🤖 CI/CD Fixer Agent API Documentation

Version: 2.0.0
Generated: August 25, 2025
Status: 🚀 LIVE IN PRODUCTION - 17 failures processed, 1 repository analyzed

🤖 **Intelligent CI/CD Failure Analysis & Fixing Platform**

**PRODUCTION VALIDATED SYSTEM** processing real GitHub Actions failures with AI-powered analysis.

## 🚀 **Key Features**

* **Portia AI Framework**: Structured plan-based analysis workflows (7 custom CI/CD tools)
* **Google Gemini 2.5 Pro**: Advanced AI error analysis and fix generation (100% operational)
* **GitHub Integration**: Real-time webhook processing and API integration (tested with real data)
* **PostgreSQL Database**: Complete audit trails and analytics storage (Supabase cloud)
* **ML Analytics**: Pattern recognition, success prediction, and learning (active)
* **Human Approval**: Safe fix application with approval workflows (41.18% approval rate)

## 🔧 **Core Capabilities**

* Analyze failed GitHub Actions workflows (17 failures processed)
* Generate intelligent fix suggestions (100% generation rate)
* Track fix effectiveness over time (comprehensive metrics)
* Learn from repository-specific patterns (chaitanyak175/ci-cd-test-repo)
* Provide comprehensive analytics and insights (live dashboard)

## 📊 **Analytics & Learning**

* Pattern recognition across repositories (multi-language support: Python, JavaScript, Docker)
* ML-based success prediction for fixes (confidence scoring up to 82.38%)
* Repository-specific intelligence (individual profiles)
* Historical analysis and trend detection (real production data)
* Enhanced fix generation with ML insights (context-aware)

---

**Base URL**: `https://ci-cd-fixer-agent-backend.onrender.com` (🚀 **LIVE PRODUCTION**) | `http://localhost:8000` (Development)

🔗 Base URLs

🚀 Production: https://ci-cd-fixer-agent-backend.onrender.com ✅ LIVE & OPERATIONAL
Development: http://localhost:8000

📊 Production Status: 17 failures processed | 1 repository analyzed | All services healthy

🔐 Authentication

Currently, this API does not require authentication for development. For production deployment, implement:

Authorization: Bearer <your_jwt_token>

📂 Untagged

📖 Root

Endpoint:

GET /

Root endpoint with API information.

Responses:

200 - Successful Response

➕ Handle Webhook

Endpoint:

POST /webhook

Handle GitHub webhook for workflow_run events.

Responses:

200 - Successful Response

➕ Analyze With Portia

Endpoint:

POST /analyze/portia

Analyze CI/CD failure using Portia's plan-based approach.

Request Body:

{
    // Request body based on schema
}

Responses:

200 - Successful Response

422 - Validation Error

📖 Get Pending Fixes

Endpoint:

GET /fixes

Get all pending fixes that require human approval.

Responses:

200 - Successful Response

➕ Approve Fix

Endpoint:

POST /fixes/{fix_id}/approve

Approve a suggested fix.

Path Parameters:

fix_id (required) —

Responses:

200 - Successful Response

422 - Validation Error

➕ Reject Fix

Endpoint:

POST /fixes/{fix_id}/reject

Reject a suggested fix.

Path Parameters:

fix_id (required) —

Responses:

200 - Successful Response

422 - Validation Error

➕ Respond To Clarification

Endpoint:

POST /plans/{plan_run_id}/clarifications/{clarification_id}

Respond to a Portia plan clarification.

Request Body:

{
    // Request body based on schema
}

Path Parameters:

plan_run_id (required) —
clarification_id (required) —

Responses:

200 - Successful Response

422 - Validation Error

📖 Get Failure Patterns

Endpoint:

GET /analytics/patterns

Get pattern analysis of workflow failures over the specified period.

Query Parameters:

days_back (integer, default=30) —

Responses:

200 - Successful Response

422 - Validation Error

📖 Get Fix Effectiveness

Endpoint:

GET /analytics/effectiveness

Get statistics on fix effectiveness and approval rates.

Responses:

200 - Successful Response

📖 Get Repository Profile

Endpoint:

GET /analytics/repository/{owner}/{repo}

Get detailed analytics profile for a specific repository.

Path Parameters:

owner (required) —
repo (required) —

Responses:

200 - Successful Response

422 - Validation Error

📖 Get Analytics Dashboard

Endpoint:

GET /analytics/dashboard

Get comprehensive analytics dashboard data.

Responses:

200 - Successful Response

➕ Find Similar Fixes

Endpoint:

POST /analytics/ml/similar-fixes

Find similar fixes using ML-based pattern recognition.

Request Body:

{
    // Request body based on schema
}

