Call the API from the CLI

coderabbit api sends authenticated requests to the CodeRabbit API and prints each response as one line of JSON. It has commands for your identity, repositories, and pull requests, and a request command for any other API operation.

Before you start

Install CodeRabbit CLI 0.9.4 or later. Check your version with coderabbit --version. To install the CLI, see CLI Tool; to upgrade, see Update the CLI.
Create an API key that can call the operations you need. See Authentication.

Authenticate

coderabbit api uses an API key from a key file or from a saved agentic key login. A browser sign-in with coderabbit auth login doesn’t work for API calls: without a key, commands fail with unauthenticated.

Use a key file

Save the key alone in a file that only you can read, then pass the file with --api-key-file. The option goes right after api, before the subcommand:

coderabbit api --api-key-file ~/.config/coderabbit/api-key me

The CLI uses the key for this command only and doesn’t change your saved login. If the file is missing, unreadable, or empty, the command fails with invalid_request and doesn’t fall back to the saved login. Sign in once with an agentic key, and later api commands use it when you don’t pass --api-key-file. The CLI saves only agentic keys, so use a key file for a user key.

coderabbit auth login --api-key "$CODERABBIT_API_KEY"
coderabbit api me

Use a workspace API token

A workspace API token needs an organization selector wherever the operation expects one, as Select an organization describes. With CLI 0.9.5 or later, the me, repositories, and pull-requests commands take --org-name, the organization’s GitHub login, or --org-id. Pass one of them, not both:

coderabbit api --api-key-file ~/.config/coderabbit/workspace-token me --org-name coderabbitai

With request, put org_name or org_id in the query string, or in the JSON input where the operation expects it in the body:

coderabbit api --api-key-file ~/.config/coderabbit/workspace-token request '/users?org_id=12345678'

Choose the region

The CLI calls the US region unless you select the EU region:

Saved login: the CLI uses the region you signed in with. For the EU region, sign in with coderabbit auth login --region eu --api-key "$CODERABBIT_API_KEY".
Key file: the CLI doesn’t read the saved login, so it calls the US region. For the EU region, set CODERABBIT_HOST_URL to the EU app address, or pass --host-url with the same value.

CODERABBIT_HOST_URL=https://app.eu.coderabbit.ai \
  coderabbit api --api-key-file ~/.config/coderabbit/api-key me

Set the app address, https://app.eu.coderabbit.ai, not the API address: the CLI derives the API address from the app address and rejects other hosts. The host setting also takes precedence over the region of a saved login.

Commands

Command	Returns	Operation
`me`	The key owner and the organization the key selects	Get the authenticated principal
`repositories list`	Repositories you can access, one page at a time	List repositories
`repositories get <repository-id>`	One repository	Get a repository
`pull-requests list <repository-id>`	A repository’s pull requests	List pull requests
`pull-requests get <repository-id> <number>`	One pull request with checks and, optionally, review threads	Get a pull request
`pull-requests review-status <repository-id> <number>`	CodeRabbit’s review state for a pull request	Get the review state
`request <path>`	The response of any operation	Any operation

<repository-id> is the Git provider’s repository ID, which repositories list returns as id. For every option of each command, see the CLI command reference or run the command with --help.

`me`

Check which key and organization the CLI uses:

coderabbit api me

principal describes the key and its owner’s role, and scope describes the organization. scope.id isn’t the value that org_id takes; see Select an organization.

`repositories`

coderabbit api repositories list --page-size 100
coderabbit api repositories get 123456789

A list returns data and next_page_token. Pass the token with --page-token and the same page size to read the next page. See Pagination.

`pull-requests`

coderabbit api pull-requests list 123456789 --author all --state open
coderabbit api pull-requests get 123456789 42 --include checks,threads
coderabbit api pull-requests review-status 123456789 42

list returns your open pull requests unless you set --author or --state. Filter by source branch with --head-branch and --head-owner.
get includes checks by default. Use --include threads or --include checks,threads for review threads, and filter them with --thread-author and --thread-state. Threads have their own page token, threads.next_page_token, which you pass with --thread-page-token. With --expected-head-sha, the command fails with head_changed if the pull request’s head commit differs.
review-status returns the pull request’s head_sha and CodeRabbit’s review. See what the review status means.

`request`

request calls any operation. Give the path relative to /v1, and quote it when it has a query string:

