API reference / Publish
Publish scope: publish
Publish messages one at a time or in ordered batches, with idempotency keys, headers, scheduled delivery, and expiry.
POST/v1/streams/{stream}/messagesPublish one message
Query parameters
| project | Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side. |
Request body
{ "key": "tenant_42",
"payload": { "order_id": 8891 },
"headers": { "region": "in" },
"idempotency_key": "order-8891-created",
"deliver_at": "2026-09-01T10:00:00Z",
"expires_at": "2026-09-07T00:00:00Z" }| key | Ordering scope: same key = strict order, one at a time. Omitted = random key (max parallelism) |
| payload | Required. Any JSON value |
| headers | String map; subscriptions can filter on exact matches |
| idempotency_key | Duplicate publishes within DEDUP_WINDOW (24h) return the original id |
| deliver_at | Future timestamp = scheduled: invisible until then, cancellable |
| expires_at | Undelivered deliveries expire at this time |
Response · 200
{ "id": "msg_1m1b9kb5qvvcqn0tc334f", "offset": 41,
"status": "available", "deduplicated": false }
// duplicate idempotency_key within the window:
{ "id": "msg_<original>", "offset": -1,
"status": "deduplicated", "deduplicated": true }Errors
| 400 | payload missing, or deliver_at / expires_at not a valid timestamp |
| 413 | payload over MAX_MESSAGE_BYTES (default 1 MB) |
| 429 | stream backlog over its cap — back off and retry |
POST/v1/streams/{stream}/messages/batchPublish many, in order
Query parameters
| project | Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side. |
Request body
{ "messages": [
{ "key": "t1", "payload": { "n": 1 } },
{ "key": "t1", "payload": { "n": 2 } }
] }Response · 200
{ "results": [
{ "id": "msg_…", "offset": 42, "status": "available", "deduplicated": false },
{ "id": "msg_…", "offset": 43, "status": "available", "deduplicated": false }
] }Errors
| 400 | messages must be an array (item errors abort the batch at that item) |
| 413 | an item over the size limit |
| 429 | backpressure |
DELETE/v1/messages/{id}Cancel a scheduled message before it fires
Response · 200
{ "id": "msg_…", "status": "cancelled" }Errors
| 404 | no message with id {id} |
| 409 | message is {status}; only scheduled messages can be cancelled |
| 403 | a project API key naming a resource outside its project |