> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snakream.tonbo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Append

> Append data to an existing stream, or close it.

<ParamField path="bucket" type="string" required>
  Bucket ID.
</ParamField>

<ParamField path="stream" type="string" required>
  Stream ID within the bucket.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must match the stream's content type. Required when the body is non-empty.
</ParamField>

<ParamField header="Stream-Closed" type="string">
  Set to `true` to close the stream after this append.
</ParamField>

<ParamField header="If-Match" type="string">
  Conditional write: only succeed if the stream's ETag matches.
</ParamField>

<ParamField header="Stream-Seq" type="string">
  Client-supplied sequence token for conflict detection.
</ParamField>

<ParamField header="Producer-Id" type="string">
  Producer identity for [exactly-once writes](/concepts/exactly-once-writes).
</ParamField>

<ParamField header="Producer-Epoch" type="string">
  Producer epoch.
</ParamField>

<ParamField header="Producer-Seq" type="string">
  Producer sequence number.
</ParamField>

<ParamField body="body" type="binary" required>
  The bytes to append. Must not be empty unless `Stream-Closed: true` is set (close-only request).
</ParamField>

## Response

| Status | Meaning                                                                      |
| ------ | ---------------------------------------------------------------------------- |
| `200`  | Append successful.                                                           |
| `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.                     |
| `412`  | `If-Match` precondition failed.                                              |
| `503`  | Write backpressure. Retry after the duration in `Retry-After`.               |

Response headers include `Stream-Next-Offset` and `ETag`.

<RequestExample>
  ```bash Append binary theme={null}
  curl -X POST https://stream.tonbo.dev/ds/demo/hello \
    -H 'Content-Type: application/octet-stream' \
    --data-binary 'hello world'
  ```

  ```bash Append JSON theme={null}
  curl -X POST https://stream.tonbo.dev/ds/demo/hello \
    -H 'Content-Type: application/json' \
    --data-binary '{"event": "click", "ts": 1711234567}'
  ```

  ```bash Close a stream theme={null}
  curl -X POST https://stream.tonbo.dev/ds/demo/hello \
    -H 'Stream-Closed: true'
  ```
</RequestExample>

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