Real-Time Streaming

Use the real-time notification stream to receive push updates over a single bidirectional WebSocket connection. Clients subscribe to one or more displays and immediately receive notification and heartbeat frames as JSON messages on the open socket. This endpoint is the recommended transport whenever you need live notification delivery without polling the REST API.

For background on the notification model, see the Notifications overview.

Connect to the Notification Stream

`GET /api/v1/notifications/stream`

Establishes a WebSocket connection for real-time notification updates. The server returns 101 Switching Protocols and upgrades the HTTP request; once the handshake completes the server pushes JSON notification messages and heartbeat frames to the client until the socket is closed.

The required displays query parameter selects which displays to subscribe to. Pass comma-separated display IDs (for example, 1,2,3) or the literal all to receive notifications from every display. Display IDs start at 1.

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

The server upgrades the HTTP request to a WebSocket. No JSON body is returned; the response is the protocol-switch handshake:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

After the upgrade, the server emits JSON notification frames and heartbeat frames on the open socket until the client disconnects.

{
  "error": "Bad Request",
  "message": "The displays query parameter is required"
}

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-n-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

// Subscribe to specific displays
await client.notifications.notifications.connectStream('1,2,3');

// Or subscribe to every display
await client.notifications.notifications.connectStream('all');

curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  "wss://{projectId}-{containerId}-n-1.{server}.containers.hoody.com/api/v1/notifications/stream?displays=all"