Skip to main content
GET
/
ds
/
{bucket}
/
{stream}
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1'
​
bucket
string
required
Bucket ID.
​
stream
string
required
Stream ID within the bucket.
​
offset
string
Starting offset. Use -1 to read from the beginning, or a numeric offset.
​
cursor
string
Opaque cursor token returned by a previous read. Alternative to offset.
​
stream-cursor
string
Alias for cursor.
​
live
string
Live mode: sse for Server-Sent Events, long-poll for long-polling. Omit for catch-up read.
​
max-bytes
number
Maximum bytes to return in a single response (catch-up and long-poll only).

​
Read modes

No live parameter. Returns all available data from the given offset immediately.
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1'

​
Response

StatusMeaning
200Data returned (catch-up or long-poll with data).
204No new data at the requested offset (catch-up only).
400Invalid offset or live mode.
404Stream not found or expired.
410Requested 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.

​
SSE event format

In SSE mode, the server sends:
  • Data events (event: data): stream payload in the data field. 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 'https://stream.tonbo.dev/ds/demo/hello?offset=-1'
See read modes, binary SSE, and offsets for more details.