Web API Reference

STATUS: Stub. This page is a structural placeholder — the consolidated documentation set does not include the racelink/web/ source code, so the canonical request and response shapes cannot be derived from this snapshot alone. The route names below are compiled from references in the migrated docs (see "Source material" at the end). Filling in the request / response shapes requires a pass over racelink/web/api.py in the source repository.

The host exposes a REST API that the WebUI and the RotorHazard plugin call. Everything is mounted under the WebUI's prefix:

http://<host>:5077/racelink/api/...     (standalone)
http://<host>:5000/racelink/api/...     (RotorHazard plugin, default port)

For the SSE channel and state-scope tokens that complement these endpoints, see SSE_CHANNELS.md.

Conventions

• All POST/PUT bodies are JSON. Reading order: validate input, then call into a service, then return.
• Validation errors raise RequestParseError (a ValueError subclass) inside the route handler, which is caught and translated to HTTP 400 with a body of {"error": "<message>"}.
• Other exceptions are caught at the top of each handler, logged with type + traceback, and translated to HTTP 500.
• Long-running operations are kicked off via the task manager; routes return {"ok": true, "task": <snapshot>} immediately. Progress is delivered over SSE — see SSE_CHANNELS.md.

Endpoints

Discovery

Method	Path	Purpose
POST	/api/discover	Run device discovery. Body: {group_id, ...} (the assignment group for newly-found devices). Returns the task snapshot.

Device list & status

Method	Path	Purpose
GET	/api/devices	Return current device list with type, capability, group assignment, last-seen state.
POST	/api/status	Run a fleet status poll. Returns the task snapshot.

Groups

Method	Path	Purpose
GET	/api/groups	Return current groups list.
POST	/api/groups	Create a group. Body: {label}.
PUT	/api/groups/<id>	Rename a group. Body: {label}.
DELETE	/api/groups/<id>	Delete a group. Devices fall back to group 0.
POST	/api/groups/move	Bulk-move devices into a group. Body: {macs: [...], group_id}.
POST	/api/groups/resync	Re-broadcast every device's stored groupId to the network.

Specials

Method	Path	Purpose
GET	/api/specials/<mac>	Return the per-device-type configuration knobs.
POST	/api/specials/<mac>	Update specials for one device. Body shape is per-capability.

Presets

Method	Path	Purpose
GET	/api/presets	Return list of WLED presets known to the host.
POST	/api/presets/upload	Upload a presets.json file from the operator's machine.
POST	/api/presets/download	Download a node's presets.json to the host (long-running task).
GET	/api/rl-presets	Return the RaceLink-native preset store.
POST	/api/rl-presets	Create or update an RL preset.
DELETE	/api/rl-presets/<key>	Delete an RL preset.
GET	/api/rl-presets/schema	Return the RL-preset editor schema (effects metadata, palette list, palette-color rules). The frontend's ensureRlPresetUiSchema consumes this.

Scenes

Method	Path	Purpose
GET	/api/scenes	Return all scenes.
POST	/api/scenes	Create a scene.
PUT	/api/scenes/<key>	Update a scene.
DELETE	/api/scenes/<key>	Delete a scene.
POST	/api/scenes/<key>/run	Run a scene end-to-end. Returns the task snapshot.
POST	/api/scenes/<key>/estimate	Return the estimated cost (packets, bytes, airtime) for a scene without running it.

See SCENE_FORMAT.md for the on-disk shape that GET / PUT / POST exchange.

Firmware update (OTA)

Method	Path	Purpose
POST	/api/fw/start	Start an OTA workflow. Body includes the binary path / upload, target MACs, OTA password, "Skip firmware-name validation" flag, WiFi options. Returns the task snapshot.

The OTA workflow's progress reaches the dialog via the task SSE event with name="fwupdate". The per-device progress fields (stage, index, total, addr) are documented in ../host/docs/DEVELOPER_GUIDE.md §"Adding a new task-manager-driven workflow".

Gateway control

Method	Path	Purpose
POST	/api/gateway/query-state	Send GW_CMD_STATE_REQUEST; await the matching EV_STATE_REPORT; return the resolved state. Used by the master-pill ↻ refresh button.
POST	/api/gateway/retry	Retry the gateway connection.

Configuration

Method	Path	Purpose
POST	/api/config	Send an OPC_CONFIG packet to a device. Body: {mac, option, data0..3}. The accepted options are documented in ../host/docs/PROTOCOL.md §"P_Config".

Source material

The endpoint list above is compiled from references in:

• ../host/ARCHITECTURE.md §"Service Layer" — names the services that own each route.
• ../host/docs/PROTOCOL.md §"Where things live in code" — points to racelink/web/api.py.
• ../host/docs/DEVELOPER_GUIDE.md §"Adding a new service" §"Adding a new task-manager-driven workflow" — establishes the route conventions.
• ../host/docs/OPERATOR_GUIDE.md — end-to-end workflow descriptions that name the routes implicitly.
• ../host/docs/UI_CONVENTIONS.md — frontend handlers / toast patterns map 1:1 to API calls.

TODO when source is available

For each endpoint above:

1. Confirm the exact path and HTTP method against racelink/web/api.py.
2. Document the request body shape (validated by racelink/web/request_helpers.py).
3. Document the response body shape.
4. Document the error responses (which RequestParseError messages are user-facing).
5. Cross-link to the service that owns each route and to the matching SSE refresh tokens.

A future revision should regenerate this page from the source — the service docstrings already declare public APIs and threading expectations (see ../host/ARCHITECTURE.md §"Service Layer"); the same docstrings can drive an autogen.