Ursulav0.1.0

API overview

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

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

This API is Ursula's implementation of the Durable Streams Protocol, defined by the durable-streams community, with additional route families for compatibility and deployment needs.

Bucket operations

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

Stream operations

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

Bootstrap and snapshots

MethodPathDescription
GET/{bucket}/{stream}/bootstrapSnapshot + tail replay
GET/{bucket}/{stream}/snapshotRead latest snapshot
GET/{bucket}/{stream}/snapshot/{offset}Read snapshot at offset
PUT/{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 http://127.0.0.1:4437/demo
curl -X PUT http://127.0.0.1:4437/demo/hello

Append data

curl -X POST http://127.0.0.1:4437/demo/hello \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'hello world'

Read from the beginning

curl 'http://127.0.0.1:4437/demo/hello?offset=-1'

Subscribe with SSE

curl 'http://127.0.0.1:4437/demo/hello?offset=-1&live=sse'