Streams scope: manage · reads: read

Create, configure, browse, and delete streams — named durable logs with per-stream retention and backlog caps.

A stream is a named, durable log inside a project. Explicit creation is optional — the first publish creates it — but lets you set retention and a backlog cap up front.

GET/v1/streamsList streams

Query parameters

project	Filter to one project. Omitted = all projects (dashboard view). Project API keys always see only their own.

Response · 200

{ "streams": [ {
  "name": "orders", "project": "payments",
  "messages": 1204, "active_keys": 3, "scheduled": 2,
  "subscriptions": ["billing-worker", "notifier"],
  "created_at": "2026-08-30T08:00:00.000Z"
} ] }

POST/v1/streamsCreate a stream explicitly

Request body

{ "name": "orders", "project": "payments",
  "retention": "30d", "max_backlog": 50000 }

name	Required. Letters, digits, dot, dash, underscore. Unique per project, not globally
project	Optional; also accepted as ?project=. Default "default"
retention	Optional duration ("7d", "12h") or "forever". Default: DEFAULT_RETENTION (7d)
max_backlog	Optional backpressure cap: publishes 429 once undelivered backlog crosses it

Response · 200

{ "name": "orders", "project": "payments", "created": true }

Errors

400	missing/invalid name, retention, or max_backlog
404	no project named {project}
409	a stream named {name} already exists in project {project}

GET/v1/streams/{stream}Settings + message count

Query parameters

project	Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side.

Response · 200

{ "name": "orders", "project": "payments", "messages": 1204,
  "retention": "30d", "effective_retention_ms": 2592000000,
  "max_backlog": 50000, "effective_max_backlog": 50000,
  "created_at": "2026-08-30T08:00:00.000Z" }

Errors

404	no stream named {stream} in project {project}

PATCH/v1/streams/{stream}Change retention / backlog cap

Query parameters

project	Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side.

Request body

{ "retention": "forever", "max_backlog": null }

retention	Duration or "forever"
max_backlog	Positive integer; null or 0 clears the cap

Response · 200

{ "name": "orders", "project": "payments",
  "retention": "forever", "max_backlog": null }

Errors

400	nothing to update, or invalid values
404	no stream named {stream} in project {project}

DELETE/v1/streams/{stream}Delete the stream and its messages permanently

Query parameters

project	Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side.

Response · 200

{ "name": "orders", "project": "payments",
  "deleted": true, "messages_deleted": 1204 }

Errors

404	no stream named {stream} in project {project}
409	delete this stream's subscriptions first: …

GET/v1/streams/{stream}/messagesBrowse messages, newest first

Query parameters

project	Project the name is scoped to. Omitted = "default". Ignored for project API keys — their project is enforced server-side.
key	Only this key
status	scheduled \| available \| cancelled \| expired
q	Payload contains this substring
limit	Max rows (default 100, cap 500)
before_offset	Page backwards from this offset

Response · 200

{ "messages": [ {
    "id": "msg_1m1b9kb5qvvcqn0tc334f",
    "stream": "orders", "project": "payments",
    "key": "tenant_42",
    "payload": { "order_id": 8891 },
    "headers": { "region": "in" },
    "idempotency_key": "order-8891-created",
    "deliver_at": null, "expires_at": null,
    "published_at": "2026-08-31T10:15:00.000Z",
    "offset": 41, "status": "available"
  } ] }

All topics Publish →