Read stream

bucketpathstringrequired

Bucket ID.

streampathstringrequired

Stream ID within the bucket.

offsetquerystring

Starting offset. Use -1 to read from the beginning, or a numeric offset.

cursorquerystring

Opaque cursor token returned by a previous read. Alternative to offset.

stream-cursorquerystring

Alias for cursor.

livequerystring

Live mode: sse for Server-Sent Events, long-poll for long-polling. Omit for catch-up read.

max_bytesquerynumber

Maximum bytes to read in one response or SSE data batch. For UTF-8 SSE data, Ursula may shorten the emitted batch so Stream-Next-Offset lands on a valid text boundary.

Read modes

No live parameter. Returns all available data from the given offset immediately.

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

live=long-poll. Returns immediately if data is available, otherwise holds the connection until new data arrives or a ~3 second timeout.

curl 'http://127.0.0.1:4437/demo/hello?offset=42&live=long-poll'

live=sse. Opens a persistent Server-Sent Events connection. The server pushes data events as new entries are appended. Includes periodic heartbeat comments.

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

Response

Status	Meaning
`200`	Data returned (catch-up or long-poll with data).
`204`	No new data at the requested offset (catch-up only).
`400`	Invalid offset or live mode.
`404`	Stream not found or expired.
`410`	Requested offset has been trimmed (data no longer available).

Response headers include Stream-Next-Offset, Stream-Cursor, ETag, Stream-Up-To-Date, Stream-Closed, and Content-Type.

Streams written with Content-Type: application/json are returned as newline-delimited JSON with response Content-Type: application/x-ndjson. max_bytes applies to the encoded byte stream, so a response can end mid-line. Resume from Stream-Next-Offset and buffer any incomplete trailing line before parsing. HEAD reports the configured stream content type; read responses report the wire representation.

SSE event format

In SSE mode, the server sends:

Data events (event: data): stream payload in the data field. The response Stream-Data-Content-Type header identifies the data payload type (application/x-ndjson for JSON streams, the original content type for other streams). SSE data: lines are transport lines, not guaranteed message boundaries; JSON clients should buffer until newline before parsing records. For binary streams, data is base64-encoded (controlled by the Stream-Sse-Data-Encoding header).
Control events (event: control): JSON metadata including the current offset and stream state.
Heartbeat comments: periodic : lines to keep the connection alive through proxies.

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

curl 'http://127.0.0.1:4437/demo/hello?offset=42&live=long-poll'

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

See read modes, binary SSE, and offsets for more details.