POST /analyze

Submit a Jenkins job build for AI-powered failure analysis. Supports both async (default) and sync modes.

Endpoint

POST /analyze

Modes

Async Mode (Default)

Returns immediately with a job_id for polling or callback delivery. Status Code: 202 Accepted

Sync Mode

Blocks until analysis completes and returns the full result. Status Code: 200 OK Query Parameter: ?sync=true

Request Body

job_name

string

required

Jenkins job name. Can include folders like folder/subfolder/job-name.

build_number

integer

required

Build number to analyze.

callback_url

string (URL)

Optional callback URL for async results delivery. Overrides CALLBACK_URL env var.

callback_headers

object

Optional headers to include in callback request. Overrides CALLBACK_HEADERS env var.Example: {"Authorization": "Bearer token123"}

jenkins_url

string

Jenkins server URL. Overrides JENKINS_URL env var.

jenkins_user

string

Jenkins username. Overrides JENKINS_USER env var.

jenkins_password

string

Jenkins password or API token. Overrides JENKINS_PASSWORD env var.

jenkins_ssl_verify

boolean

Enable/disable SSL verification for Jenkins. Overrides JENKINS_SSL_VERIFY env var.

tests_repo_url

string (URL)

URL of the tests repository for code context. Overrides TESTS_REPO_URL env var.

ai_provider

string

AI provider to use: claude, gemini, or cursor. Overrides AI_PROVIDER env var.

ai_model

string

AI model to use. Overrides AI_MODEL env var.Examples: claude-opus-4-20250514, gemini-2.0-flash-exp

ai_cli_timeout

integer

AI CLI timeout in minutes. Must be greater than 0. Overrides AI_CLI_TIMEOUT env var.

enable_jira

boolean

Enable Jira bug search for PRODUCT BUG failures. Defaults to true when Jira is configured.

jira_url

string

Jira instance URL. Overrides JIRA_URL env var.

jira_email

string

Jira Cloud email for authentication. Overrides JIRA_EMAIL env var.

jira_api_token

string

Jira Cloud API token. Overrides JIRA_API_TOKEN env var.

jira_pat

string

Jira Server/DC personal access token. Overrides JIRA_PAT env var.

jira_project_key

string

Jira project key to scope searches (e.g., PROJ). Overrides JIRA_PROJECT_KEY env var.

jira_ssl_verify

boolean

Enable/disable SSL verification for Jira. Overrides JIRA_SSL_VERIFY env var.

jira_max_results

integer

Maximum Jira search results to retrieve. Must be greater than 0. Overrides JIRA_MAX_RESULTS env var.

Response (Async Mode - 202)

status

string

Always "queued" for async requests.

job_id

string

Unique identifier for polling or retrieving results.

message

string

Status message with next steps (callback or polling instructions).

base_url

string

Base URL of the service (extracted from request headers).

result_url

string

Full URL to retrieve results: GET /results/{job_id}

html_report_url

string

Full URL to view HTML report: GET /results/{job_id}.html

Response (Sync Mode - 200)

job_id

string

Unique identifier for the analysis.

job_name

string

Jenkins job name.

build_number

integer

Jenkins build number.

jenkins_url

string

Full URL to the Jenkins build.

status

string

Always "completed" for successful sync requests.

summary

string

Summary of analysis findings.

ai_provider

string

AI provider used for analysis.

ai_model

string

AI model used for analysis.

failures

array

Array of analyzed test failures.

Show FailureAnalysis object

test_name

string

Name of the failed test.

error

string

Error message or exception.

analysis

object

Structured AI analysis.

Show AnalysisDetail object

classification

string

CODE ISSUE or PRODUCT BUG

affected_tests

array

List of affected test names.

details

string

Detailed analysis text.

code_fix

object

Code fix suggestion (only present for CODE ISSUE).

Show CodeFix object

file

string

File path to fix.

line

string

Line number.

change

string

Specific code change.

product_bug_report

object

Product bug report (only present for PRODUCT BUG).

Show ProductBugReport object

title

string

Concise bug title.

severity

string

Bug severity: critical/high/medium/low.

component

string

Affected component.

description

string

What product behavior is broken.

evidence

string

Relevant log snippets.

jira_search_keywords

array

AI-suggested keywords for Jira search.

jira_matches

array

Matched Jira issues (populated when Jira integration is enabled).

Show JiraMatch object

key

string

Jira issue key (e.g., PROJ-123).

summary

string

Issue summary/title.

status

string

Issue status (e.g., Open, In Progress).

priority

string

