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:
invalid_request and doesn’t fall back to the saved login.
Use a saved agentic key login
Sign in once with an agentic key, and laterapi 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.
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, theme, repositories, and pull-requests commands take --org-name, the organization’s GitHub login, or --org-id. Pass one of them, not both:
request, put org_name or org_id in the query string, or in the JSON input where the operation expects it in the body:
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_URLto the EU app address, or pass--host-urlwith the same value.
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
<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:
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
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
listreturns your open pull requests unless you set--authoror--state. Filter by source branch with--head-branchand--head-owner.getincludes checks by default. Use--include threadsor--include checks,threadsfor review threads, and filter them with--thread-authorand--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 withhead_changedif the pull request’s head commit differs.review-statusreturns the pull request’shead_shaand CodeRabbit’sreview. 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:
-X (--method): GET, POST, PUT, PATCH, or DELETE. This call requests a review of a pull request’s current head:
--input. The method is then POST unless you set -X. For example, create task.json:
- 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
GETrequest 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>.
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:
Exit codes and errors
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:
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:
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 -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.