HelmOS HTTP API Reference

NORTHSTARSHOW SYSTEMS

HelmOS HTTP API Reference

Every HTTP endpoint exposed by HelmOS

Document Number	Revision	Date	Platform Version
NSSS-DOC-0091	A	2026-05-20	1.0

Base

Listening port: 3000 by default (HELMOS_HTTP_PORT). JSON bodies: Content-Type application/json. Binary uploads: Content-Type application/octet-stream. CORS is wide open (LAN-trusted).

Endpoint Index

Method	Path	Purpose
GET	/api/health	Server status + brand + product + version + uptime + maintenance + licensed
GET	/api/project	Active project metadata
GET	/api/nodes	Every registered Polaris node
GET	/api/cues	All cues in the active project
POST	/api/cues/:id/go	Manually fire a cue (license + maintenance gates apply)
POST	/api/stop-all	Abort every running cue + UDP STOP to all nodes
POST	/api/nodes/register	Polaris boards POST here on boot
POST	/api/deploy	Upload a .nsss.compose archive (binary body)
POST	/api/cuemaster/event	Cuemaster terminal sends an event
POST	/api/test-output	Maintenance-only: fire a single pulse
GET	/api/license/status	License activation state + device fingerprint
POST	/api/license/activate	Activate with a token
POST	/api/license/deactivate	Remove the stored license
GET	/api/maintenance	Current maintenance state
POST	/api/maintenance/enter	Force maintenance on
POST	/api/maintenance/exit	Force maintenance off
GET	/api/firmware	Bundled firmware list + per-variant target node ids + toolchain info
POST	/api/nodes/:id/update-firmware	OTA-push to one node
POST	/api/firmware/update-all	Rolling fleet OTA update

Sample /api/health Response

{
  "ok": true,
  "product": "HelmOS",
  "brand": "Northstar Show Systems",
  "tagline": "Distributed show control · Always points home",
  "version": "1.0.0",
  "uptime": 12345.67,
  "project": "Project Name",
  "nodes": 12,
  "cues": 24,
  "runningCues": 0,
  "maintenance": false,
  "licensed": true
}

Authentication

No HTTP authentication today. The TrueNorth network WPA password is the security boundary. Tokens for license activation are validated server-side.

Rate Limits

None applied. Deploy bodies are capped at 200 MB. OTA push operations are serialised per node.

NSSS-DOC-0072WebSocket Protocol Reference
NSSS-DOC-0073UDP Cue Command Reference

Revision History

Revision	Date	Description
A	2026-05-20	Initial publication