Pull Requests API

Corbulo analyzes pull requests for code quality issues, merge readiness, scope drift, health impact, and conflicts with other open PRs. Analyses run automatically on PR events or can be triggered manually.

List PR Analyses

Returns paginated PR analyses for a project.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/pr-analyses?limit=20&offset=0" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "analyses": [
    {
      "id": "c8d9e0f1-2345-6789-abcd-ef0123456789",
      "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
      "repository_id": "f1a2b3c4-5678-9abc-def0-aabbccddeeff",
      "pr_number": 142,
      "head_sha": "a3f8e2d1b4c5",
      "classification": {
        "primary_intent": "feature",
        "secondary_intents": ["testing"],
        "change_categories": ["backend", "api"],
        "risk_signals": ["new_dependency"],
        "summary": "Adds user notification preferences API with email and in-app channels"
      },
      "merge_readiness": {
        "status": "needs_review",
        "blocking_count": 0,
        "advisory_count": 3,
        "info_count": 1,
        "confidence": 0.85
      },
      "status": "completed",
      "created_at": "2026-03-10T09:15:00Z",
      "completed_at": "2026-03-10T09:17:32Z"
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Query Parameters

Parameter	Type	Description	Default
`limit`	integer	Items per page (max 100)	20
`offset`	integer	Number of items to skip	0

Get PR Analysis

Returns a full PR analysis by ID, including all analysis sections.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/pr-analyses/c8d9e0f1-2345-6789-abcd-ef0123456789" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "id": "c8d9e0f1-2345-6789-abcd-ef0123456789",
  "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
  "repository_id": "f1a2b3c4-5678-9abc-def0-aabbccddeeff",
  "pr_number": 142,
  "head_sha": "a3f8e2d1b4c5",
  "classification": {
    "primary_intent": "feature",
    "secondary_intents": ["testing"],
    "change_categories": ["backend", "api"],
    "risk_signals": ["new_dependency"],
    "summary": "Adds user notification preferences API with email and in-app channels"
  },
  "merge_readiness": {
    "status": "needs_review",
    "blocking_count": 0,
    "advisory_count": 3,
    "info_count": 1,
    "confidence": 0.85
  },
  "health_impact": {
    "overall_delta": -1,
    "issues_added": 3,
    "issues_fixed": 1,
    "impact_rating": "degrading"
  },
  "health_projection": {
    "current_overall": 78.5,
    "projected_overall": 77.2,
    "overall_delta": -1.3,
    "current_grade": "B",
    "projected_grade": "B",
    "category_deltas": [
      {
        "category": "security",
        "current_score": 92.0,
        "projected_score": 92.0,
        "delta": 0.0,
        "issues_in_pr": 0
      },
      {
        "category": "code_smell",
        "current_score": 71.0,
        "projected_score": 68.5,
        "delta": -2.5,
        "issues_in_pr": 2
      }
    ],
    "issues_added": 3,
    "issues_fixed": 1,
    "impact_rating": "degrading"
  },
  "scope_drift": [
    {
      "description": "Unrelated logging refactor in auth middleware",
      "reason": "Changes to auth/middleware.go are outside the notification feature scope",
      "files": ["src/auth/middleware.ts"]
    }
  ],
  "impact_zones": [
    {
      "name": "Notification API",
      "risk": "medium",
      "scope_classification": "core",
      "summary": "New notification preferences endpoints and data model",
      "intent": "feature",
      "files": [
        {
          "path": "src/notifications/handler.ts",
          "additions": 85,
          "deletions": 0
        },
        {
          "path": "src/notifications/service.ts",
          "additions": 120,
          "deletions": 0
        }
      ]
    }
  ],
  "conflicts": {
    "conflicts": [
      {
        "pr_number": 139,
        "title": "Refactor user settings page",
        "overlapping_files": ["src/settings/preferences.ts"],
        "semantic_conflict": "Both PRs modify the preferences data model",
        "resolution_suggestion": "Merge #139 first, then rebase this PR"
      }
    ],
    "checked_prs": [138, 139, 140, 141],
    "summary": "1 potential conflict detected with PR #139"
  },
  "stacked_prs": {
    "is_stacked": false,
    "stacked_prs": [],
    "parent_prs": [],
    "child_prs": [],
    "summary": "This PR is not part of a stack"
  },
  "analysis_run_id": "d1e2f3a4-5678-9abc-def0-112233445566",
  "status": "completed",
  "created_at": "2026-03-10T09:15:00Z",
  "started_at": "2026-03-10T09:15:01Z",
  "completed_at": "2026-03-10T09:17:32Z"
}

Response Fields

Field	Type	Description
`classification`	object	PR intent, change categories, and risk signals
`merge_readiness`	object	Merge status (`ready`, `needs_review`, `blocked`), issue counts, confidence
`health_impact`	object	Net issue delta and overall impact rating
`health_projection`	object	Per-category score projections showing how the PR would affect health scores
`graph_impact`	object	Impact analysis of changed symbols on the codebase graph
`scope_drift`	array	Detected changes outside the PR’s stated scope
`impact_zones`	array	Logical groupings of changes with risk levels
`conflicts`	object	Detected conflicts with other open PRs
`stacked_prs`	object	Stacked PR detection (parent/child relationships)
`status`	string	`pending`, `running`, `completed`, or `failed`

Merge Readiness Status

Status	Meaning
`ready`	No blocking or advisory issues found
`needs_review`	Advisory issues found but no blockers
`blocked`	Blocking issues that should be resolved before merging

Get Latest Analysis for PR

Returns the most recent analysis for a specific pull request.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos/f1a2b3c4-5678-9abc-def0-aabbccddeeff/prs/142/analysis" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

Returns the same response format as Get PR Analysis. Returns 404 if no analysis exists for the PR.

Trigger PR Analysis

Starts a new analysis for a pull request. The analysis runs asynchronously.

curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos/f1a2b3c4-5678-9abc-def0-aabbccddeeff/prs/142/analyze" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "head_sha": "a3f8e2d1b4c5"
  }'

{
  "id": "e2f3a4b5-6789-0abc-def0-112233445566",
  "status": "pending",
  "workflow_id": "pr-analysis-b3d7f1a2-f1a2b3c4-142",
  "pr_number": 142
}

Request Body

Field	Type	Required	Description
`head_sha`	string	no	HEAD commit SHA. If omitted, uses the SHA from the most recently synced PR metadata.

The analysis runs asynchronously. Poll the Get PR Analysis endpoint or use the Get Latest Analysis for PR endpoint to check for completion.

Get PR Statistics

Returns aggregate statistics for PR analyses in a project.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/pr-analyses/stats" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "total_count": 156,
  "completed_count": 148,
  "failed_count": 3,
  "running_count": 2,
  "blocked_count": 12,
  "needs_review_count": 45,
  "ready_count": 91,
  "avg_duration_seconds": 142.5
}

Query Parameters

Parameter	Type	Description
`since`	string	ISO 8601 timestamp. Only count analyses created after this time.

# Stats for the last 30 days
curl "https://app.corbulo.dev/api/v1/projects/{id}/pr-analyses/stats?since=2026-02-08T00:00:00Z" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

​Pull Requests API

​List PR Analyses

​Query Parameters

​Get PR Analysis

​Response Fields

​Merge Readiness Status

​Get Latest Analysis for PR

​Trigger PR Analysis

​Request Body

​Get PR Statistics

​Query Parameters

Pull Requests API

List PR Analyses

Query Parameters

Get PR Analysis

Response Fields

Merge Readiness Status

Get Latest Analysis for PR

Trigger PR Analysis

Request Body

Get PR Statistics

Query Parameters