API reference / Consume
Consume scope: consume
Long-poll receive with per-message leases, ack, nack, and lease extension — per-key ordering enforced broker-side.
Leases are per message; per-key ordering is enforced broker-side — at most one message per (subscription, key) is ever in flight.
POST/v1/subscriptions/{sub}/receiveLong-poll for leased messages
Query parameters
| project | Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side. |
Request body
{ "max_messages": 10, "wait_seconds": 20, "consumer": "worker-1" }| max_messages | Cap per call (default 10, max 100) |
| wait_seconds | Long-poll up to this long when idle (max 25). Woken instantly when work lands |
| consumer | Name recorded on the lease and in the trace |
Response · 200
{ "messages": [ {
"delivery_id": "dlv_1m1b9kpp677szfce3zzh7",
"attempt": 1,
"lease_expires_at": "2026-08-31T10:15:30.000Z",
"message": {
"id": "msg_1m1b9kb5qvvcqn0tc334f",
"stream": "orders", "project": "payments",
"key": "tenant_42",
"payload": { "order_id": 8891 }, … }
} ] }Errors
| 404 | no subscription named {sub} in project {project} |
POST/v1/subscriptions/{sub}/ackFinish deliveries — the lane moves on
Query parameters
| project | Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side. |
Request body
{ "delivery_ids": ["dlv_…"] }Response · 200
{ "results": [
{ "delivery_id": "dlv_…", "ok": true },
{ "delivery_id": "dlv_bad", "ok": false, "error": "unknown delivery id" }
] }Errors
| 400 | delivery_ids must be an array |
| 404 | no subscription named {sub} in project {project} |
POST/v1/subscriptions/{sub}/nackFail deliveries now; the retry policy takes over
Query parameters
| project | Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side. |
Request body
{ "delivery_ids": ["dlv_…"],
"error": "downstream 500",
"retry_after": "30s" }| error | Recorded on the attempt; DLQ groups by this signature |
| retry_after | Overrides the policy's backoff for this attempt |
Response · 200
{ "results": [ { "delivery_id": "dlv_…", "ok": true } ] }Errors
| 400 | delivery_ids must be an array |
| 404 | no subscription named {sub} in project {project} |
POST/v1/subscriptions/{sub}/extendBuy more time on the visibility lease
Query parameters
| project | Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side. |
Request body
{ "delivery_ids": ["dlv_…"], "seconds": 60 }Response · 200
{ "results": [ { "delivery_id": "dlv_…", "ok": true,
"lease_expires_at": "2026-08-31T10:16:30.000Z" } ] }Errors
| 400 | delivery_ids must be an array |
| 404 | no subscription named {sub} in project {project} |