List review requests (Review Loop, agent plane)
GET /v1/reviews
List the customer’s review requests so a sending agent can monitor its submissions. Filter by state (repeatable / comma-separated), category_id, and inbox. Customer-scoped; human-authority actions are console-only.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Restrict to the calling composer for pending-work recovery.
Filter by canonical conversation ID. Combine with inbox and active states to discover existing response work across authorized composers before creating a reply.
Filter by state (repeatable or comma-separated, e.g. needs_review).
Filter by opaque category id (cat_…).
Filter by composer inbox address.
Page size for the cursor-paginated agent surface (default 50; clamped to the 1-100 range).
Opaque page cursor.
Responses
Section titled “ Responses ”Ok
object
A review request (rr_…); the server-owned pre-send record of a message under the Review Loop. Carries intent, the current proposed draft, category, state machine fields, and (once sent) the sent body + diff.
object
Human-readable category name; absent when unavailable.
Pending reconsideration; does not assert that the composer is online.
Durable composer completion watermark independent of acknowledgement.
Highest available unresolved recheck event sequence.
Cause of pending reconsideration.
Console path to this draft. Sign in and claim the workspace if prompted before reviewing.
Captured sender name for this review; empty means bare address. Absent on legacy reviews.
object
Mail conversation ID for fetching reply or forward context; distinct from reviewer feedback.
Conversation snapshot used for this draft. Absent on legacy drafts whose composition context is unknown.
Newest message observed when composing this draft.
Message selectors in the conversation snapshot used for this draft; does not certify semantic comprehension.
Opaque parent message ID for replies; raw RFC5322 Message-ID for plain sends.
True once this review will never move again; sent, auto_sent, cancelled OR failed. It is the definitive per-review “am I done?” answer and the poll-side companion to the terminal review events; use it after a restart when your event cursor is gone. failed is included deliberately: nothing re-approves a failed review, so treating it as open means waiting forever.
Vendor-scrubbed delivery failure, present on a failed review.
How the message was released, once sent.
Missing or invalid credential.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-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.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.
Authenticated but lacking the required scope, or out of quota.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-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.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.