HelmOS REST and WebSocket API

NORTHSTAR SHOW SYSTEMS

HelmOS REST and WebSocket API

HTTP and WebSocket interface for the Helm orchestration server

v1.0 — May 2026

HelmOS REST and WebSocket API

HelmOS serves its API on port 3000 at 10.0.0.1. All REST endpoints are under /api. Cuemaster (the runtime dashboard) is served from the same origin. No authentication is required — network isolation on TrueNorth is the security model.

REST endpoints

Method	Path	Description
POST	/api/config	Upload a new nodes.json. Replaces the file on disk after Zod validation. Append ?dryRun=1 to validate without writing.
GET	/api/state	Full state snapshot: show state, config, node statuses, running sequences, last 50 activity entries.
GET	/api/nodes/:id/status	Live /status poll of a single Polaris node (proxied through HelmOS).
POST	/api/trigger/channel	Fire a single channel. Body: {nodeId, ch}. Returns 423 if maintenance mode is active.
POST	/api/trigger/group	Fire all channels in a group. Body: {groupId}. Returns 423 during maintenance.
POST	/api/trigger/sequence	Start a sequence. Body: {sequenceId}. Returns 423 during maintenance.
POST	/api/sequence/:runId/abort	Abort a running sequence by its runtime run ID.
POST	/api/show/start	Transition show state to RUNNING. Fires the boot sequence if one exists. Blocked during maintenance.
POST	/api/show/stop	Transition show state to STOPPED. Cancels all running sequences.
POST	/api/show/reset	Transition to RESETTING (5-second window), then STOPPED. Cancels all running sequences.
POST	/api/maintenance	Toggle maintenance mode. Body: {on: boolean}. No dashboard toggle exists — this is for Bridge and admin chord only.
POST	/api/schedule/:id/toggle	Enable/disable a schedule. Body: {enabled: boolean}. Writes to runtime-overrides.json.
GET	/api/activity	Paginated activity log. Query params: limit (default 50), offset (default 0).
GET	/api/healthz	Liveness check. Returns {"ok":true}.

HTTP status codes

Code	Meaning
200	Success
400	Validation error (bad body, invalid ID, malformed config)
404	Node, group, sequence, or schedule not found
423	Maintenance mode is active — triggers and show start are locked
500	Internal server error

POST /api/config detail

This endpoint is used by Compose to upload show files. The full nodes.json body is sent as application/json. HelmOS validates the payload with Zod before writing:

All cross-references resolve (group channels point to real nodes, sequence steps point to real targets, schedule targets resolve).
No duplicate node IDs.
Interval schedules require intervalMinutes >= 1.
On success, the file is atomically replaced on disk and the in-memory config is reloaded.
With ?dryRun=1, validation runs but no file is written. Returns {"valid":true} or the validation errors.

WebSocket

A single WebSocket endpoint at /ws. Broadcast model — no subscription topics. Cuemaster auto-reconnects every 2 seconds on disconnect.

Message types

Type	Payload	When
state	Full state snapshot (same as GET /api/state)	On any show state change
activity	Single activity log entry	On every operator-relevant event
node	Node status update (id, online, rssi, uptime)	After each 5-second poll cycle
schedule	Schedule status change	On schedule fire, enable/disable
sequence:start	Sequence run started (runId, sequenceId, name)	When a sequence begins
sequence:end	Sequence run ended (runId, reason: complete\|aborted\|error)	When a sequence finishes
bridge	Bridge event (command name)	On any Bridge serial command

All messages are JSON with a type field at the top level. Clients should ignore unknown type values for forward compatibility.

Mock mode

When HelmOS runs with --mock or HELMOS_MOCK=1, Polaris HTTP calls are stubbed (30–80 ms jitter, 5% random failure), no serial port is opened, and POST /__mock/bridge/:command synthesizes Bridge button events for UI testing.