Skip to main content
Tonbo Stream 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.

​
Bucket operations

MethodPathDescription
PUT/ds/{bucket}Create a bucket
GET/ds/{bucket}Get bucket metadata
DELETE/ds/{bucket}Delete a bucket
GET/ds/{bucket}/streamsList streams in a bucket

​
Stream operations

MethodPathDescription
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

MethodPathDescription
GET/ds/{bucket}/{stream}/bootstrapSnapshot + tail replay
GET/ds/{bucket}/{stream}/snapshotRead 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'

​
Subscribe with SSE

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