Real-Time Notification Streaming

Stream notification updates in real-time over a bidirectional WebSocket connection. Once the handshake completes, the server pushes JSON notification messages and periodic heartbeat frames to subscribed clients without polling. Use this endpoint when you need live notification state in dashboards, monitoring tools, or any UI that should reflect changes as they happen.

The transport is a single WebSocket connection — not Server-Sent Events. Clients maintain the socket and parse WebSocket frames directly. For the broader notification model (listing, marking as read, preferences), see the Notifications overview.

Note

After the handshake, the server sends JSON notification payloads and periodic heartbeat frames on the same WebSocket connection. Treat heartbeat frames as keep-alive signals and respond accordingly to keep the socket open.

GET /api/v1/notifications/stream

Establishes a WebSocket connection for real-time notification updates. Clients subscribe to one or more displays and receive immediate notifications over the open socket.

The HTTP request performs a standard WebSocket upgrade handshake. On success, the server replies with 101 Switching Protocols and the underlying TCP connection transitions to WebSocket framing. All subsequent traffic on that socket is WebSocket-framed JSON: notification messages when state changes, and heartbeat messages at regular intervals. The connection stays open until the client disconnects or the server enforces a per-container connection limit.

Parameters

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

Response

101

The WebSocket handshake succeeded. The connection is now open and the client can read WebSocket frames (notification messages and heartbeats) from the socket.

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

400

The request was malformed. Common causes include a missing or invalid displays query parameter, or an empty display ID list.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Missing required query parameter: displays"
}

429

The connection limit for this container has been exceeded. The server returns this JSON error in the handshake response and does not upgrade the connection.

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

Usage

cURL

The request performs a standard WebSocket upgrade. The -i flag prints the response headers (the 101 Switching Protocols reply), and -N disables output buffering so frames are delivered as they arrive.

curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  -H "Sec-WebSocket-Version: 13" \
  "https://proj-abc123-cont-xyz789-n-1.us-east.containers.hoody.icu/api/v1/notifications/stream?displays=1,2,3"

SDK

// Subscribe to displays 1, 2, and 3
await client.notifications.connectStream({ displays: "1,2,3" })

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

The required displays value is passed in the trailing options object as a query parameter.