Realtime Event Streams (SSE)

The External API provides realtime event streams over
Server-Sent Events (SSE).
An SSE stream is a long-lived HTTP GET request: the server keeps the
connection open and pushes events as they occur.

Available streams

Stream	Endpoint	Event type
Notifications	`GET /api/v1/organizations/{name}/notifications:stream`	`notification.created`
Chat events	`GET /api/v1/organizations/{name}/chatEvents:stream`	`chat.updated`

Both streams are scoped to your organisation: you only receive events for
the organisation your credential belongs to, and {name} must match it.

Authentication

SSE endpoints accept the same authentication as regular API calls — Ed25519 API key headers. Sign the request exactly as described in Signing a Request:
the canonical payload is built from the GET method, the path, the raw
query string (empty if none), and the timestamp.

GET|/api/v1/organizations/acme/notifications:stream||1716643200000

The signature is verified once, when the connection is established. The
stream then stays open without re-authentication. Each reconnect is a new
request and needs a fresh timestamp and signature.

Stream protocol

On connect, the server responds with Content-Type: text/event-stream and
immediately sends a readiness event:

event: ready
data: {"status":"connected"}

After that, events are delivered as they occur. Every 20 seconds the server
sends a comment line (: keepalive) to keep the connection alive through
proxies and load balancers — SSE clients ignore comment lines automatically.

`notification.created`

Emitted when a new notification is created for your organisation:

event: notification.created
data: {"organization_id":"9a3f7e9a-...","notification":{...}}

The notification object has the same shape as items returned by the
notification list endpoint.

`chat.updated`

Emitted when a chat thread in your organisation receives an update:

event: chat.updated
data: {...}

Example

(curl -N disables output buffering; sign stands for your Ed25519
signing step from Signing a Request.)

Reconnection guidance

Expect disconnects. Network hiccups, deploys, and idle proxies will
occasionally drop the connection. Treat reconnection as the normal case:
reconnect with exponential backoff and jitter, re-signing the request
each time.

Streams are not replayed. Events emitted while you were disconnected
are not redelivered on reconnect. After reconnecting, fetch the current
state from the corresponding REST endpoint (e.g. the notification list)
to catch up, then continue consuming the stream.

One credential, one nonce sequence. The connection request consumes a
timestamp nonce like any other request. If the same credential is used
for both a stream and regular API calls from different processes, see the
nonce coordination note in Signing a Request — Replay protection.

Realtime Event Streams (SSE)

Available streams#

Authentication#

Stream protocol#

notification.created#

chat.updated#

Example#