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
projectProject 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_messagesCap per call (default 10, max 100)
wait_secondsLong-poll up to this long when idle (max 25). Woken instantly when work lands
consumerName 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
404no subscription named {sub} in project {project}
POST/v1/subscriptions/{sub}/ackFinish deliveries — the lane moves on
Query parameters
projectProject 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
400delivery_ids must be an array
404no subscription named {sub} in project {project}
POST/v1/subscriptions/{sub}/nackFail deliveries now; the retry policy takes over
Query parameters
projectProject 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" }
errorRecorded on the attempt; DLQ groups by this signature
retry_afterOverrides the policy's backoff for this attempt
Response · 200
{ "results": [ { "delivery_id": "dlv_…", "ok": true } ] }
Errors
400delivery_ids must be an array
404no subscription named {sub} in project {project}
POST/v1/subscriptions/{sub}/extendBuy more time on the visibility lease
Query parameters
projectProject 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
400delivery_ids must be an array
404no subscription named {sub} in project {project}
← PublishAll topicsSubscriptions →