Append

bucketpathstringrequired

Bucket ID.

streampathstringrequired

Stream ID within the bucket.

Content-Typeheaderstringrequired

Must match the stream's content type (set at PUT or first POST). Required when the body is non-empty. Mismatch returns 400.

Stream-Closedheaderstring

Set to true to close the stream after this append.

Stream-Seqheaderstring

Client-supplied monotonic sequence token. The server tracks the last accepted value per stream and rejects any append whose Stream-Seq is not lexicographically greater than the previous one.

Producer-Idheaderstring

Stable producer identity (UUID, hostname, etc.) for exactly-once writes. Dedup state is per-stream.

Producer-Epochheaderstring

Producer epoch. Bumped on producer restart. Must be ≥ the last epoch the server accepted for this Producer-Id. A new epoch resets the seq counter. Max value 2^53 − 1.

Producer-Seqheaderstring

Producer sequence number. Starts at 0 for a new epoch and must increase by exactly 1 per append. Exact (epoch, seq) duplicates are silently deduplicated. Max value 2^53 − 1.

bodybodybinaryrequired

The bytes to append. Must not be empty unless Stream-Closed: true is set (close-only request).

Response

Status	Meaning
`204`	Append successful (default success response, no body).
`200`	Append successful with body - returned when a `Producer-Id` was supplied and the append was not deduplicated, so the response carries producer ack headers.
`400`	Empty body without `Stream-Closed: true`, missing content type, or bad JSON.
`404`	Stream not found.
`409`	Stream is already closed, or sequence/producer conflict.
`503`	Cold-write backpressure. Retry after the duration in `Retry-After`.

Response headers include Stream-Next-Offset (always). When a Producer-Id was supplied, the server echoes the accepted Producer-Epoch and Producer-Seq so the producer can confirm what was durably recorded. Stream-Closed: true is set if this request closed the stream. ETag is set on reads only, not on appends.

curl -X POST http://127.0.0.1:4437/demo/hello \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'hello world'

curl -X POST http://127.0.0.1:4437/demo/hello \
  -H 'Content-Type: application/json' \
  --data-binary '{"event": "click", "ts": 1711234567}'

curl -X POST http://127.0.0.1:4437/demo/hello \
  -H 'Stream-Closed: true'

Appends to JSON streams are validated and normalized. The server may coalesce multiple concurrent appends into a single batch for performance.