Responses:

200 - Successful Response

422 - Validation Error

➕ Predict Fix Success

Endpoint:

POST /analytics/ml/predict-success

Predict the success probability of a proposed fix.

Request Body:

{
    // Request body based on schema
}

Responses:

200 - Successful Response

422 - Validation Error

➕ Generate Enhanced Fix

Endpoint:

POST /analytics/ml/generate-enhanced-fix

Generate an enhanced fix recommendation using ML insights.

Request Body:

{
    // Request body based on schema
}

Responses:

200 - Successful Response

422 - Validation Error

➕ Learn From Feedback

Endpoint:

POST /analytics/ml/learn-from-feedback

Learn from user feedback to improve future recommendations.

Request Body:

{
    // Request body based on schema
}

Responses:

200 - Successful Response

422 - Validation Error

📖 Get Pattern Insights

Endpoint:

GET /analytics/ml/pattern-insights

Get insights from learned patterns and ML models.

Responses:

200 - Successful Response

📖 Get Model Performance

Endpoint:

GET /analytics/ml/model-performance

Get performance metrics of the ML models.

Responses:

200 - Successful Response

📂 System

📖 System Health Check

Endpoint:

GET /health

Check the overall health and status of all system components.

Returns the status of:

Database: PostgreSQL connection status
GitHub API: GitHub service availability
Gemini AI: Google Gemini API availability

This endpoint is useful for monitoring and ensuring all services are operational.

Responses:

200 - System is healthy

{
    "status": "healthy",
    "timestamp": "2025-08-23T10:00:00.000000",
    "services": {
        "database": "connected",
        "github_api": "available",
        "gemini_api": "available"
    }
}

500 - System health check failed

📂 Analysis

➕ Trigger Manual Analysis

Endpoint:

POST /analyze

Manually trigger CI/CD failure analysis for a specific GitHub Actions workflow run.

This endpoint allows you to analyze any workflow run by providing:

owner: GitHub repository owner/organization
repo: Repository name
run_id: GitHub Actions workflow run ID

The analysis will be processed asynchronously and stored in the database for later retrieval. Use this when you want to analyze a specific failed workflow run manually.

Request Body:

{
    // Request body based on schema
}

Responses:

200 - Analysis triggered successfully

{
    "message": "Analysis triggered successfully",
    "failure_id": "7",
    "owner": "microsoft",
    "repo": "vscode",
    "run_id": 17152193292
}

400 - Invalid request parameters

500 - Internal server error

422 - Validation Error

🧪 TESTED ENDPOINTS WITH LIVE RESPONSES

All endpoints tested on August 25, 2025 against the live production system.

🔍 System Health & Status

Health Check

GET /health

Live Response:

{
    "status": "healthy",
    "timestamp": "2025-08-25T08:15:16.896858",
    "services": {
        "database": "connected",
        "github_api": "available",
        "gemini_api": "available"
    }
}

📊 Failures & Analytics

Get All Failures

GET /failures

Live Response:

{
    "failures": [
        {
            "id": 95,
            "repo_name": "ci-cd-test-repo",
            "owner": "chaitanyak175",
            "workflow_name": "🔴 Broken Python Advanced CI",
            "run_id": 17199274412,
            "status": "failed",
            "conclusion": "failure",
            "suggested_fix": "**Description:** Fix Docker build configuration...",
            "fix_status": "pending",
            "created_at": "2025-08-25T04:44:00.605028"
        }
    ],
    "count": 17
}

Analytics Dashboard

GET /analytics/dashboard

Live Response:

{
    "message": "Analytics dashboard generated",
    "dashboard": {
        "failure_patterns": {
            "total_runs": 17,
            "patterns": {
                "most_failing_repos": {
                    "chaitanyak175/ci-cd-test-repo": 17
                },
                "language_distribution": {
                    "python": 4,
                    "javascript": 4,
                    "docker": 2
                }
            }
        },
        "fix_effectiveness": {
            "overall_stats": {
                "total_fixes": 17,
                "approved_fixes": 7,
                "approval_rate": 41.18,
                "pending_rate": 58.82
            }
        }
    }
}

🤖 Machine Learning Endpoints

Predict Fix Success

POST /analytics/ml/predict-success
Content-Type: application/json

{
  "error_log": "npm install failed",
  "suggested_fix": "use --legacy-peer-deps"
}

Live Response:

{
    "message": "Fix success prediction completed",
    "prediction": {
        "predicted_success_rate": 0.8238,
        "confidence": 0.76,
        "factors": {
            "similarity_match": 1.0,
            "repo_history": 0.5,
            "fix_complexity": 0.994,
            "error_type_reliability": 0.8
        },
        "recommendations": [
            "✅ High success probability - safe to apply automatically"
        ],
        "similar_fixes_found": 4
    }
}

