Drain review events (non-blocking)
GET /v1/reviews/events
Non-blocking drain of the next un-acked review nudges for the calling agent, in strict-FIFO-per-review seq order (best-effort across reviews), with the per-review cursors. The durable nudge queue is the authoritative liveness source; webhook/SSE are best-effort fast paths on top of it. Side-effect free and idempotent; re-calling returns the same frontier until an ack advances the cursor. Customer-scoped.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Restrict the drain to one review’s events (rr_…).
Page size for the cursor-paginated agent surface (default 50; clamped to the 1-100 range).
Responses
Section titled “ Responses ”Ok
Durable attention for reviews the caller may access, including feedback and rule/category changes. Omit review_id for one shared wait. Reconnect with the same identity to replay unhandled events; waiting never acknowledges work. Events are FIFO per review, with persisted cursors. Delegated observations survive composer acknowledgements.
object
Authoritative outcome for an authorized review-specific read or wait, including when every event has been acknowledged.
object
Remaining active reviews within this wait’s authorized resource and optional review_id boundary; legacy keys retain their composer ceiling. Included on an empty wait.
One durable review nudge (ndg_…) as drained from the authoritative liveness queue (spec §11). seq is the per-review monotonic ordinal the ack cursor advances against (0 for a broadcast nudge). Opaque typed ids only (D10).
object
The work-item kind. sent / send_failed / cancelled are TERMINAL: the LAST event a review ever produces is one of these; ack it and stop polling that review. (Almost every review emits exactly one; a failed send the agent then closes out emits send_failed and then cancelled.) sent covers both delivery flavors; payload.state distinguishes sent from auto_sent. approved and staleness are RESERVED and never emitted (kept so the enum is never narrowed). Treat an unrecognized reason as ack-and-ignore: this enum is additive across 0.x releases.
object
The agent’s per-(agent, review) ack frontier; its strict-FIFO position for one review.
object
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.