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

# Platform API workflows

> Read review state, submit a coding task, and inspect product results with REST, CLI, or MCP.

These examples use CodeRabbit CLI **0.9.4 or later** and an organization API key file. For a workspace token, also include the provider organization ID as described in [authentication](https://docs.coderabbit.ai/api/platform-authentication.md). Use your organization's regional REST endpoint; hosted MCP is US-only. The shared API supports GitHub Cloud, not self-hosted instances. Use the API reference for each operation's complete inputs and product requirements.

## Inspect a pull request and request its current-head review

Find an accessible repository and inspect a PR:

```bash theme={null}
coderabbit api --api-key-file /path/to/api-key repositories list --page-size 20

coderabbit api --api-key-file /path/to/api-key \
  pull-requests get 12345678 42 --include checks,threads

coderabbit api --api-key-file /path/to/api-key \
  pull-requests review-status 12345678 42
```

To request a review of the current head, use an agentic API key. User keys can read pull requests, but return `403 forbidden` for this action:

```bash theme={null}
coderabbit api --api-key-file /path/to/agentic-api-key \
  request /repositories/12345678/pull-requests/42/review --method POST
```

A `202` response acknowledges the existing review dispatcher. It does not mean the review completed. Read review status afterward, and compare the provider's `head_sha` with the observation's `target_commit_sha`. Missing or unconfirmed observations do not prove that execution stopped or that no review ran. Even a completed observation does not prove that comments were published.

In hosted MCP, use `request_pull_request_review` with `account:read`, `pull_requests:read`, and `reviews:write` consent. A grant for local code review (`review`) does not include permission to request a PR review.

See [pull-request reads](https://docs.coderabbit.ai/api/platform-pull-requests.md) for pagination, stale-head handling, and thread observations. PR-review cancellation, old-commit restarts, and thread resolution are not part of this API.

## Create and follow a coding task

Create `task.json` with a repository provider ID, existing branch, instructions, and a client request ID:

```json theme={null}
{
  "repository_id": "12345678",
  "branch": "main",
  "instructions": "Add a regression test for the documented pagination behavior.",
  "mode": "plan",
  "client_request_id": "pagination-plan-001"
}
```

```bash theme={null}
coderabbit api --api-key-file /path/to/api-key \
  request /code/tasks --input task.json
```

Use the returned task ID to inspect its current state and retained turns. The task detail's `plan_version` identifies its current stored plan; `null` means no plan is stored yet. Plan reads require that returned version. This example uses `jq` and stops before the plan read when no version is available:

```bash theme={null}
coderabbit api --api-key-file /path/to/api-key request /code/tasks/TASK_ID/turns

coderabbit api --api-key-file /path/to/api-key \
  request /code/tasks/TASK_ID > task-state.json &&
  PLAN_VERSION="$(jq -er '.plan_version' task-state.json)" &&
  coderabbit api --api-key-file /path/to/api-key \
    request "/code/tasks/TASK_ID/plan?version=$PLAN_VERSION" > plan.json &&
  PLAN_SHA="$(jq -er '.sha256' plan.json)" &&
  coderabbit api --api-key-file /path/to/api-key \
    request "/code/tasks/TASK_ID/plan/comments?version=$PLAN_VERSION&sha256=$PLAN_SHA"
```

Turn lists contain metadata. Read `/code/tasks/TASK_ID/turns/TURN_START_SEQ` for a retained final reply or public error. A `null` result can mean the turn is still running or no final reply is retained; use its status to distinguish those cases. Turn pagination returns the newest page first, with turns ordered oldest first within each page. Pass `next_before_turn_start_seq` as `before_turn_start_seq` for the next older page.

The reference also exposes plan approval and implementation, follow-up messages, questions and answers, patches, and explicit patch delivery. Creation leaves delivery explicit; inspect the resulting plan or patch before requesting delivery. Follow-ups, plan revisions, implementation, and delivery return `202` when accepted. Read the task and its subsequent turns for completion; acceptance does not mean the work has finished. Writes preserve the existing task permissions, collaboration rules, and billing checks.

Plan comments include open and resolved threads for the current version and hash, with deleted comments omitted. If those selectors are stale, reread the task and plan. Plan approval records another reviewer's decision; authors cannot approve their own plans. An authorized author can request implementation without that approval, once the existing readiness checks pass. Use the returned plan version for implementation and resolve or revise any open Plan comments first.

Keep a client request or operation ID stable when retrying the same submission, where the schema requires one. After a timeout, inspect the existing task or command receipt before creating new work. To stop a coding turn, use its documented `/code/tasks/{task_id}/cancel` operation; that action does not cancel a PR review.

Ordinary patch delivery through `POST /code/tasks/{task_id}/delivery` does not accept `client_operation_id` or promise client-key idempotency. If the response is uncertain, read the task and its provider pull request before deciding whether to retry. Delivery requires an existing provider write grant; complete any requested authorization in the browser.

In MCP, use `create_code_task`, `get_code_task`, and the other advertised Coding tools. Creation and mutation require `code:write`; reads require `code:read`, in addition to `account:read`.

## Inspect scans, usage, and automation results

The same CLI transport works across products:

```bash theme={null}
coderabbit api --api-key-file /path/to/api-key request /usage
coderabbit api --api-key-file /path/to/api-key request /credits
coderabbit api --api-key-file /path/to/api-key request /reports
```

For Security, first read coverage or a quote where available. Submit the operation using the documented input, then read the returned scan or finding. For Verify, read the registered repository and journeys, start a job, then read its result. For Automations, follow the returned native command or execution identifiers.

An optional Security Deep Scan `spend_limit_cents` must be between 1,000 and 100,000,000 customer cents. Omitting it uses the existing billing admission without an explicit request budget; it does not supply a zero-cent limit or bypass credit checks.

For a Security finding, read `GET /security/repositories/{repository_id}/findings/{finding_id}/validation-capability`. If `available` is `true`, use its `findingIdentityId` as `finding_identity_id` when listing `/security/repositories/{repository_id}/validations`, then read a returned attempt at `/security/repositories/{repository_id}/validations/{validation_id}`. If availability is false or no attempts exist, do not invent an identity or validation result. The capability lookup does not start a validation; native permissions and feature availability still apply.

Verify repository reads return `config_revision` and `cuj_list_revision`. Use `config_revision` as `expected_revision` when configuring the repository, and `cuj_list_revision` as `expected_list_revision` when creating or updating a journey. Updating a journey also requires its own `revision` as `expected_revision`. Reload after a conflict or a successful change instead of reusing an old revision. Job results identify executions and evidence; follow their returned identifiers to read execution details or download an evidence artifact.

For an ordinary Automation update, read its detail and reuse the returned `definition`, with `data.revision` as `expected_revision`. Set the definition's `status` to `paused` or `active`; enabling it can start automated work. Preserve the definition's other fields rather than rebuilding it from the summary. Creation defaults to `active`, so explicitly choose `paused` for a disposable test. If an editable definition is unavailable, use the product's existing edit or authorization flow.

Learning creation returns `learning_ids` for reading and updating the saved records. If an older writer returns `null` instead, do not replay the write to discover IDs. Recurring reports support configuration replacement, disabling, and deletion; reading a report returns configuration, not generated report content or execution status. Creating an on-demand report starts native generation.

These operations retain each product's feature flags and permissions. An API key cannot enable a disabled product. Readable credit balances do not grant permission to spend, and unavailable balances are not zero.

Connection setup can return a provider authorization or consent handoff. Complete that step in the browser. Use the native browser flow for payment changes, full workspace configuration replacement, and budget changes rather than trying to replay browser credentials through API mode.

Connection reads expose only the endpoint's `serverOrigin`, not its full path or query. Use `PATCH /connections/CONNECTION_ID` to change the name or description while preserving the saved provider configuration and credentials. `PUT` remains a full configuration replacement. To edit an endpoint, use Settings or resubmit the full endpoint URL you already know. Do not reconstruct the saved URL from the redacted read response.

For existing metrics, legacy bug-scan findings, and user-role changes, use the original REST endpoint and permitted key type through `coderabbit api request`. These exceptions are not additional MCP tools. Read `seat_assignment_mode` from `GET /users`; updating it uses the existing self-hosted-only `POST /users/seats/assignment` operation.

## What's next

> [card] [Explore pull-request reads](https://docs.coderabbit.ai/api/platform-pull-requests.md)
>
> Read checks, threads, and CodeRabbit review observations.

> [card] [Review API boundaries](https://docs.coderabbit.ai/api/platform-api.md#boundaries)
>
> Check supported operations and the actions that require a browser.


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