coderabbit api request /me
coderabbit api request '/code/tasks?page_size=20'

Choose the method with -X (--method): GET, POST, PUT, PATCH, or DELETE. This call requests a review of a pull request’s current head:

coderabbit api request -X POST /repositories/123456789/pull-requests/42/review

Send a JSON body from a file with --input. The method is then POST unless you set -X. For example, create task.json:

{
  "repository_id": "123456789",
  "branch": "main",
  "instructions": "Add a regression test for the pagination bug.",
  "mode": "plan",
  "client_request_id": "pagination-plan-001"
}

Then create the coding task:

coderabbit api request /code/tasks --input task.json

Keep these rules in mind:

Write the path relative to /v1: /code/tasks, not /v1/code/tasks. The CLI rejects full URLs and paths outside the API.
The input file must contain valid JSON, and a GET request can’t have one. Put filters in the path’s query string instead.
The CLI doesn’t follow redirects.
There is no time limit by default. Set one with --timeout <seconds>.

Each operation’s reference page, such as Create a coding task, shows its path, method, and body. The pull request reviews and coding tasks guides show complete flows.

Output

Each command prints the response body as one line of JSON on standard output. An empty response prints {}. Pipe the output to jq to format or filter it:

coderabbit api repositories list --page-size 100 | jq -r '.data[] | "\(.id)\t\(.full_name)"'

Errors are also printed as one line of JSON on standard output, so check the exit code before you use the output.

Exit codes and errors

Exit code	Meaning
`0`	The API returned a success response.
`1`	The API returned an error status, or the CLI couldn’t make the call. The JSON on standard output describes the error.

Invalid options, such as an unknown method or a page size outside 1–100, print a usage error to standard error and exit with 1 before the CLI calls the API. The me, repositories, and pull-requests commands print errors in one shape:

{"error":{"code":"rate_limit_exceeded","message":"Too many requests.","retry_after":30}}

code is one of the error codes that the API returns, and retry_after gives the seconds to wait after a rate limit. See Errors. request prints the error response as the API returns it, so its shape depends on the operation. When the CLI can’t make the call, every command prints the same shape with one of these codes:

Code	Cause
`unauthenticated`	No key: you didn’t pass `--api-key-file`, and the saved login isn’t an agentic key login.
`invalid_request`	The key file is missing or empty, the path leaves the API, or the input file isn’t valid JSON or is used with `GET`.
`unavailable`	The network request failed or timed out, the response wasn’t JSON, or the API returned an error that the `me`, `repositories`, or `pull-requests` command doesn’t recognize.

Use in CI

In a CI job, keep the key in a secret, write it to a temporary file, and pass the file with --api-key-file. The CLI then doesn’t need a saved login. For the EU region, also set CODERABBIT_HOST_URL=https://app.eu.coderabbit.ai.

set -euo pipefail
key_file="$(mktemp)"
trap 'rm -f "$key_file"' EXIT
printf '%s' "$CODERABBIT_API_KEY" > "$key_file"

coderabbit api --api-key-file "$key_file" \
  pull-requests review-status "$REPOSITORY_ID" "$PR_NUMBER" |
  jq -r '.review.status // "none"'

set -o pipefail makes the step fail when coderabbit api exits with 1, even though jq runs after it. When a call fails with rate_limit_exceeded, wait retry_after seconds before you retry. CI jobs share your organization’s request quota; see Rate limits. To install the CLI in CI, see Headless CLI integration.

What’s next

Request and read reviews

Read pull requests, request a review, and follow its status through the API.

Handle responses

Learn how the API handles pagination, errors, and rate limits.

Connect an MCP client

Give your AI agent the same operations as tools, with OAuth instead of an API key.

Basics

Clients

Guides

API reference

Call the API from the CLI

Before you start

Authenticate

Use a key file

Use a workspace API token

Choose the region

Commands

`me`

`repositories`

`pull-requests`

`request`

Output

Exit codes and errors

Use in CI

What’s next

Request and read reviews

Handle responses

Connect an MCP client

Before you start

Authenticate

Use a key file

Use a saved agentic key login

Use a workspace API token

Choose the region

Commands

me

repositories

pull-requests

request

Output

Exit codes and errors

Use in CI

What’s next

Request and read reviews

Handle responses

Connect an MCP client

`me`

`repositories`

`pull-requests`

`request`