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

# Make your first API call

> Create a CodeRabbit API key, check it, list your repositories, and read a pull request's review status with curl or the CLI.

GitHub Cloud (The operations on this page are available for GitHub Cloud organizations.)

In this quickstart you create an API key and make three calls: check which organization the key belongs to, list the repositories you can access, and read CodeRabbit's review status for a pull request. It takes about five minutes.

## Before you start

* CodeRabbit is installed on a GitHub Cloud organization, and you know a pull request it reviewed.
* You know your organization's region: US if you sign in at `app.coderabbit.ai`, EU if you sign in at `app.eu.coderabbit.ai`.
* You have `curl`, or the CodeRabbit CLI for the CLI examples. See [CLI](https://docs.coderabbit.ai/api/cli.md) for the version that includes `coderabbit api`.

## Create an API key

In the CodeRabbit app for your region, open **API keys** ([US](https://app.coderabbit.ai/settings/api-keys) or [EU](https://app.eu.coderabbit.ai/settings/api-keys)) and create a key of type **User**, as [Create a user or agentic key](https://docs.coderabbit.ai/api/authentication.md#create-a-user-or-agentic-key) describes. If **Type** offers only **Agentic**, choose it: an agentic key works for every call on this page. Copy the key when you save it, because CodeRabbit shows it only once.

## Set up your shell

Read the key into an environment variable without echoing it or writing it to your shell history:

```bash theme={null}
read -rs CODERABBIT_API_KEY   # paste the key, then press Enter
export CODERABBIT_API_KEY
```

Set the API host of the region where you created the key. The EU settings also point the CLI at the EU region; see [Choose the region](https://docs.coderabbit.ai/api/cli.md#choose-the-region).

```bash US theme={null}
export CODERABBIT_API_HOST=https://api.coderabbit.ai
```

```bash EU theme={null}
export CODERABBIT_API_HOST=https://api.eu.coderabbit.ai
export CODERABBIT_HOST_URL=https://app.eu.coderabbit.ai
```

For the CLI, also save the key to a file that only you can read. `--api-key-file` passes the file to each command without changing your CLI sign-in:

```bash theme={null}
(umask 077 && printf '%s\n' "$CODERABBIT_API_KEY" > ~/.coderabbit-api-key)
```

## Check the key

Ask the API who you are with [Get the authenticated principal](https://docs.coderabbit.ai/api/reference/get-me.md):

```bash curl theme={null}
curl -sS "$CODERABBIT_API_HOST/v1/me" \
  -H "x-coderabbitai-api-key: $CODERABBIT_API_KEY"
```

```bash CLI theme={null}
coderabbit api --api-key-file ~/.coderabbit-api-key me
```

The response names the key, its owner's role, and the CodeRabbit organization the key belongs to:

```json Response (trimmed) theme={null}
{
  "principal": {
    "type": "api_key",
    "key_type": "user",
    "owner": { "provider_user_id": "583231", "role": "cr_member" }
  },
  "scope": {
    "type": "organization",
    "id": "0b6f3d2e-5a1c-4e8b-9f27-6c4d8a1e3b95",
    "provider": "github",
    "workspace_id": "7e2a9c41-3d8f-4b6e-a015-9c8d2f4b7a63"
  }
}
```

If you get `401 unauthenticated`, the key is missing, mistyped, deleted, or expired, or `CODERABBIT_API_HOST` isn't the host of the region where you created the key. If you get `404 not_found`, the key belongs to an organization that isn't on GitHub Cloud, or it's a self-hosted instance key. See [Errors](https://docs.coderabbit.ai/api/conventions.md#errors) for the other codes.

## List your repositories

[List repositories](https://docs.coderabbit.ai/api/reference/list-repositories.md) returns the repositories in the organization that you can access:

```bash curl theme={null}
curl -sS "$CODERABBIT_API_HOST/v1/repositories?page_size=10" \
  -H "x-coderabbitai-api-key: $CODERABBIT_API_KEY"
```

```bash CLI theme={null}
coderabbit api --api-key-file ~/.coderabbit-api-key repositories list --page-size 10
```

Each entry in `data` has an `id`, GitHub's numeric repository ID, and a `full_name` such as `acme/api`. Copy the `id` of the repository that has your pull request. When `next_page_token` isn't `null`, more repositories are available: see [Pagination](https://docs.coderabbit.ai/api/conventions.md#pagination).

## Read a pull request's review status

[Read review status](https://docs.coderabbit.ai/api/reference/get-pull-request-review.md) takes the repository ID and the pull request number. Replace `123456789` and `42` with yours:

```bash curl theme={null}
curl -sS "$CODERABBIT_API_HOST/v1/repositories/123456789/pull-requests/42/review" \
  -H "x-coderabbitai-api-key: $CODERABBIT_API_KEY"
```

```bash CLI theme={null}
coderabbit api --api-key-file ~/.coderabbit-api-key pull-requests review-status 123456789 42
```

```json Response (trimmed) theme={null}
{
  "head_sha": "9f2c1e74b0a1d3c5e8f7a6b5c4d3e2f1a0b9c8d7",
  "review": {
    "status": "completed",
    "target_commit_sha": "9f2c1e74b0a1d3c5e8f7a6b5c4d3e2f1a0b9c8d7",
    "updated_at": "2026-11-10T09:14:03Z"
  }
}
```

`head_sha` is the pull request's current head commit. To read `review.status` and check whether it covers that commit, see [Follow the review status](https://docs.coderabbit.ai/api/guides/pull-request-reviews.md#4-follow-the-review-status). This call only reads the status; to start a review, see [Request a review](https://docs.coderabbit.ai/api/guides/pull-request-reviews.md#3-request-a-review).

## What's next

> [card] [Authenticate requests](https://docs.coderabbit.ai/api/authentication.md)
>
> Choose between user keys, agentic keys, and workspace API tokens, and keep them safe.

> [card] [Handle responses](https://docs.coderabbit.ai/api/conventions.md)
>
> Learn the base URLs, identifiers, pagination styles, errors, and rate limits that every operation shares.

> [card] [Request and read reviews](https://docs.coderabbit.ai/api/guides/pull-request-reviews.md)
>
> Request a CodeRabbit review and follow it until the current head is reviewed.


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