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

# API conventions

> Base URLs and regions, identifiers, pagination, errors, rate limits, asynchronous operations, and versioning that every CodeRabbit API operation shares.

This page covers the rules that apply across the CodeRabbit API. Each operation's page in the API reference adds its own parameters, response fields, and error codes.

## Base URLs and regions

Send requests to the region where your CodeRabbit organization lives, the same region as the app you sign in to and create keys in:

| Region | App | API host |
| - | - | - |
| US | `https://app.coderabbit.ai` | `https://api.coderabbit.ai` |
| EU | `https://app.eu.coderabbit.ai` | `https://api.eu.coderabbit.ai` |

Every path in the API reference starts with `/v1`, so `GET /v1/me` in the EU region is `https://api.eu.coderabbit.ai/v1/me`. If your HTTP client takes a base URL, set it to the API host and keep `/v1` at the start of each path. Use HTTPS. Request and response bodies are JSON; send `Content-Type: application/json` with a body. A few export operations can also return CSV or SARIF when you ask for it with their `format` parameter.

The [hosted MCP server](https://docs.coderabbit.ai/api/mcp.md) has its own address and region support.

## Identifiers

| Identifier | What it is | Where to find it |
| - | - | - |
| `repository_id` | GitHub's numeric repository ID, sent as a string of digits. It isn't the repository name or GitHub's GraphQL node ID. | `id` in [List repositories](https://docs.coderabbit.ai/api/reference/list-repositories.md) |
| `pull_request_number` | The pull request's number on GitHub, such as `42`. | The pull request URL, or [List pull requests](https://docs.coderabbit.ai/api/reference/list-repository-pull-requests.md) |
| `org_id` | The Git provider's ID for an organization, such as the numeric ID of a GitHub organization. Workspace API tokens use it to select an organization; see [Select an organization](https://docs.coderabbit.ai/api/authentication.md#select-an-organization). | `provider_organization_id` in [List organizations](https://docs.coderabbit.ai/api/reference/organizations-list.md). For GitHub, also `id` in the response of `https://api.github.com/orgs/<organization>` |
| `org_name` | The GitHub login of a GitHub Cloud organization, such as `coderabbitai`. Workspace API tokens can use it instead of `org_id` where name selection is on; see [Select an organization](https://docs.coderabbit.ai/api/authentication.md#select-an-organization). | The organization's GitHub URL, `https://github.com/<login>` |
| CodeRabbit organization ID | CodeRabbit's own ID for an organization. It isn't interchangeable with `org_id`. | `scope.id` in [Get the authenticated principal](https://docs.coderabbit.ai/api/reference/get-me.md), or `id` in [List organizations](https://docs.coderabbit.ai/api/reference/organizations-list.md), where it's the `organization_id` of the next request |

Other IDs, such as task, scan, and job IDs, are opaque strings that the API returns. Pass them back unchanged.

## Pagination

A list operation returns one page and a field that tells you how to get the next. Look at the response, find the continuation field, and send its value back:

| The response has | Send it back as | Used by |
| - | - | - |
| `next_page_token` | `page_token`, with the same `page_size` | Repositories, pull requests, coding tasks, and Change Stack layer diffs. A pull request's review threads use `threads.next_page_token` and `thread_page_token`. |
| `next_cursor` or `nextCursor` | `cursor`, with the same `limit` | Most export and user-management operations, Triage, Verify, connection requests, and runtime validations |
| `next_before_turn_start_seq` | `before_turn_start_seq` | A coding task's turns and questions |
| `next_offset` | `offset` | Automation runs |
| `pagination`, `page`, or `total` | The next `page` number | Audit logs, security findings, dependencies, SBOMs, security scans, secret findings, usage budget members, Knowledge Base Learnings, architecture knowledge repositories, and a Verify bug's history |

Stop when the continuation field is `null` or missing, or when you reach the last page. Knowledge Base Learnings take their page size as `pageSize`, not `page_size`.

* **Keep the request the same.** Send the same filters, page size, key, and organization selector with every page. Only the continuation value changes.
* **Continue past empty pages.** A page can be empty while more results follow, for example when it holds only items you can't access. Stop on the continuation field, not on an empty page.
* **Don't store tokens.** Page tokens and cursors are opaque and short-lived: repository and pull request listings expire theirs after ten minutes. An expired or mismatched token returns `400`; start again from the first page.
* **Expect a live listing.** Items can change between pages. Deduplicate by ID when you collect a full list.

Page sizes have a maximum that differs by operation, from 25 to 1,000. Each operation's reference shows its limits and defaults.

## Errors

Check the HTTP status first, then the error code in the body. Branch on the code, never on the message text, which can change. When the body has no code, as for a missing or expired key, act on the HTTP status.

### Product operations

[Product operations](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts), every operation outside the export and user-management paths listed in the next section, return one error shape:

```json Error response theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests.",
    "retry_after": 30
  }
}
```

| Code | HTTP status | What to do |
| - | - | - |
| `invalid_request` | 400 | Fix the request: check parameter names, types, and values, and the organization selector: where it goes, and that you sent only one. For an expired page token, restart the listing. |
| `unauthenticated` | 401 | Send a valid key. Replace a key that was deleted or expired, or an agentic key whose owner no longer holds a seat. |
| `forbidden` | 403 | Check that the key's owner has the permission, that the operation [accepts the key type](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts), and that the owner can access the repository. Retrying unchanged doesn't help. |
| `not_found` | 404 | The resource doesn't exist, you can't access it, or the operation isn't available for the organization, for example because it isn't on GitHub Cloud or the key is a self-hosted instance key. |
| `head_changed` | 409 | The pull request's head commit changed while you paged through it. Start again without a page token. |
| `conflict` | 409 | The resource changed since you read it. Read its current state, then decide whether to repeat the change. |
| `precondition_failed` | 412 | A condition the operation needs isn't met. Check the operation's description in the reference before retrying. |
| `payload_too_large` | 413 | Send a smaller request body. |
| `rate_limit_exceeded` | 429 | Wait `retry_after` seconds, then retry. See [Rate limits](#rate-limits). |
| `internal_error` | 500 | Retry a read after a short wait. Before you retry a change, read the resource to check whether the change happened. |
| `unavailable` | 503 | A service CodeRabbit depends on is temporarily unavailable. Retry with an increasing wait. |

### Export and user-management operations

The operations under `/v1/users`, `/v1/audit-logs`, `/v1/metrics`, `/v1/learnings`, `/v1/organizations`, and `/v1/linked-repositories`, and the Deep Scan and Bug Scan findings exports, return error codes in upper case, in one of three shapes:

* `{"error": {"code": "LEGACY_API_KEY", "message": "…"}}` for most errors
* `{"errors": [{"code": "RATE_LIMIT_EXCEEDED", "message": "…"}]}` for rate limits and some metrics errors
* `{"success": false, "errors": [{"message": "…"}]}` when the key is missing, unknown, or expired

Read `error.code` first, then `errors[0].code`. The codes you're most likely to meet:

| Code | HTTP status | What to do |
| - | - | - |
| `LEGACY_API_KEY` | 410 | Replace the legacy key with a [user key](https://docs.coderabbit.ai/api/authentication.md#create-a-user-or-agentic-key). |
| `KEY_TYPE_FORBIDDEN` | 403 | The operation doesn't accept agentic keys. Use a user key. |
| `SSO_WORKSPACE_ORG_KEY_FORBIDDEN` | 403 | Use a [workspace API token](https://docs.coderabbit.ai/api/workspace-api-tokens.md) in an Enterprise SSO workspace. |
| `ENTERPRISE_PLAN_REQUIRED` | 403 | The operation needs the Enterprise plan. See [Plans](https://docs.coderabbit.ai/api.md#plans). |
| `RATE_LIMIT_EXCEEDED` | 429 | Wait for the `Retry-After` interval, then retry. |
| `METRICS_BUSY`, `METRICS_QUERY_IN_PROGRESS` | 429 | The metrics service is busy, or the same query is still running. Wait for `Retry-After`, then repeat the same request with the same cursor. |
| `METRICS_PREPARING` | 503 | The metrics are being prepared. Retry after `Retry-After`. |

Each operation's reference lists the rest of its error codes.

## Rate limits

Each operation has its own budget: a burst of 10 requests, refilled at 10 requests per minute. These groups of operations share one budget:

| Shared budget | Operations |
| - | - |
| Repositories | [List repositories](https://docs.coderabbit.ai/api/reference/list-repositories.md) and [get a repository](https://docs.coderabbit.ai/api/reference/get-repository.md) |
| Pull requests and reviews | [List pull requests](https://docs.coderabbit.ai/api/reference/list-repository-pull-requests.md), [get a pull request](https://docs.coderabbit.ai/api/reference/get-repository-pull-request.md), [read the review status](https://docs.coderabbit.ai/api/reference/get-pull-request-review.md), and [request a review](https://docs.coderabbit.ai/api/reference/request-pull-request-review.md) |
| Organization Learnings changes | [Update](https://docs.coderabbit.ai/api/reference/learnings-update.md) and [delete](https://docs.coderabbit.ai/api/reference/learnings-delete.md) an organization Learning |
| Metrics exports | [Review metrics](https://docs.coderabbit.ai/api/reference/review-metrics.md), [review comment metrics](https://docs.coderabbit.ai/api/reference/review-comment-metrics.md), and [MCP server usage](https://docs.coderabbit.ai/api/reference/mcp-metrics.md). The size of this budget is set separately from the others. |

The budget belongs to the organization, not to the key. Every key, the CLI, and the hosted MCP server draw from the same budget for the same organization.

When you go over, the API returns `429` with these headers:

| Header | Meaning |
| - | - |
| `Retry-After` | Seconds to wait before the next request. Product operations also return it as `error.retry_after`. |
| `X-RateLimit-Limit` | The size of the budget. |
| `X-RateLimit-Remaining` | Requests left in the budget. |
| `X-RateLimit-Reset` | When the budget is full again, as a Unix timestamp in seconds. |

### Pace scheduled jobs

A job that stays under the budget doesn't have to recover from `429` responses:

* Send at most 10 requests a minute to one budget, about one every 6 seconds. For the metrics exports, use the size that `X-RateLimit-Limit` reports on a `429`.
* Count every job, script, and agent that works on the same organization, because they draw from the same budget. Start scheduled jobs at different times.
* On a `429`, wait the `Retry-After` interval plus a few random seconds, then send the same request again.

At this pace, reading the review status of 40 pull requests takes about four minutes.

## Asynchronous operations and retries

Some operations start work that finishes later, such as requesting a review, starting a Verify job or a security scan, sending a follow-up to a coding task, or delivering a patch. A successful response, often `202 Accepted`, means CodeRabbit accepted the request, not that the work finished. Read the resource the operation names, such as the review status, the coding task, the Verify job, or the scan, to follow its progress.

Most changes don't accept an idempotency key. If a change times out or the connection drops, read the resource before you retry, so you don't start the same work twice.

## Versioning

The major version of the API is part of the path: every operation is under `/v1`. Operations and response fields are added to `v1` over time, so write clients that ignore response fields they don't recognize. The API reference is generated from the OpenAPI description that the API serves.

## What's next

> [card] [Authenticate requests](https://docs.coderabbit.ai/api/authentication.md)
>
> See which operations accept which key, and how a key's permissions work.

> [card] [Request and read reviews](https://docs.coderabbit.ai/api/guides/pull-request-reviews.md)
>
> Put pagination, polling, and error handling to work in a complete review workflow.

> [card] [API reference](https://docs.coderabbit.ai/api/reference/get-me.md)
>
> Look up an operation's parameters, response fields, limits, and error codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.