Reference

The OmnaDMX Device REST API is the controller’s own API, served by the firmware. This page covers the conventions you need before you start calling it.

Base URL & reachability

The base URL is the controller, at http://omna.local (mDNS) or its IP. The device is on the network on demand, so automate against one you’re keeping awake — web UI open, or network DMX active. (Zone sync holds the network up only while one is available to it; a zone with no network keeps syncing over a direct device-to-device radio link, which has no IP reachability.) A fully idle device may be off the network by design.

With more than one device on the network, omna.local resolves to whichever one currently owns that name (an election that can change as devices come and go), and its root path serves a device-picker lobby rather than the app. For deterministic automation against a specific unit, target its stable per-device name, omna-<id>.local (a short MAC-derived id, shown on the OLED and in the web UI), or its IP. /api/fleet lists every device with its hostname.

Response envelopes

Everything is JSON. A success carries "success": true; a failure carries "success": false and a human-readable "message". Branch on success, not on HTTP status alone. An unknown route is 404; a known route with the wrong method is 405.

Retry on 503

A handler returns 503 with Retry-After: 2 when free memory is briefly under a per-route threshold — page-serving routes reserve more than light API calls. This is transient back-pressure, not a failure. Honour Retry-After and retry; don’t treat it as fatal.

Disabled capabilities return 404

Some endpoints sit behind optional capabilities — zone sync, fleet ops, factory restore, sensor reactions, auth — that are compiled in or out per build. A capability that isn’t in the running firmware returns 404, never 501. So probe with a request and read 404 on these as “not available on this device”, not “wrong URL”.

Authentication

If the firmware was built with API auth on, every /api/* request needs a valid X-Auth-Token. The token is an HMAC the device issues. Fetch it from GET /api/context/live, send it on later calls, and re-fetch if a call comes back 401 (missing or invalid token). Builds without auth take calls unauthenticated.

CORS

A subset of routes — config, pattern, status, fleet, identify, zone, and the fleet peer-settings patch — are CORS-enabled for cross-origin use from app.omnadmx.ca, with preflight (OPTIONS) on the cross-origin fleet, identify, pattern, and status routes. The rest are same-origin: call them from the device’s own page or server-side.

Live preview is a separate channel

A WebSocket on port 81 carries live pattern-preview data for the web app. It isn’t part of this REST API, so don’t go looking for preview or streaming endpoints here.