Skip to content
BoilStream

SSE events and errors

referencepreview
TL;DR

Look up the stream endpoint, event types and error behavior for the SSE preview protocol. Schema and batch events carry opaque cursor strings; heartbeats do not acknowledge data. An HTTP 200 begins the stream, but later errors may require a snapshot refresh or close the connection without changing that status.

Message sequenceSchema establishes the baseline; batches carry resumable cursors
Schema establishes the baseline; batches carry resumable cursorsA browser opens the token-scoped SSE endpoint. BoilStream sends a schema baseline and complete Arrow IPC batch events. The consumer retains the opaque cursor after processing a complete batch. Heartbeats carry no data acknowledgement.SSE consumerBoilStreamGET /stream/{token}HTTP 200: stream openedschema: baseline and Arrow schemabatch: Arrow IPC and opaque IDProcess complete batch; retain IDheartbeat: connection activityTime moves downward · dashed arrows are responsesSchema establishes the baseline; batches carry resumable cursorsA browser opens the token-scoped SSE endpoint. BoilStream sends a schema baseline and complete Arrow IPC batch events. The consumer retains the opaque cursor after processing a complete batch. Heartbeats carry no data acknowledgement.SSE consumerBoilStreamGET /stream/{token}HTTP 200: stream openedschema: baseline andArrow schemabatch: Arrow IPC andopaque IDProcess complete batch;retain IDheartbeat: connectionactivityTime moves downward · dashed arrows are responses
Opening the stream is not a durable subscription. A new subscription starts from its captured baseline, not the entire table history.
Jump to reference ↓

Endpoint

Section titled “Endpoint”
HTTP
GET https://localhost:8443/stream/{token}

Use a stream token issued by the CLI or API without modifying it.

Protocol details

Section titled “Protocol details”
Property Value
Protocol HTTP/2 with TLS
Port 8443 (default, configurable via http_ingestion.port)
Content-Type text/event-stream
CORS Browser origins must be allowed by the deployment
Heartbeat Every 15 seconds when output capacity is available; skipped under backpressure

Event types

Section titled “Event types”

schema

Section titled “schema”

Establishes the subscription baseline before data, including on an idle newly established subscription, and is sent again when the live schema changes. A new subscription starts after rows already visible at that baseline; it does not backfill the entire table. The live queue is registered before capture. The Arrow schema is a base64-encoded Arrow IPC stream. Its cursor repeats the current baseline or last complete batch coverage; a schema change does not acknowledge the following data batch.

Output
event: schema
id: r1.<opaque-cursor>
data: <base64-encoded Arrow IPC stream>

batch

Section titled “batch”

Contains one complete logical batch, potentially several Arrow record batches, in one base64-encoded Arrow IPC stream. The event ID is an opaque versioned cursor. Keep it unchanged as a string: it is not a batch number and cannot be compared numerically or lexicographically.

Output
event: batch
id: r1.<opaque-cursor>
data: <base64-encoded Arrow IPC stream>

heartbeat

Section titled “heartbeat”

Keeps an idle connection alive. It contains no cursor or data acknowledgement.

Output
event: heartbeat
data:

refresh-required

Section titled “refresh-required”

Terminal control event. Close the client and refresh the application from an authorized canonical table query before establishing a new subscription according to the application’s snapshot strategy. Do not automatically retry the same exhausted cursor. The event has no ID, so it cannot advance the last complete cursor.

Output
event: refresh-required
data: {"reason":"refresh_required"}

Network loss may prevent this final event from reaching the client. Token expiry, revocation and owner changes can also close a connection.

Error codes

Section titled “Error codes”
Status Description
200 Success — SSE stream begins
400 Malformed token or invalid reconnect-header framing
401 Invalid, expired or revoked token, or token validation unavailable
403 Wrong token purpose or disallowed browser origin
429 Request-rate or consumer limit reached
503 Admission capacity unavailable; retry as directed by the response

These statuses apply before the stream starts. Cursor decoding and original-table identity validation occur during snapshot opening: an invalid, old numeric or foreign cursor produces refresh-required after HTTP 200. Later replay or capacity failures also use that terminal event where possible; transport or authorization loss may close the connection. No later failure changes the HTTP status.