API

System Bridge exposes your system over a local API. There are three ways to interact with it: an HTTP API for simple request/response calls, a WebSocket API for live data and control, and an MCP server for agents.

The WebSocket API is the primary interface and covers most operations: live data, input, media and power control, notifications, settings, and commands. Reach for HTTP only when you want a quick one-off read of status or a module’s current data.

Base URL

By default the backend listens on port 9170, so the base URL is:

http://{host}:9170

Replace {host} with the hostname or IP address of the machine running System Bridge. The port can be changed with the SYSTEM_BRIDGE_PORT environment variable.

Authentication

Most endpoints require your API token. Get it with the CLI:

system-bridge client token

See the CLI reference for more ways to find it. How you pass the token depends on the protocol:

• HTTP: send the X-API-Token or token header. The media file endpoint takes a token query parameter instead.
• WebSocket: include token in every message you send.
• MCP: authenticated with the same token.

The GET /api and GET /api/health endpoints do not require a token.

Protocols

WebSocket Live data subscriptions and system control. Covers most operations.

HTTP Request/response endpoints for status and module data.

MCP Server Connect agents over the Model Context Protocol.

When to use which

Protocol	Best for
WebSocket	Most operations: live updates, control actions (media, power, notifications, input), settings, and commands.
HTTP	Simple one-off reads: health checks and fetching a module’s current data.
MCP	Letting agents query data and trigger actions.