Skip to main content

WebSocket

Connect to /api over WebSocket to open a live event stream. Notifications begin arriving as soon as the socket connects. No subscription or setup command is required.

REST WebSocket endpoint​

wss://<server>/api
Two WebSocket endpoints

The TCI WebSocket on ports 7000 and 7010 is a full API session. It carries the same commands and responses as a telnet session. Before sending commands, the client must work through the connection state, including require api and mode async on. See Connecting to the API.

The REST WebSocket upgrades /api on ports 80 and 443. It supports SDVoE REST API events and adds DisplayNet notifications on the same connection. Events flow immediately; no handshake is required.

Authentication​

When the server requires authentication, the WebSocket connection needs the same bearer token used for HTTP requests. The token authorizes both DisplayNet notifications and SDVoE API commands. Browser WebSocket clients cannot set headers, so they can use a query parameter:

wss://<server>/api?token=<login token>

Clients that can set headers should send Authorization: Bearer instead. See Authentication.

The server uses the identity from the connection to decide which notifications to send. Notifications scoped to a user go only to that user's connections.

Incoming events​

The socket carries both SDVoE API events and DisplayNet notifications:

Endpoint typeContents
SDVoE API eventsDevice connections, stream state, and everything else the Control Server emits.
DisplayNet notificationspreset_update, device_update, and the other DisplayNet notifications. See Requests and Events.

Sending on the socket​

This socket is an event stream and an SDVoE API command channel. It delivers events from both endpoint types. It accepts only SDVoE API commands from the client. The server relays client text to the Control Server in the format expected by SDVoE clients. DisplayNet API commands are not available on this socket.

DisplayNet API operations are not available here. Call those over HTTP; see Sending commands.

Commands sent here follow the same rules as SDVoE API operations over HTTP. Device names are resolved to device IDs. Mutating verbs against a locked device are refused rather than forwarded. The refusal is sent back on the same socket:

Locked device response​

{
  "status": "ERROR",
  "request_id": null,
  "result": null,
  "error": {
    "message": "Cannot reboot on locked device Top Left TV",
    "reason": "DEVICE_LOCKED"
  }
}

Socket versus polling​

GET /api/event polls the same SDVoE API events. On the socket, events arrive as they happen and DisplayNet notifications use the same connection. There is no polling interval to set. Polling keeps no connection open, which suits a script that runs briefly and exits.

See also​