API conventions

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 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
`pull_request_number`	The pull request’s number on GitHub, such as `42`.	The pull request URL, or List pull requests
`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.	`provider_organization_id` in List organizations. 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.	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, or `id` in List organizations, 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, every operation outside the export and user-management paths listed in the next section, return one error shape:

{
  "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, 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.
`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.
`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 in an Enterprise SSO workspace.
`ENTERPRISE_PLAN_REQUIRED`	403	The operation needs the Enterprise plan. See 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 and get a repository
Pull requests and reviews	List pull requests, get a pull request, read the review status, and request a review
Organization Learnings changes	Update and delete an organization Learning
Metrics exports	Review metrics, review comment metrics, and MCP server usage. 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

Authenticate requests

See which operations accept which key, and how a key’s permissions work.

Request and read reviews

Put pagination, polling, and error handling to work in a complete review workflow.

API reference

Look up an operation’s parameters, response fields, limits, and error codes.

Basics

Clients

Guides

API reference

Base URLs and regions

Identifiers

Errors

Product operations

Export and user-management operations

Rate limits

Pace scheduled jobs

Asynchronous operations and retries

Versioning

What’s next

Authenticate requests

Request and read reviews

API reference