Approvals queue (Review Loop, console plane)

GET

/v1/admin/orgs/{org_id}/projects/{project_id}/reviews

• Production
• Local

The human Approvals queue: pending reviews across ALL the tenant’s inboxes, newest-first and paginated, each with an intent summary + a body snippet (never the full body). Filter by state (repeatable / comma-separated), inbox, and category_id. Customer-scoped to the Clerk session; these human-authority reads/actions are console-only and never MCP tools (D17).

Authorizations

• ClerkSession
• AgentKey
  account:admin

Parameters

Path Parameters

org_id

required

string

project_id

required

string

Query Parameters

state

string

Filter by state (repeatable or comma-separated).

inbox

string

Filter by composer inbox address.

category_id

string

Filter by opaque category id (cat_…).

limit

integer

default: 50 >= 1 <= 100

Page size for the cursor-paginated agent surface (default 50; clamped to the 1-100 range).

page

string

Opaque page cursor.

Responses

200

Ok

object

items

required

Array<object>

One Approvals-queue row (console plane, D17). Metadata + intent summary + subject + a body snippet only; never the full body (loaded on detail open).

object

category_name

Human-readable category name; absent when unavailable.

string

recheck_status

Pending reconsideration; does not assert that the composer is online.

string

Allowed values: queued

recheck_completed_through_seq

Durable composer completion watermark independent of acknowledgement.

integer

recheck_outstanding_seq

Highest available unresolved recheck event sequence.

integer

recheck_reason

Cause of pending reconsideration.

string

id

required

string

state

required

string

Allowed values: needs_review in_review chatting stale approved sent auto_sent rejected stalled cancelled failed

mode

required

string

Allowed values: review direct

effective_mode

required

string

Allowed values: review direct

kind

required

string

Allowed values: send reply forward

from_address

string

from_display_name

Captured sender name for this review; empty means bare address. Absent on legacy reviews.

string

agent_id

string

category_id

string

intent_summary

string

subject

string

snippet

string

revision

required

integer

version

required

integer

stale_reason

string

gate_outcome

The auto-send divert reason (held:) when the submit-time gate routed this message to the human (M6); empty for an ordinary review.

string

escalation_reason

Why a reviewer-loop draft landed back in the human queue (M8; §9): a reviewer’s escalate, or a circuit breaker (max_hops / review_deadline) forcing it to the human. Empty for an ordinary review.

string

hop_count

The monotonic reviewer hand-back counter (M8 breaker (a)); surfaced so a maxed-out review reads as forced-to-human.

integer

created_at

string format: date-time

updated_at

string format: date-time

total

required

integer

next_cursor

string

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean