API overview

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, 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
`GET`	`/ds/{bucket}`	Get bucket metadata
`DELETE`	`/ds/{bucket}`	Delete a bucket
`GET`	`/ds/{bucket}/streams`	List streams in a bucket

Stream operations

Method	Path	Description
`PUT`	`/ds/{bucket}/{stream}`	Create a stream
`POST`	`/ds/{bucket}/{stream}`	Append data or close
`GET`	`/ds/{bucket}/{stream}`	Read (catch-up, long-poll, SSE)
`HEAD`	`/ds/{bucket}/{stream}`	Get stream metadata
`DELETE`	`/ds/{bucket}/{stream}`	Delete a stream

Bootstrap and snapshots

Method	Path	Description
`GET`	`/ds/{bucket}/{stream}/bootstrap`	Snapshot + tail replay
`GET`	`/ds/{bucket}/{stream}/snapshot`	Read latest snapshot
`GET`	`/ds/{bucket}/{stream}/snapshot/{offset}`	Read snapshot at offset
`PUT`	`/ds/{bucket}/{stream}/snapshot/{offset}`	Publish a snapshot

v1 compatibility

A flat v1 compatibility layer 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

curl -X PUT https://stream.tonbo.dev/ds/demo
curl -X PUT https://stream.tonbo.dev/ds/demo/hello

Append data

curl -X POST https://stream.tonbo.dev/ds/demo/hello \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'hello world'

Read from the beginning

curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1'

curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1&live=sse'

Read modes: catch-up vs long-poll vs SSE
Bootstrap: snapshot + tail recovery
Snapshots: snapshot lifecycle
Exactly-once writes: producer deduplication
Conditional writes: ETag and sequence-based writes

Getting Started

Concepts

Architecture

API

Protocol Specification

Comparisons

Bucket operations

Stream operations

Bootstrap and snapshots

v1 compatibility

Common request patterns

Create a bucket and stream

Append data

Read from the beginning

​Bucket operations

​Stream operations

​Bootstrap and snapshots

​v1 compatibility

​Common request patterns

​Create a bucket and stream

​Append data

​Read from the beginning

​Subscribe with SSE

​Related concepts

Bucket operations

Stream operations

Bootstrap and snapshots

v1 compatibility

Common request patterns

Create a bucket and stream

Append data

Read from the beginning

Subscribe with SSE

Related concepts