Drain review events (non-blocking)

GET

/v1/reviews/events

• Production
• Local

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

• AgentKey
  mailbox:read

Parameters

Query Parameters

review_id

string

Restrict the drain to one review’s events (rr_…).

limit

integer

default: 50 >= 1 <= 100

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

Responses

200

Ok

The drain result for list_review_events / wait_for_review_event; un-acked events in FIFO seq order plus the per-review cursors.

object

events

required

Array<object>

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

seq

required

integer

id

required

string

reason

required

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.

string

Allowed values: redraft_requested feedback_added recheck_category staleness approved rejected front_run_next rule_changed propagate_general_rule sent send_failed cancelled

review_id

string

category_id

string

payload

object

key

additional properties

any

created_at

required

string format: date-time

cursors

Array<object>

The agent’s per-(agent, review) ack frontier; its strict-FIFO position for one review.

object

review_id

required

string

last_acked_seq

required

integer

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

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