Issue priority (e.g., High, Medium).

url

string

Full URL to the Jira issue.

score

number

AI-calculated relevance score (0.0-1.0).

child_job_analyses

array

Analyses of failed child jobs in pipeline builds.

Show ChildJobAnalysis object

job_name

string

Name of the child job.

build_number

integer

Build number of the child job.

jenkins_url

string

URL of the child job build.

summary

string

Summary of the child job failure analysis.

failures

array

List of FailureAnalysis objects for this child job.

failed_children

array

Nested ChildJobAnalysis objects (recursive).

note

string

Additional notes (e.g., “max depth reached”).

base_url

string

Base URL of the service.

result_url

string

Full URL to retrieve this result.

html_report_url

string

Full URL to view HTML report.

Examples

Async Request

curl -X POST https://your-instance.com/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "job_name": "my-pipeline",
    "build_number": 123
  }'

Response (202):

{
  "status": "queued",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Analysis job queued. Poll /results/550e8400-e29b-41d4-a716-446655440000 for status.",
  "base_url": "https://your-instance.com",
  "result_url": "https://your-instance.com/results/550e8400-e29b-41d4-a716-446655440000",
  "html_report_url": "https://your-instance.com/results/550e8400-e29b-41d4-a716-446655440000.html"
}

Sync Request

curl -X POST "https://your-instance.com/analyze?sync=true" \
  -H "Content-Type: application/json" \
  -d '{
    "job_name": "my-pipeline",
    "build_number": 123,
    "ai_provider": "claude",
    "ai_model": "claude-opus-4-20250514"
  }'

Response (200):

{
  "job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "job_name": "my-pipeline",
  "build_number": 123,
  "jenkins_url": "https://jenkins.example.com/job/my-pipeline/123/",
  "status": "completed",
  "summary": "Analyzed 5 test failures (3 unique errors). 2 CODE ISSUES, 1 PRODUCT BUG.",
  "ai_provider": "claude",
  "ai_model": "claude-opus-4-20250514",
  "failures": [
    {
      "test_name": "com.example.UserServiceTest.testLogin",
      "error": "NullPointerException: username cannot be null",
      "analysis": {
        "classification": "CODE ISSUE",
        "affected_tests": ["com.example.UserServiceTest.testLogin"],
        "details": "The test is failing due to a missing null check in the login method.",
        "code_fix": {
          "file": "src/main/java/com/example/UserService.java",
          "line": "42",
          "change": "Add null check: if (username == null) throw new IllegalArgumentException()"
        }
      }
    }
  ],
  "child_job_analyses": [],
  "base_url": "https://your-instance.com",
  "result_url": "https://your-instance.com/results/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "html_report_url": "https://your-instance.com/results/7c9e6679-7425-40de-944b-e07fc1f90ae7.html"
}

With Callback

curl -X POST https://your-instance.com/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "job_name": "my-pipeline",
    "build_number": 123,
    "callback_url": "https://your-app.com/webhook",
    "callback_headers": {
      "Authorization": "Bearer secret-token"
    }
  }'

When analysis completes, the full result (same structure as sync mode 200 response) will be POST-ed to the callback URL with the specified headers.

Error Responses

Missing AI Configuration

Status Code: 400 Bad Request

{
  "detail": "No AI provider configured. Set AI_PROVIDER env var or pass ai_provider in request body. Valid providers: claude, cursor, gemini"
}

Missing Jenkins Configuration

Status Code: 400 Bad Request

{
  "detail": "No AI model configured. Set AI_MODEL env var or pass ai_model in request body."
}

Endpoints

Models

Endpoint

Modes

Async Mode (Default)

Sync Mode

Request Body

Response (Async Mode - 202)

Response (Sync Mode - 200)

Examples

Async Request

Sync Request

With Callback

Error Responses

Missing AI Configuration

Missing Jenkins Configuration

See Also

Build docs developers (and LLMs) love

Endpoints

Models

​Endpoint

​Modes

​Async Mode (Default)

​Sync Mode

​Request Body

​Response (Async Mode - 202)

​Response (Sync Mode - 200)

​Examples

​Async Request

​Sync Request

​With Callback

​Error Responses

​Missing AI Configuration

​Missing Jenkins Configuration

​See Also

Build docs developers (and LLMs) love

Endpoint

Modes

Async Mode (Default)

Sync Mode

Request Body

Response (Async Mode - 202)

Response (Sync Mode - 200)

Examples

Async Request

Sync Request

With Callback

Error Responses

Missing AI Configuration

Missing Jenkins Configuration

See Also