Real-Time Streaming

Establish a persistent WebSocket connection to receive notification updates as they are produced. The transport is a single bidirectional WebSocket — clients receive JSON-formatted notification messages and heartbeat frames over the open socket. Use this endpoint when a display needs live updates without polling the notifications REST API.

Note

This endpoint upgrades the HTTP connection to a WebSocket (101 Switching Protocols). It is not Server-Sent Events: there are no event: / data: line frames, no text/event-stream content type, and no Last-Event-ID resumption header. All frames — notifications and heartbeats — are JSON messages carried over the WebSocket connection.

For the broader notification model, see the Notification Server overview.

Connect to the notification stream

GET /api/v1/notifications/stream

Opens a WebSocket connection for real-time notification updates. Subscribe to one or more displays via the required displays query parameter, or pass "all" to receive notifications from every display. Once the handshake completes, the server pushes notification messages — and periodic heartbeat frames — directly over the open socket.

Parameters

Name	In	Type	Required	Description
displays	query	string	Yes	Comma-separated display IDs to subscribe to (e.g., 0,:1,2), or "all" to receive notifications from every display.

This endpoint accepts no request body.

Responses

101

{
  "description": "Switching Protocols - WebSocket connection established"
}

The WebSocket handshake completed successfully. Subsequent frames received on the open socket are JSON notification messages and heartbeats.

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid query parameter: 'displays' is required"
}

429

{
  "error": "Connection limit exceeded",
  "type": "error"
}

The server refused to open a new WebSocket because the per-client connection limit has been reached. Close any existing streams before reconnecting.

SDK usage

// Subscribe to specific displays
const stream = client.notifications.connectStream({ displays: "0,:1,2" });

stream.on("message", (frame) => {
  // frame is a JSON notification or heartbeat message
  console.log(frame);
});

// Subscribe to every display
const all = client.notifications.connectStream({ displays: "all" });