Pubsub

Package pubsub is your message bus: publish, subscribe, and durable streams your apps read at their own pace.

pubsub

POST /v1/pubsub/jetstream/streams/{stream}/consumers/{name}/next

Fetch pulls the next batch from a consumer and acknowledges it — the request/response way to consume a stream. The hand-off is at-most-once: a message returned here is acked here, so a caller that loses the response does not see it again. Workers needing at-least-once delivery consume the same consumer over the NATS port, where acks are theirs to send. An empty batch after the wait is an empty page, not an error.

Request body — application/json (required)

GET /v1/pubsub/jetstream/streams/{stream}/consumers/{name}

Returns one consumer of one org stream — its configuration and its cursor: delivered and acknowledged sequences, pending and redelivered counts. 404 when the stream or the consumer does not exist.

DELETE /v1/pubsub/jetstream/streams/{stream}/consumers/{name}

Removes one consumer — its cursor, not the stream's messages — and answers 204 with no body. 404 when the stream or the consumer does not exist.

GET /v1/pubsub/jetstream/streams/{stream}/consumers

Returns one stream's consumers, sorted by name. 404 when the org has no stream of that name.

POST /v1/pubsub/jetstream/streams/{stream}/consumers

Creates a durable consumer on one stream and returns it. A consumer is a named cursor: it tracks what has been delivered and what is acknowledged, so many workers can share it and none sees a message twice outside redelivery. 409 when the stream already has a consumer of that name with a different configuration.

Request body — application/json (required)

GET /v1/pubsub/jetstream/streams/{stream}

Returns one stream of the caller's org — its configuration and its live state (messages, bytes, sequence range, consumer count). 404 when the org has no stream of that name.

PUT /v1/pubsub/jetstream/streams/{stream}

Rewrites a stream's configuration — subjects, limits, discard — and returns the updated stream. It is a PUT: the spec sent replaces the spec held, with one reading for the enums a caller omits — an empty storage, retention or discard keeps the stream's current one, because JetStream holds storage and retention immutable and refuses a change with a 400 rather than this door pretending it took.

Request body — application/json (required)

DELETE /v1/pubsub/jetstream/streams/{stream}

Removes one stream of the caller's org — its retained messages and its consumers with it — and answers 204 with no body. 404 when the org has no stream of that name.

GET /v1/pubsub/jetstream/streams

Returns the org's streams, sorted by name.

A stream is the durable log: it captures every message published to its subjects and retains them by its own limits, independent of any consumer. The listing is org-scoped server-side — one org can never see another's streams, and the platform's own planes never appear.

POST /v1/pubsub/jetstream/streams

Creates a durable stream capturing the given subjects and returns it. 409 when the org already has a stream of that name; the subjects are the org's own and cannot collide with another org's.

Request body — application/json (required)

GET /v1/pubsub/kv/{bucket}/{key}/history

History returns one key's retained revisions, oldest first — every put and every delete marker up to the bucket's History depth. 404 when the bucket does not exist or the key was never written.

GET /v1/pubsub/kv/{bucket}/{key}

Get returns one key's current value and revision. 404 when the bucket does not exist, the key was never written, or its latest revision is a delete.

PUT /v1/pubsub/kv/{bucket}/{key}

Put sets one key to one value and returns the revision the write created. Writes are versioned: each put is a new revision and the bucket retains up to its History of them per key.

Request body — application/json (required)

DELETE /v1/pubsub/kv/{bucket}/{key}

Delete removes one key — a delete marker in the key's history, so watchers see it and Get answers 404 — and answers 204 with no body. 404 when the bucket does not exist.

POST /v1/pubsub/kv/{bucket}

Creates a KV bucket and returns it. A bucket is keyed state on the same durable plane as the streams: each key holds up to History revisions, entries can expire by TTL, and watchers on the NATS port see every write. 409 when the org already has a bucket of that name.

Request body — application/json (required)

DELETE /v1/pubsub/kv/{bucket}

Removes one bucket of the caller's org — every key and every revision with it — and answers 204 with no body. 404 when the org has no bucket of that name.

POST /v1/pubsub/publish

Publish puts one message on the org's bus. When a stream captures the subject the write is DURABLE — the receipt names the stream and sequence only after JetStream has it on storage, and a repeated Nats-Msg-Id header within the dedup window answers duplicate instead of storing twice. When nothing captures it, the message goes out core NATS: delivered to current subscribers, receipt {ok}, nothing retained.

Request body — application/json (required)

POST /v1/pubsub/request

Request sends one request on the org's bus and waits for one reply — the synchronous half of pub/sub, for callers speaking to a responder subscribed on the NATS port. 404 when nobody is listening on the subject; 408 when a responder exists but no reply arrived within the timeout.

Request body — application/json (required)

---

Pubsub guide · All Hanzo APIs · Interactive reference