v1 compatibility

Snakream provides a compatibility layer under /v1/stream/ that implements the Durable Streams Protocol, defined by the durable-streams community, with a flat path model. This is useful when you want a simpler path structure without explicit bucket management.

Path mapping

The v1 path is mapped to the bucket/stream model using the first / as the separator:

v1 path	Bucket	Stream
`/v1/stream/mystream`	`_default`	`mystream`
`/v1/stream/workspace/mystream`	`workspace`	`mystream`
`/v1/stream/a/b/c`	`a`	`b/c`

Paths without a / are placed in the _default bucket.

Routes

These routes accept the same headers, query parameters, and body formats as their /ds/{bucket}/{stream} equivalents:

Method	Path	Equivalent
`PUT`	`/v1/stream/{path}`	Create stream
`POST`	`/v1/stream/{path}`	Append
`GET`	`/v1/stream/{path}`	Read
`HEAD`	`/v1/stream/{path}`	Head stream
`DELETE`	`/v1/stream/{path}`	Delete stream

Differences from `/ds/` routes

Buckets do not need to be created beforehand. Streams are created without bucket-existence validation.
No bucket-level operations (create/get/delete bucket, list streams). Use the /ds/ routes for those.
No snapshot or bootstrap routes. Use the /ds/ equivalents.
Stream close uses the Stream-Closed: true header on POST, not a path suffix.

curl -X PUT https://stream.tonbo.dev/v1/stream/mystream

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

curl 'https://stream.tonbo.dev/v1/stream/mystream?offset=-1'

curl 'https://stream.tonbo.dev/v1/stream/mystream?offset=-1&live=sse'

Getting Started

Concepts

Architecture

API

Protocol Specification

Comparisons

Path mapping

Routes

Differences from `/ds/` routes

​Path mapping

​Routes

​Differences from /ds/ routes

Path mapping

Routes

Differences from `/ds/` routes