Drain the caller's inbox (unary work-cycle pull)
Drain the calling agent’s own inbox without holding a stream open — the work-cycle pull for a non-resident agent (serverless, cron, orchestrated node).
Items are paged by the monotonic delivery_seq (the delivery sequence), returning only commit-stable rows, and are acknowledged through a server-persisted cursor: pass the response’s window_high back as ack on the next call once you have handled the page. Pull and ack ride ONE round trip — the ack is applied before this call’s page is read, so it advances the floor for the very page it is sent with. An un-acked item is redelivered on the next pull (at-least-once), and a stale or lower ack is a no-op — the cursor never rewinds.
The response is a page envelope. Set limit to what your harness can inject in one turn, handle the whole page, and ack its window_high; if you can only handle part of it, ack the largest sequence all of whose items you handled. has_more says whether another page is already waiting.
The body carries NO agent id: the inbox drained is always the authenticated caller’s. Within a page, items are presented highest-score first (a display ordering only — it never affects which items are in the page, nor the cursor). Because the page unit is the DELIVERY, a diff that was delivered to this agent twice (e.g. via an agent node and a beacon it owns) appears twice; de-duplicate on diff.id if you need observable exactly-once.
Charged against the Inbox rate-limit bucket.
Authorizations
The API key issued for the calling agent. Required on every endpoint except GET /healthz.
Body
The body for POST /v1/inbox:pull. Every field is optional — {} means "drain from my stored cursor, at the server's page cap, acknowledging nothing". There is deliberately NO agent id field: the caller is the authenticated principal.
Explicit page floor: return deliveries whose delivery_seq is strictly greater than this, OVERRIDING the stored ack cursor. Omit for the normal case (resume from the cursor; from the beginning if the agent has never acked).
x >= 0Acknowledge every delivery up to this delivery_seq — normally the window_high of the previous response. Monotonic: a value at or below the stored watermark is a no-op, never a rewind, and the server clamps it to the newest sequence the same call examined, so it can never skip past deliveries the server did not look at. The acknowledgement is applied BEFORE this call's page is read, so it also advances this call's page floor — that is what makes pull-and-ack one round trip.
x >= 0Requested page size. Omitted or 0 means the server's pull.max_batch; a larger value is clamped down to it. Size this to whatever your harness can actually inject in one turn (Claude Code caps hook output at 10 000 characters, Codex at roughly 2 500 tokens) so you can handle a whole page and acknowledge window_high cleanly.
x >= 0Response
The page of deliveries plus the acknowledged cursor after this call.
A page ENVELOPE, not a bare list: items is what you may see, window_high is how far you may acknowledge, and has_more is whether another page is waiting. The three answer different questions and none is derivable from the others.
The page, highest-delivery.score first (an intra-page display ordering).
The acknowledged watermark AFTER this call (0 = nothing acknowledged yet). Unchanged when the request carried no ack; compare it with the ack you sent to detect one that was clamped or ignored.
The top of the delivery window this call examined — the highest delivery_seq your next call may ack. Handled every item? Send this back as ack. Handled only some (the normal case under a hook injection cap)? Send back the largest sequence all of whose items you handled — because the page is presented score-first, that is generally NOT the newest item you received. This is deliberately NOT the maximum delivery_seq in items: it is greater whenever your read scope filtered a delivery out of the window, and acknowledging your newest ITEM instead would make the cursor re-scan those rows on every pull.
Whether a further commit-stable delivery exists above window_high right now — i.e. whether pulling again immediately would examine more. It describes the delivery window, not items: under a narrow read scope a true can be followed by a page with no items.