> ## 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.

# API overview

> Learn the public Snakream HTTP routes for creating, appending, reading, and replaying streams.

Snakream exposes a small public HTTP API for durable append-only streams. Most users only need the `/ds/{bucket}/{stream}` route family, which maps cleanly to buckets and stream IDs.

This API is Snakream's implementation of the [Durable Streams Protocol](/specs/durable-stream), defined by the durable-streams community, with additional route families for compatibility and deployment needs.

## Bucket operations

| Method   | Path                   | Description                                   |
| -------- | ---------------------- | --------------------------------------------- |
| `PUT`    | `/ds/{bucket}`         | [Create a bucket](/api/create-bucket)         |
| `GET`    | `/ds/{bucket}`         | [Get bucket metadata](/api/get-bucket)        |
| `DELETE` | `/ds/{bucket}`         | [Delete a bucket](/api/delete-bucket)         |
| `GET`    | `/ds/{bucket}/streams` | [List streams in a bucket](/api/list-streams) |

## Stream operations

| Method   | Path                    | Description                                  |
| -------- | ----------------------- | -------------------------------------------- |
| `PUT`    | `/ds/{bucket}/{stream}` | [Create a stream](/api/create-stream)        |
| `POST`   | `/ds/{bucket}/{stream}` | [Append data or close](/api/append)          |
| `GET`    | `/ds/{bucket}/{stream}` | [Read (catch-up, long-poll, SSE)](/api/read) |
| `HEAD`   | `/ds/{bucket}/{stream}` | [Get stream metadata](/api/head-stream)      |
| `DELETE` | `/ds/{bucket}/{stream}` | [Delete a stream](/api/delete-stream)        |

## Bootstrap and snapshots

| Method | Path                                      | Description                                   |
| ------ | ----------------------------------------- | --------------------------------------------- |
| `GET`  | `/ds/{bucket}/{stream}/bootstrap`         | [Snapshot + tail replay](/api/bootstrap)      |
| `GET`  | `/ds/{bucket}/{stream}/snapshot`          | [Read latest snapshot](/api/read-snapshot)    |
| `GET`  | `/ds/{bucket}/{stream}/snapshot/{offset}` | [Read snapshot at offset](/api/read-snapshot) |
| `PUT`  | `/ds/{bucket}/{stream}/snapshot/{offset}` | [Publish a snapshot](/api/publish-snapshot)   |

## v1 compatibility

A flat [v1 compatibility layer](/api/v1-compatibility) is also available under `/v1/stream/{path}` for simpler integrations that don't need explicit bucket management.

## Common request patterns

### Create a bucket and stream

```bash theme={null}
curl -X PUT https://stream.tonbo.dev/ds/demo
curl -X PUT https://stream.tonbo.dev/ds/demo/hello
```

### Append data

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

### Read from the beginning

```bash theme={null}
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1'
```

### Subscribe with SSE

```bash theme={null}
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1&live=sse'
```

## Related concepts

* [Read modes](/concepts/read-modes): catch-up vs long-poll vs SSE
* [Bootstrap](/concepts/bootstrap): snapshot + tail recovery
* [Snapshots](/concepts/snapshots): snapshot lifecycle
* [Exactly-once writes](/concepts/exactly-once-writes): producer deduplication
* [Conditional writes](/concepts/conditional-writes): ETag and sequence-based writes