Append

Last updated 29 October 2026

Append messages to a stream from any program, exactly once even when it retries, and close the stream when its writer is done.

A stream speaks the open Durable Streams protocol at its URL, so any HTTP client works, and a client library of the protocol can append and read with a Tonbo key. The examples use curl with the stream’s URL in STREAM and an API key in TONBO_API_KEY, as the quickstart sets them. A stream named events is at:

https://streams.tonbo.dev/<account-id>/s.events

Its last segment is the stream’s name after s., and the segment before it is your account’s id. Every request carries the key, or a token made from it, as Authorization: Bearer, unless the stream is public and the request only reads (see Access). Reading the stream is on Read and tail, and summarizing it on Snapshots and retention.

Content types and JSON mode

A stream’s content type is chosen when it is created, application/octet-stream when none is named, and never changes. Every append sends exactly it as Content-Type; any other answers 409 with the code CONTENT_TYPE_MISMATCH and appends nothing.

A stream of application/json is in JSON mode. Each append must be valid JSON, and Tonbo keeps each message as you wrote it, without insignificant whitespace; a body that is a JSON array appends one message per element (see JSON message text). Reads return the messages as newline-delimited JSON, application/x-ndjson, one message per line. Any other content type is bytes: a read returns them as they were appended.

Append

POST to the stream’s URL appends the body. Send each append with a producer id, an epoch and a sequence number, so a retry never appends it twice:

curl -sS -i -X POST "$STREAM" \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Producer-Id: quickstart" \
  -H "Producer-Epoch: 0" \
  -H "Producer-Seq: 0" \
  -d '{"n":0}'

• Producer-Id names the writer, such as a host or a job; it is kept per stream.
• Producer-Seq starts at 0 and goes up by exactly one per append.
• Producer-Epoch goes up when the writer restarts and has lost its count; a new epoch starts its sequence at 0 again. Keep the epoch where the writer keeps its state and add one at each restart: it must never be below the last epoch the stream saw from that producer.

The next append in sequence answers 200 with Stream-Offset, where it starts, and Stream-Next-Offset, where it ends. The same append sent again, after a timeout or a 5xx, answers 204 with the same two offsets and appends nothing, so when an answer is lost, send the same request again. A sequence number that skips ahead answers 409, and a write of an older epoch 403: a newer instance of the writer has taken its place, and this one should stop. Ursula, the open-source server Tonbo runs streams on, documents every case in exactly-once writes and producer write answers. A writer that has not appended for 7 days is forgotten, and its next append starts a new sequence. What happens to an append says, answer by answer, whether it applied.

Batch messages

A JSON array appends all its elements in one request, one message each, in order. An append costs one write per 10 KiB of its body and at least one, so a hundred small messages in one append cost one write where a hundred appends cost a hundred (see the worked example), and they count once against the account’s requests per second. Each body is at most 8 MiB (see Limits).

Without producer headers

An append without producer headers answers 204 and is not deduplicated, which suits writers whose repeats do no harm. To append only when nothing else has been appended since you last read, use Stream-Seq (see conditional writes). The append reference lists every header and answer.

Close

An append with Stream-Closed: true closes the stream, with its body as the last message or with no body at all:

curl -sS -i -X POST "$STREAM" \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Stream-Closed: true"

It answers 204 with Stream-Closed: true and the end of the stream as Stream-Next-Offset. Closing cannot be undone. The stream keeps what it holds, stays readable and still counts toward the account until it is deleted, and every later append answers 409 with Stream-Closed: true. Readers at the end learn it at once (see A closed stream).

When an append is refused

The table says, for each refusal an append can get, whether to send it again. With producer headers, the same request sent again never applies twice, so when in doubt, send it again unchanged. Troubleshooting lists every refusal.