ML Model Performance

GET /analytics/ml/model-performance

Live Response:

{
    "message": "ML model performance analysis completed",
    "performance": {
        "data_summary": {
            "total_fixes_last_30_days": 17,
            "approved_fixes": 4,
            "approval_rate": 0.23529411764705882
        },
        "model_capabilities": {
            "similarity_matching": "✅ Operational",
            "success_prediction": "✅ Operational",
            "pattern_learning": "✅ Operational",
            "adaptive_improvement": "✅ Operational"
        }
    }
}

🔧 Fix Management

Get Pending Fixes

GET /fixes

Live Response:

{
    "pending_fixes": [
        {
            "id": 95,
            "repo_name": "ci-cd-test-repo",
            "owner": "chaitanyak175",
            "workflow_name": "🔴 Broken Python Advanced CI",
            "suggested_fix": "**Description:** Fix Docker build configuration...",
            "fix_status": "pending",
            "created_at": "2025-08-25T04:44:00.605028"
        }
    ]
}

🌐 All Available Endpoints

The production system includes 24 fully functional endpoints:

GET    /                                                    # API welcome
GET    /health                                             # Health check
GET    /ping                                               # Simple ping
POST   /webhook                                            # GitHub webhooks
POST   /webhook/test                                       # Test webhooks
POST   /analyze                                            # Manual analysis
POST   /analyze/portia                                     # Portia analysis
GET    /failures                                           # All failures
GET    /failures/{failure_id}                              # Specific failure
GET    /fixes                                              # Pending fixes
POST   /fixes/{fix_id}/approve                             # Approve fix
POST   /fixes/{fix_id}/reject                              # Reject fix
POST   /fixes/{fix_id}/apply                               # Apply fix
GET    /fixes/{fix_id}/status                              # Fix status
GET    /analytics/dashboard                                # Dashboard
GET    /analytics/patterns                                 # Pattern analysis
GET    /analytics/effectiveness                            # Fix effectiveness
GET    /analytics/repository/{owner}/{repo}                # Repo analytics
POST   /analytics/ml/predict-success                       # ML prediction
GET    /analytics/ml/model-performance                     # ML performance
POST   /analytics/ml/similar-fixes                         # Similar fixes
POST   /analytics/ml/pattern-insights                      # Pattern insights
POST   /analytics/ml/generate-enhanced-fix                 # Enhanced fixes
POST   /analytics/ml/learn-from-feedback                   # Learn feedback
GET    /plans/{plan_run_id}/clarifications/{clarification_id}  # Clarifications

📊 OpenAPI Schema

Developers can access the machine-readable schema:

GET /openapi.json

This schema can be imported into Postman, Insomnia, Swagger Editor, or GitHub Copilot for autocompletion and testing.

📖 Interactive Documentation

Swagger UI: GET /docs - Interactive API testing interface
ReDoc: GET /redoc - Clean documentation interface

⚠️ Error Format

All error responses follow this format:

{
    "detail": "Error message describing what went wrong"
}

Common HTTP status codes:

200 - Success
400 - Bad Request (invalid parameters)
401 - Unauthorized (authentication required)
404 - Not Found (resource doesn't exist)
422 - Validation Error (invalid request body)
500 - Internal Server Error

Generated automatically from OpenAPI schema ✨

FilesExpand file tree

API_DOCUMENTATION.md

Latest commit

History

API_DOCUMENTATION.md

File metadata and controls

🤖 CI/CD Fixer Agent API Documentation

🔗 Base URLs

🔐 Authentication

📂 Untagged

📖 Root

➕ Handle Webhook

➕ Analyze With Portia

📖 Get Pending Fixes

➕ Approve Fix

➕ Reject Fix

➕ Respond To Clarification

📖 Get Failure Patterns

📖 Get Fix Effectiveness

📖 Get Repository Profile

📖 Get Analytics Dashboard

➕ Find Similar Fixes

➕ Predict Fix Success

➕ Generate Enhanced Fix

➕ Learn From Feedback

📖 Get Pattern Insights

📖 Get Model Performance

📂 System

📖 System Health Check

📂 Analysis

➕ Trigger Manual Analysis

🧪 TESTED ENDPOINTS WITH LIVE RESPONSES

🔍 System Health & Status

Health Check

📊 Failures & Analytics

Get All Failures

Analytics Dashboard

🤖 Machine Learning Endpoints

Predict Fix Success

ML Model Performance

🔧 Fix Management

Get Pending Fixes

🌐 All Available Endpoints

📊 OpenAPI Schema

📖 Interactive Documentation

⚠️ Error Format