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.

recordquerystring

For a JSON stream with Record Coordinates, start at a complete record boundary. Supply a zero-based ordinal or now for the current record tail. Mutually exclusive with offset and tail_records.

tail_recordsquerynumber

Start at the most recent retained records: max(first_record, next_record - count). Mutually exclusive with record and offset.

max_recordsquerynumber

Maximum number of complete records to return. Requires record or tail_records and cannot be combined with max_bytes.

record_viewquerystring

Set to envelope with a record-aware start to return one {record, value} object per NDJSON line.

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.

Record-aware responses also advertise json-record-coordinates-v1 in Stream-Extensions and include Stream-Record-First, Stream-Record-Start, and Stream-Record-Next. Continue with record=<Stream-Record-Next>. A record below Stream-Record-First returns 410, and a record beyond the current tail returns 400.

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, while 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'

curl -i 'http://127.0.0.1:4437/demo/hello?record=42&max_records=100'

curl 'http://127.0.0.1:4437/demo/hello?tail_records=100&record_view=envelope'

curl -N 'http://127.0.0.1:4437/demo/hello?record=now&record_view=envelope&live=sse'

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