> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidocsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codebases API

> List repositories in your project and find their codebase IDs

Use the Codebases API to find the repository IDs required by the [Issues API](/api/issues) and the [Scanning API](/api/scanning).

## List Codebases

```text theme={null}
GET /v1/codebase
```

The path is `codebase` (singular). Send your API key in the `x-vidoc-token` header. The route requires `issue:view`.

The API returns all codebases that are not deleted in the key's project. It does not list projects or repositories from other projects. To read another project, use a key for that project.

### Example Request

```bash theme={null}
curl --fail-with-body https://api.vidoc.dev/v1/codebase \
  -H "x-vidoc-token: $VIDOC_API_KEY"
```

### Response

`200 OK` returns a JSON array. There is no pagination and no `codebases` or `data` wrapper. A project with no codebases returns `[]`.

This example shows selected fields. The API also returns other codebase fields.

```json theme={null}
[
  {
    "id": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
    "name": "example-repository",
    "url": "https://github.com/example/example-repository",
    "defaultBranchName": "main",
    "projectId": "019f8a00-1b2c-7d3e-8f40-5a6b7c8d9e0f"
  }
]
```

| Field               | Use                                                       |
| ------------------- | --------------------------------------------------------- |
| `id`                | Use this value as `codebaseId` in issue and scan requests |
| `name`              | Repository name                                           |
| `url`               | Repository URL, when available                            |
| `defaultBranchName` | Default branch name, when available                       |
| `projectId`         | Project that owns the codebase                            |

### Read Issues for a Codebase

Copy an `id` from the list response:

```bash theme={null}
curl --fail-with-body \
  "https://api.vidoc.dev/v1/issues?codebaseId=019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a&branch=main&status=open&limit=100" \
  -H "x-vidoc-token: $VIDOC_API_KEY"
```

Use the repository's branch name in `branch`. Issue results are paginated; see [List Issues](/api/issues#list-issues) to read the remaining pages.

## Get One Codebase

```text theme={null}
GET /v1/codebase/:codebaseId
```

This route requires `issue:view` and returns one codebase object from the key's project.

```bash theme={null}
curl --fail-with-body \
  https://api.vidoc.dev/v1/codebase/019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a \
  -H "x-vidoc-token: $VIDOC_API_KEY"
```

## List Files in a Branch

```text theme={null}
GET /v1/codebase/:codebaseId/files?branchName=main
```

This route requires `issue:view`. The `branchName` parameter is required. It is named `branchName` here and `branch` in issue-list and scan-start requests.

The response has the shape `{ "files": [...] }`. Each item contains `fileId`, `filePath`, `version`, `isIndexed`, and `isScanned`. Use `fileId` to [scan specific files](/api/scanning#scan-specific-files).

## Authentication Errors

A missing key returns `401 Token is missing`. An invalid or expired key returns `401 Invalid or expired token`.

See [API Authentication](/api/authentication) for the host, header, permissions, and error format.