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

# Triage API

> Read your Triage queue, change details, retained recommendation history, and selectable teams through the CodeRabbit API.

Use the Triage API to bring your queue into a dashboard or integration. The API reads the information already tracked by [Triage](https://docs.coderabbit.ai/triage.md), including priority, close candidacy, review and approval status, and Now/Next focus. It does not start reviews, refresh change assessments, or merge or close changes.

The resource name `changes` works across Git providers. A change can be a pull request or merge request; its provider-specific number is returned separately as `external_id`.

## Choose a resource

| Reference | Use it to |
| - | - |
| [List changes](https://docs.coderabbit.ai/api-reference/triage-changes-list.md) | Filter, order, group, and page open tracked changes in your personal or team queue. |
| [Get a change](https://docs.coderabbit.ai/api-reference/triage-changes-get.md) | Read a tracked change, including retained closed or merged changes. |
| [List change history](https://docs.coderabbit.ai/api-reference/triage-history-list.md) | Read retained priority and close-candidacy transitions. |
| [List teams](https://docs.coderabbit.ai/api-reference/triage-teams-list.md) | Find the teams you can select for a team queue. |

Each resource supports `GET`, `HEAD`, and `OPTIONS`. `HEAD` performs the same authenticated read and returns headers without a body. `OPTIONS` returns the supported methods without authenticating or returning resource data. Reads have no request body. The endpoint references provide the complete query parameters, response schemas, and response codes.

## Access and organization selection

Use a non-agentic CodeRabbit API key whose owner can be resolved to a current Triage viewer. The viewer must have Triage access and access to the repositories being read. An API key, workspace administrator role, or team membership does not grant access to every repository.

* **Organization keys** default to their bound organization. If you supply `org_id`, it must identify that organization.
* **Workspace tokens and Git-provider instance keys** require one `org_id` on every Triage request. Triage has no workspace-wide or instance-wide query, and does not accept `ALL`.
* **Workspace tokens** also require a current workspace administrator with a uniquely linked account for the selected Git provider. A workspace login alone does not establish that provider identity.

`org_id` is the Git provider's native organization ID. For workspace organization discovery, use `provider_organization_id` from [List organizations](https://docs.coderabbit.ai/api-reference/organizations-list.md), not the CodeRabbit UUID in `id`. The response's `meta.org_id` uses the same native ID. An ambiguous ID within the key's workspace or instance is rejected.

## Read your queue

This example selects one organization and the changes that require the key owner's attention:

```bash theme={null}
curl --get "https://api.coderabbit.ai/v1/triage/changes" \
  -H "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "org_id=$PROVIDER_ORG_ID" \
  --data-urlencode "view=mine" \
  --data-urlencode "attention=required" \
  --data-urlencode "group_by=focus_state" \
  --data-urlencode "limit=50"
```

The default `view=mine` includes eligible changes in your personal Triage view. Add `attention=required` for your action queue; `mine` alone does not mean every returned change needs your action.

For a team queue, first [list teams](https://docs.coderabbit.ai/api-reference/triage-teams-list.md), then send `view=team` and the returned team's `id` as `team_id`. Omit `team_id` for a personal queue.

Use returned identifiers unchanged:

* `data[].id` selects a change for detail and history requests. Do not substitute its `external_id` or provider URL.
* `data[].repository.id` is the value for the list's `repository_id` filter. Do not substitute a native repository number or an ID from another API.
* A team's `id` is the value for `team_id`; its `external_id` is for provider context.

## Filter, group, and page results

Send each query parameter once. Filters with several values use one comma-separated string, such as `priority=p0,p1`; repeated parameters and array syntax are rejected. Values within a filter combine with OR, and different filters combine with AND. Unknown query parameters are rejected.

The returned `focus_state` is `now`, `next`, or `null`. Use the `unassigned` filter value to select changes without a focus assignment. You can also use `focus_state` as a grouping axis. Filtering and changing the sort order do not recalculate Now/Next allocation. A subgroup requires an enabled, different top-level group.

The `groups` counts and `meta.total_count` describe the full filtered result you can access. The `data` array is one page in the selected global order; it is not a separate page for each group. Use each item's `group_key` and `subgroup_key` to associate it with the returned counts.

To read another page, copy `next_cursor` into `cursor` and repeat the original organization, filters, grouping, sort, and limit. Stop when `next_cursor` is `null`. Cursors expire after 15 minutes. If a cursor expires or no longer matches your access or query, start again without it.

Pages reflect a live queue. Changes can move between pages as their ranking changes, so deduplicate by change `id` when collecting several pages. Pagination does not create a frozen export.

## Interpret the fields

| Field | Meaning |
| - | - |
| `opened_at`, `age_seconds` | The recorded creation time and age at response generation. |
| `latest_commit_at` | The provider's commit timestamp. Currently `null`: the stored Triage data does not establish this timestamp. |
| `latest_reviewable_observed_at` | When the latest reviewable change was observed. Do not use it as a substitute for the commit timestamp. |
| `last_activity_at`, `last_human_activity_at` | The same recorded human-activity timestamp. Bot activity is excluded from these API fields. |
| `priority` | Urgency, including the effective level and available supporting reason or manual override. `none` is a known level; a `null` level is unassigned or unknown. |
| `close_candidate` | A separate recommendation to consider closing the change. It is independent of priority. |
| `review_status` | The CodeRabbit review state shown by Triage, including whether new changes need review. |
| `approval_status` | The stored aggregate approval decision, separate from CodeRabbit review progress. An approval does not establish that every merge requirement is satisfied. |
| `readiness` | Detail-only draft, checks, conflicts, and provider eligibility observations. Review and approval states are top-level fields, not `readiness.reviews`. |
| `change_type`, `blast_radius`, `merge_risk` | Available classifications and assessments. Merge-risk scores carry a `basis` describing whether the assessment is direct, a proxy, mixed, or unknown. |
| `focus_state`, `requires_attention`, `next_action` | The selected queue's focus allocation and the viewer's attention and next-action information. These can differ between viewers. |

Assessment objects include `status`, `value`, `observed_at`, and `revision`. Use `value` only when `status` is `available`. `unknown`, `stale`, and `unsupported` have a `null` value; none means a measured zero, a negative recommendation, or permission to act. Observation timestamps and revisions can also be `null`. `meta.generated_at` is the response time, not a freshness guarantee for every field.

Detail responses add participants, readiness, diff information, and closure assessments. `blocked_change_count` is currently unknown. History contains only retained priority and close-candidacy transitions. An empty history is valid; `meta.history_complete` is currently `null` because completeness is unknown. History is not a complete Git-provider audit log.

## Provider coverage

Resource names are independent of the Git provider, but availability follows Triage's provider, viewer, and organization support. Team discovery and team views currently require GitHub Cloud on CodeRabbit Cloud. Unsupported provider or view requests return `capability_unavailable`; organization access restrictions can return `triage_access_denied`. Neither error is an empty successful result.

Self-hosted CodeRabbit deployments do not support `focus_state` filtering or grouping. Omit that filter and choose another grouping axis when using such a deployment. A self-managed Git provider connected to CodeRabbit Cloud is a different deployment type.

Optional assessments may be missing even for supported providers. Use the response's observation status for each field. A provider name accepted by the filter does not establish that Triage is enabled for your organization or deployment.

## Handle errors

Triage errors use `application/problem+json` with a stable `code` and a `request_id`. Use `invalid_params`, when present, to correct query controls. Keep the request ID when contacting support; do not share your API key.

* For `cursor_expired` or `cursor_mismatch`, start a new pagination sequence.
* For `viewer_identity_required`, check the key owner's linked provider account. For `org_access_denied` or `triage_access_denied`, check organization selection and current access.
* For `capability_unavailable`, check provider and view support before retrying.
* For `rate_limit_exceeded`, wait for the number of seconds in `Retry-After`.
* For `provider_connection_unavailable`, check the provider connection. For temporary dependency failures or timeouts, retry later with bounded backoff.

Responses use `Cache-Control: private, no-store`. A successful read reports stored Triage information; it is not authorization to merge, close, or otherwise change a resource.

## What's next

> [card] [List Triage changes](https://docs.coderabbit.ai/api-reference/triage-changes-list.md)
>
> Explore every filter, grouping option, and response field.

> [card] [How Triage prioritizes](https://docs.coderabbit.ai/triage/prioritization.md)
>
> Understand the evidence behind priority and close recommendations.


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