> ## 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.

# API Introduction

> Corbulo REST API for programmatic access

# 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.

```bash theme={null}
curl "https://app.corbulo.dev/api/v1/projects" \
  -H "Authorization: Bearer ok_live_abc123..."
```

See the [Authentication](/api-reference/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.

```bash theme={null}
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:

```json theme={null}
{
  "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.

```bash theme={null}
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   |