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
projectProject 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" }
keyOrdering scope: same key = strict order, one at a time. Omitted = random key (max parallelism)
payloadRequired. Any JSON value
headersString map; subscriptions can filter on exact matches
idempotency_keyDuplicate publishes within DEDUP_WINDOW (24h) return the original id
deliver_atFuture timestamp = scheduled: invisible until then, cancellable
expires_atUndelivered 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
400payload missing, or deliver_at / expires_at not a valid timestamp
413payload over MAX_MESSAGE_BYTES (default 1 MB)
429stream backlog over its cap — back off and retry
POST/v1/streams/{stream}/messages/batchPublish many, in order
Query parameters
projectProject 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
400messages must be an array (item errors abort the batch at that item)
413an item over the size limit
429backpressure
DELETE/v1/messages/{id}Cancel a scheduled message before it fires
Response · 200
{ "id": "msg_…", "status": "cancelled" }
Errors
404no message with id {id}
409message is {status}; only scheduled messages can be cancelled
403a project API key naming a resource outside its project
← StreamsAll topicsConsume →