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

# Repositories API

> Manage repositories in a project

# Repositories API

Repositories are linked to projects for analysis. Corbulo connects to repositories via the GitHub App installation or can add public repositories directly.

***

## List Repositories

Returns all repositories linked to a project.

<CodeGroup>
  ```bash Request theme={null}
  curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
  ```

  ```json Response theme={null}
  [
    {
      "id": "f1a2b3c4-5678-9abc-def0-aabbccddeeff",
      "github_id": 123456789,
      "installation_id": 42000001,
      "owner": "corbulo",
      "name": "corbulo",
      "full_name": "corbulo/corbulo",
      "url": "https://github.com/corbulo-ai/corbulo-core",
      "description": "Technical debt intelligence platform",
      "default_branch": "main",
      "analyzers": [
        {
          "language": "node",
          "path": ".",
          "enabled": true,
          "description": "TypeScript/JavaScript project"
        },
        {
          "language": "go",
          "path": "backend-go",
          "enabled": true,
          "description": "Go backend"
        }
      ],
      "private": true,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-03-10T08:00:00Z"
    }
  ]
  ```
</CodeGroup>

### Response Fields

| Field             | Type    | Description                                   |
| ----------------- | ------- | --------------------------------------------- |
| `id`              | string  | Corbulo repository ID (UUID)                  |
| `github_id`       | integer | GitHub repository ID                          |
| `installation_id` | integer | GitHub App installation ID                    |
| `owner`           | string  | Repository owner (user or organization)       |
| `name`            | string  | Repository name                               |
| `full_name`       | string  | Full repository name (`owner/name`)           |
| `url`             | string  | GitHub repository URL                         |
| `default_branch`  | string  | Default branch name                           |
| `analyzers`       | array   | Detected static analyzers for this repository |
| `private`         | boolean | Whether the repository is private             |

***

## Link Repository

Links one or more repositories to a project. Repositories must already be synced from a GitHub App installation.

<CodeGroup>
  ```bash Request (single) theme={null}
  curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "repository_id": "f1a2b3c4-5678-9abc-def0-aabbccddeeff"
    }'
  ```

  ```bash Request (batch) theme={null}
  curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "repository_ids": [
        "f1a2b3c4-5678-9abc-def0-aabbccddeeff",
        "a2b3c4d5-6789-abcd-ef01-bbccddeeff00"
      ]
    }'
  ```

  ```json Response (201 Created) theme={null}
  {
    "status": "linked",
    "linked": 2,
    "onboarding_session_id": "c4d5e6f7-8901-2345-6789-112233445566"
  }
  ```
</CodeGroup>

### Request Body

| Field             | Type             | Required                          | Description                                                             |
| ----------------- | ---------------- | --------------------------------- | ----------------------------------------------------------------------- |
| `repository_id`   | string           | yes (if `repository_ids` not set) | Single repository ID to link                                            |
| `repository_ids`  | array of strings | yes (if `repository_id` not set)  | Multiple repository IDs to link                                         |
| `skip_onboarding` | boolean          | no                                | If `true`, skip the automatic onboarding analysis. Defaults to `false`. |

<Note>
  When repositories are linked, Corbulo automatically starts an onboarding workflow that clones the repository, detects analyzers, runs initial analysis, and generates architecture documentation. The `onboarding_session_id` can be used to track progress via the SSE event stream.
</Note>

***

## Add Public Repository

Adds a public GitHub repository to a project without requiring the GitHub App installation.

<CodeGroup>
  ```bash Request (by owner/name) theme={null}
  curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos/add-public" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "owner": "BurntSushi",
      "name": "ripgrep"
    }'
  ```

  ```bash Request (by URL) theme={null}
  curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos/add-public" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://github.com/BurntSushi/ripgrep"
    }'
  ```

  ```json Response (201 Created) theme={null}
  {
    "status": "linked",
    "repository": {
      "id": "b3c4d5e6-7890-abcd-ef01-ccddeeff0011",
      "github_id": 52505169,
      "owner": "BurntSushi",
      "name": "ripgrep",
      "full_name": "BurntSushi/ripgrep",
      "url": "https://github.com/BurntSushi/ripgrep",
      "description": "ripgrep recursively searches directories for a regex pattern",
      "default_branch": "master",
      "analyzers": [],
      "private": false,
      "created_at": "2026-03-10T12:00:00Z",
      "updated_at": "2026-03-10T12:00:00Z"
    },
    "onboarding_session_id": "d5e6f7a8-9012-3456-7890-223344556677"
  }
  ```
</CodeGroup>

### Request Body

| Field             | Type    | Required                        | Description                                                |
| ----------------- | ------- | ------------------------------- | ---------------------------------------------------------- |
| `url`             | string  | yes (if `owner`/`name` not set) | GitHub repository URL                                      |
| `owner`           | string  | yes (if `url` not set)          | Repository owner                                           |
| `name`            | string  | yes (if `url` not set)          | Repository name                                            |
| `skip_onboarding` | boolean | no                              | If `true`, skip automatic onboarding. Defaults to `false`. |

***

## Unlink Repository

Removes a repository from a project. This does not delete analysis data.

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos/f1a2b3c4-5678-9abc-def0-aabbccddeeff" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
  ```
</CodeGroup>

Returns `204 No Content` on success.

***

## List Available Repositories

Returns repositories accessible via the GitHub App installation that are not yet linked to the project. Use this to present a selection UI when adding repositories.

<CodeGroup>
  ```bash Request theme={null}
  curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/repos/available" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
  ```

  ```json Response theme={null}
  [
    {
      "id": "a2b3c4d5-6789-abcd-ef01-bbccddeeff00",
      "github_id": 987654321,
      "installation_id": 0,
      "owner": "corbulo",
      "name": "docs",
      "full_name": "corbulo/docs",
      "url": "https://github.com/corbulo-ai/docs",
      "description": "Corbulo documentation",
      "default_branch": "main",
      "analyzers": [],
      "private": false,
      "created_at": "2026-02-01T08:00:00Z",
      "updated_at": "2026-02-01T08:00:00Z"
    }
  ]
  ```
</CodeGroup>

***

## Sync GitHub Installations

Syncs GitHub App installations and their repositories. Call this after installing or reconfiguring the GitHub App to update the available repositories.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://app.corbulo.dev/api/v1/github/installations/sync" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "installation_ids": [42000001]
    }'
  ```

  ```json Response theme={null}
  [
    {
      "id": "e6f7a8b9-0123-4567-8901-ddeeff001122",
      "provider": "github",
      "installation_id": 42000001,
      "account_login": "corbulo",
      "account_type": "Organization",
      "status": "active",
      "created_at": "2026-01-10T08:00:00Z"
    }
  ]
  ```
</CodeGroup>

### Request Body

| Field              | Type              | Required | Description                                                                                                    |
| ------------------ | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `installation_ids` | array of integers | no       | Specific installation IDs to sync. If omitted, syncs all installations associated with the authenticated user. |