Skip to main content

REST & WebSocket API

phix exposes a HTTP/WebSocket API that allows external applications to send commands and receive real-time state updates. This is the same API used by the built-in GUI.

Enabling the API#

The API server runs on a configurable port (default: 9000).

api enableapi port 9000

Authentication#

The API uses Bearer token authentication. Create a token:

api token create "My App"

Include the token in every request:

Authorization: Bearer <your-token>

REST endpoints#

MethodPathDescription
POST/api/v1/commandExecute a command (JSON body)
POST/api/v1/parseParse a text command
GET/api/v1/statusServer status and connected clients
GET/api/v1/wsWebSocket endpoint for real-time events
POST/api/v1/auth/validateValidate an API token

Sending a command#

POST /api/v1/command

Send a JSON-serialized Command object. Example — trigger executor 1:

POST /api/v1/commandAuthorization: Bearer <token>Content-Type: application/json
{  "command": {    "Go": { "executor_index": 1 }  }}

Parsing a text command#

POST /api/v1/parse

Parse a text command string (like the command line). phix returns the parsed JSON command:

POST /api/v1/parseAuthorization: Bearer <token>Content-Type: application/json
{  "input": "go 1"}

Real-time events via WebSocket#

Connect to GET /api/v1/ws with a WebSocket client. phix streams all engine events in JSON format:

{  "ExecutorListChanged": {    "executors": [ ... ]  }}

Events include:

  • StateChanged — general state update
  • FixtureListChanged — fixture list updated
  • PresetListChanged — preset pool updated
  • ExecutorListChanged — executor state changed
  • CueListChanged — cue list for the active sequence
  • ProgrammerChanged — programmer values changed
  • DmxFrameSent — a DMX frame was output
  • SelectionChanged — fixture selection changed

Managing API tokens#

api token create "My App"    -- create a new tokenapi token list               -- list all tokensapi token delete <id>        -- delete a token

Use cases#

  • Custom control surfaces — build a web or mobile app that controls phix
  • Show automation — trigger cues from a video system, QSC Q-SYS, or automation controller
  • Integration — connect phix to other show-control systems via HTTP
  • Monitoring — stream DMX values or executor state to a visualization tool