API Introduction

The Corbulo API provides programmatic access to code health assessments, PR analysis, architecture insights, and project management. All endpoints return JSON and follow standard REST conventions.

Base URL

https://app.corbulo.dev/api/v1

For self-hosted deployments:

https://your-corbulo.dev/api/v1

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header.

curl "https://app.corbulo.dev/api/v1/projects" \
  -H "Authorization: Bearer ok_live_abc123..."

See the Authentication page for details on creating and managing API keys.

Request/Response Format

All request and response bodies use JSON. Include Content-Type: application/json for POST, PATCH, and PUT requests.

curl "https://app.corbulo.dev/api/v1/projects" \
  -H "Authorization: Bearer ok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "key": "my-project"}'

Error Responses

Errors return a JSON object with an error field:

{
  "error": "project not found"
}

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request — invalid input or missing required fields
401	Unauthorized — missing or invalid API key
403	Forbidden — key lacks access to the requested resource
404	Not Found
409	Conflict — e.g., removing the last project owner
500	Internal Server Error

Pagination

List endpoints use limit and offset query parameters for pagination.

GET /api/v1/projects/{id}/health/assessments?limit=20&offset=0

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

Paginated responses include total_count (or total), limit, and offset fields alongside the items array.

API Endpoints Overview

Projects

Method	Endpoint	Description
`GET`	`/api/v1/projects`	List projects
`POST`	`/api/v1/projects`	Create project
`GET`	`/api/v1/projects/{id}`	Get project
`PATCH`	`/api/v1/projects/{id}`	Update project
`DELETE`	`/api/v1/projects/{id}`	Delete project
`GET`	`/api/v1/projects/{id}/members`	List members
`POST`	`/api/v1/projects/{id}/invitations`	Invite member
`PATCH`	`/api/v1/projects/{id}/members/{userId}`	Update member role
`DELETE`	`/api/v1/projects/{id}/members/{userId}`	Remove member

Code Health

Method	Endpoint	Description
`GET`	`/api/v1/projects/{id}/health`	Get health dashboard
`GET`	`/api/v1/projects/{id}/health/assessments`	List assessments
`GET`	`/api/v1/projects/{id}/health/assessments/{assessmentId}`	Get assessment
`POST`	`/api/v1/projects/{id}/health/trigger`	Trigger assessment
`GET`	`/api/v1/projects/{id}/health/drift-alerts`	List drift alerts
`POST`	`/api/v1/projects/{id}/health/drift-alerts/{alertId}/dismiss`	Dismiss drift alert
`GET`	`/api/v1/projects/{id}/health/categories`	List health categories

Analysis

Method	Endpoint	Description
`GET`	`/api/v1/projects/{id}/analysis/issues`	List issues
`GET`	`/api/v1/projects/{id}/analysis/issues/{issueId}`	Get issue
`GET`	`/api/v1/projects/{id}/analysis/issues/stats`	Issue statistics
`POST`	`/api/v1/projects/{id}/analysis/issues/{issueId}/dismiss`	Dismiss issue
`POST`	`/api/v1/projects/{id}/analysis/issues/{issueId}/restore`	Restore dismissed issue
`GET`	`/api/v1/projects/{id}/analysis/dismiss-rules`	List dismiss rules
`POST`	`/api/v1/projects/{id}/analysis/dismiss-rules`	Create dismiss rule
`DELETE`	`/api/v1/projects/{id}/analysis/dismiss-rules/{ruleId}`	Delete dismiss rule

Pull Requests

Method	Endpoint	Description
`GET`	`/api/v1/projects/{id}/pr-analyses`	List PR analyses
`GET`	`/api/v1/projects/{id}/pr-analyses/{analysisId}`	Get PR analysis
`GET`	`/api/v1/projects/{id}/pr-analyses/stats`	PR statistics
`GET`	`/api/v1/projects/{id}/repos/{repoId}/prs/{number}/analysis`	Get latest analysis for PR
`POST`	`/api/v1/projects/{id}/repos/{repoId}/prs/{number}/analyze`	Trigger PR analysis

Architecture

Method	Endpoint	Description
`GET`	`/api/v1/projects/{id}/architecture/overview`	Architecture overview
`GET`	`/api/v1/projects/{id}/architecture/reviews`	List architecture reviews
`GET`	`/api/v1/projects/{id}/architecture/reviews/{reviewId}`	Get architecture review
`POST`	`/api/v1/projects/{id}/architecture/reviews/trigger`	Trigger architecture review
`GET`	`/api/v1/projects/{id}/architecture/conventions`	List conventions
`PATCH`	`/api/v1/projects/{id}/architecture/conventions/{conventionId}`	Update convention status
`POST`	`/api/v1/projects/{id}/architecture/conventions/detect`	Trigger convention detection
`GET`	`/api/v1/projects/{id}/architecture/adrs`	List ADRs
`POST`	`/api/v1/projects/{id}/architecture/adrs`	Create ADR
`GET`	`/api/v1/projects/{id}/architecture/adrs/{adrId}`	Get ADR
`PATCH`	`/api/v1/projects/{id}/architecture/adrs/{adrId}`	Update ADR

Repositories

Method	Endpoint	Description
`GET`	`/api/v1/projects/{id}/repos`	List project repositories
`POST`	`/api/v1/projects/{id}/repos`	Link repository to project
`DELETE`	`/api/v1/projects/{id}/repos/{repoId}`	Unlink repository
`GET`	`/api/v1/projects/{id}/repos/available`	List available repositories
`POST`	`/api/v1/github/installations/sync`	Sync GitHub installations

​API Introduction

​Base URL

​Authentication

​Request/Response Format

​Error Responses

​HTTP Status Codes

​Pagination

​API Endpoints Overview

​Projects

​Code Health

​Analysis

​Pull Requests

​Architecture

​Repositories