API Reference

LiveWing exposes a WebSocket API on port 8099 for remote control, automation, and third-party integration. The API uses a JSON protocol over WebSocket and covers switching, audio, outputs, replay, overlays, inputs, and system state.

Connection

ws://<host>:8099

Authentication must be the first message sent after connecting — any other command before auth is rejected.

Authentication

Send system.auth within 5 seconds of connecting or the server closes the connection.

// Request
{ "id": "1", "type": "system.auth", "params": { "token": "your-token" } }

// Success
{ "id": "1", "status": "ok", "data": {} }

// Failure
{ "id": "1", "status": "error", "error": { "code": "AUTH_FAILED", "message": "Invalid token" } }

The shared token is configured in LiveWing settings and stored in the macOS Keychain. After 5 failed attempts the connection is dropped.

Protocol

All messages are UTF-8 JSON objects.

Client → Server

{ "id": "<string>", "type": "domain.action", "params": {} }

Server → Client (response)

{ "id": "<string>", "status": "ok", "data": {} }
{ "id": "<string>", "status": "error", "error": { "code": "ERROR_CODE", "message": "..." } }

Server → Client (push event)

{ "event": "topic.name", "data": {} }

Use system.describe to discover all available commands and topics at runtime.

Subscriptions

Subscribe to real-time push events without polling.

{ "id": "1", "type": "system.subscribe", "params": { "topics": ["switcher.state", "audio.levels"] } }
{ "id": "2", "type": "system.unsubscribe", "params": { "topics": ["audio.levels"] } }

Rate limits

Error codes