> ## 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.

# Call the API from the CLI

> Call CodeRabbit API operations from a terminal, a script, or a CI job with the CodeRabbit CLI and an API key, and get JSON back.

`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](https://docs.coderabbit.ai/cli.md); to upgrade, see [Update the CLI](https://docs.coderabbit.ai/cli.md#update-the-cli).
* Create an API key that can call the operations you need. See [Authentication](https://docs.coderabbit.ai/api/authentication.md).

## 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:

```bash theme={null}
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.

### Use a saved agentic key 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.

```bash theme={null}
coderabbit auth login --api-key "$CODERABBIT_API_KEY"
coderabbit api me
```

### Use a workspace API token

A [workspace API token](https://docs.coderabbit.ai/api/workspace-api-tokens.md) needs an organization selector wherever the operation expects one, as [Select an organization](https://docs.coderabbit.ai/api/authentication.md#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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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](https://docs.coderabbit.ai/api/reference/get-me.md) |
| `repositories list` | Repositories you can access, one page at a time | [List repositories](https://docs.coderabbit.ai/api/reference/list-repositories.md) |
| `repositories get <repository-id>` | One repository | [Get a repository](https://docs.coderabbit.ai/api/reference/get-repository.md) |
| `pull-requests list <repository-id>` | A repository's pull requests | [List pull requests](https://docs.coderabbit.ai/api/reference/list-repository-pull-requests.md) |
| `pull-requests get <repository-id> <number>` | One pull request with checks and, optionally, review threads | [Get a pull request](https://docs.coderabbit.ai/api/reference/get-repository-pull-request.md) |
| `pull-requests review-status <repository-id> <number>` | CodeRabbit's review state for a pull request | [Get the review state](https://docs.coderabbit.ai/api/reference/get-pull-request-review.md) |
| `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](https://docs.coderabbit.ai/cli/reference.md) or run the command with `--help`.

### `me`

Check which key and organization the CLI uses:

```bash theme={null}
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](https://docs.coderabbit.ai/api/authentication.md#select-an-organization).

### `repositories`

```bash theme={null}
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](https://docs.coderabbit.ai/api/conventions.md#pagination).

### `pull-requests`

```bash theme={null}
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](https://docs.coderabbit.ai/api/guides/pull-request-reviews.md#4-follow-the-review-status).

### `request`

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

```bash theme={null}
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](https://docs.coderabbit.ai/api/reference/request-pull-request-review.md) of a pull request's current head:

```bash theme={null}
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`:

```json theme={null}
{
  "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:

```bash theme={null}
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](https://docs.coderabbit.ai/api/reference/create-code-task.md), shows its path, method, and body. The [pull request reviews](https://docs.coderabbit.ai/api/guides/pull-request-reviews.md) and [coding tasks](https://docs.coderabbit.ai/api/guides/coding-tasks.md) 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:

```bash theme={null}
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:

```json theme={null}
{"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](https://docs.coderabbit.ai/api/conventions.md#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`.

```bash theme={null}
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](https://docs.coderabbit.ai/api/conventions.md#rate-limits). To install the CLI in CI, see [Headless CLI integration](https://docs.coderabbit.ai/cli/headless-cli-integration.md).

## What's next

> [card] [Request and read reviews](https://docs.coderabbit.ai/api/guides/pull-request-reviews.md)
>
> Read pull requests, request a review, and follow its status through the API.

> [card] [Handle responses](https://docs.coderabbit.ai/api/conventions.md)
>
> Learn how the API handles pagination, errors, and rate limits.

> [card] [Connect an MCP client](https://docs.coderabbit.ai/api/mcp.md)
>
> Give your AI agent the same operations as tools, with OAuth instead of an API key.


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