Streams HTTP API

Last updated 2 November 2026

Every request a stream’s URL serves, with each header, query parameter and answer it takes, so a program can append to and read a stream with any HTTP client.

A stream speaks the open Durable Streams protocol and the extensions of Ursula, the server Tonbo runs streams on, at release 0.11.3 (protocol, extensions). Each row below cites the section it rests on. Creating, listing and deleting streams is the Management API’s, not the stream URL’s (below).

Operations

The stream’s URL

Every request goes to the stream’s URL, which the Management API returns as url when it creates or shows the stream (Read a stream) and tonbo stream show prints:

{streams-origin}/{account-id}/s.{name}

The origin is the Streams origin of the stream’s region (Regions and URLs), then your account’s id and the stream’s name after s., as they are, without encoding. Paths under it name the stream’s snapshots, retention, bootstrap and cacheable reads. The examples keep the URL in STREAM, an API key in TONBO_API_KEY, an offset in OFFSET and a Stream-Incarnation in INCARNATION.

Credentials

A request carries an API key or a Streams token as Authorization: Bearer. A key works directly; a token comes from the token exchange, which can narrow it to some streams and to reading, and is the only way for an Agent’s key. A read of a public stream needs neither; every write does. A read-only key or token reads, tails and reads snapshots, and every other request answers 403. An SSE tail opened with a token ends with a credential-expired event at its expiry.

Headers on every request

Content types and JSON mode

A stream’s content type is fixed when it is created, and every append sends exactly it. A stream of application/json is in JSON mode: each append is validated as JSON, nested at most 127 deep; a top-level array appends one message per element; and each message is kept as it was written, without insignificant whitespace, its members, numbers and strings untouched. Reads return its messages as application/x-ndjson, one per line (protocol 7, extensions JSON Message Text). Any other content type is bytes, read back as they were appended; an SSE tail sends them base64-encoded unless the type is text/*.

Offsets

An offset names a position in the stream. It is an opaque, case-sensitive string: keep it as an answer gave it, in Stream-Next-Offset or streamNextOffset. Two offsets of one stream compare as strings in stream order, and an offset stays valid for as long as the stream holds it. -1 is the start of the stream and now its current end; neither is ever an answer’s offset. URL-encode an offset in a query or a path (protocol 6, extensions 8). An offset means nothing to a stream deleted and created again, so keep the stream’s Stream-Incarnation with any offset you keep.

Through the Management API

A stream’s URL never creates or deletes it, and has no lifetime of its own. What the protocol does there, Tonbo does through the Management API, the console and the CLI:

Error codes

A refusal is a status and, in most cases, a JSON body that names it:

{"error":{"code":"CONTENT_TYPE_MISMATCH","message":"…"}}

Match code, never message, which is for people and may change. A code you do not know is read by its status and headers, and the headers keep their meaning: a 413 names its limit, a 503 carries Retry-After, and a producer refusal carries Producer-Outcome. A body may be missing, and a HEAD answer has none. The codes of each status (extensions 11), of which Troubleshooting explains the ones a program meets:

Write outcomes

Whether a write applied, when its answer leaves doubt, follows from its answer alone (extensions 11.1):

• A 2xx with the write’s typed answer applied it: a producer write’s Stream-Offset and Stream-Next-Offset, an append’s or a close’s Stream-Next-Offset, a snapshot’s Stream-Snapshot-Digest, a part’s Stream-Snapshot-Part, retention’s Stream-Retained-Offset. A 2xx without it says nothing.
• A 4xx other than 408 refused it: nothing of it applied, and nothing will.
• A 408 or a 5xx refused it only when its code is one of the list below. Any other, and a request that got no answer, may have applied: send the same request again. With producer headers it applies once; without them, it may apply twice.

A read changes nothing, so sending one again is always safe. A refusal speaks for its own request only: whether an earlier attempt under the same producer key applied, only a receipt or a producer 403 says.

Limits

Each account gets at least 50 requests a second and 16 open tails at once in each region, for its streams and databases together, past which a request answers 429 with Retry-After. A request body is at most 8 MiB, as HEAD reports in Ursula-Max-Request-Bytes, and one read answer at most 8 MiB. Every limit is on Limits.

Versions

Tonbo runs the Ursula 0.11 line, which every answer from the server names in Ursula-Protocol. Releases of one line keep the protocol; an answer may gain headers and an error body may gain codes and members, which a client ignores. This reference follows the specifications at v0.11.3.