> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octokraft.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Pull Requests API
> Access PR analysis results
# 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.
```bash Request theme={null}
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..."
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
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..."
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
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](#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.
```bash Request theme={null}
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"
}'
```
```json Response (201 Created) theme={null}
{
"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](#get-pr-analysis) endpoint or use the [Get Latest Analysis for PR](#get-latest-analysis-for-pr) endpoint to check for completion.
***
## Get PR Statistics
Returns aggregate statistics for PR analyses in a project.
```bash Request theme={null}
curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/pr-analyses/stats" \
-H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```
```json Response theme={null}
{
"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. |
```bash theme={null}
# 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..."
```