REST API reference

Liveness check. Returns 200 OK when the daemon is running. No authentication, no envelope. Use this in your reconnect loop and readiness probes.

Aggregate system status: the running effect, connected device count, audio availability, global brightness, and live render-loop timing.

Response:

{
  "data": {
    "running": true,
    "version": "0.1.0",
    "device_count": 3,
    "effect_count": 59,
    "active_effect": "borealis",
    "global_brightness": 85,
    "audio_available": true,
    "render_loop": {
      "state": "running",
      "target_fps": 60,
      "capacity_fps": 60.0,
      "delivered_fps": 59.8,
      "actual_fps": 60.0
    }
  },
  "meta": {
    "api_version": "1.0",
    "request_id": "req_019b1f9a-3f4b-7c8d-a2e1-91b4c0d86a25",
    "timestamp": "2026-06-25T18:03:11.482Z"
  }
}

effect_count reflects whatever the registry holds at request time (native built-ins plus discovered HTML effects); treat it as live, not a fixed product number.

Stable server identity: instance ID, instance name, and version. This is the same identity advertised over discovery.

Latest hardware sensor snapshot: CPU temperature, GPU load, RAM usage, and raw component readings. These feed sensor-bound effect controls.

A single named sensor reading. Common labels: cpu_temp, gpu_load, ram_used.

List the effect catalog. Returns data.items (effect summaries) plus data.pagination. Supports the standard offset / limit query params.

Response:

{
  "data": {
    "items": [
      {
        "id": "borealis",
        "name": "Borealis",
        "description": "Aurora borealis with domain-warped fBm noise",
        "author": "Hypercolor",
        "category": "ambient",
        "source": "html",
        "runnable": true,
        "tags": ["ambient", "shader"],
        "version": "1.0.0",
        "audio_reactive": false
      }
    ],
    "pagination": {
      "offset": 0,
      "limit": 50,
      "total": 59,
      "has_more": false
    }
  },
  "meta": {
    "api_version": "1.0",
    "request_id": "req_019b1f9a-3f4b-7c8d-a2e1-91b4c0d86a25",
    "timestamp": "2026-06-25T18:03:11.482Z"
  }
}

The catalog combines around a dozen native Rust built-ins with the HTML/GLSL effects discovered on disk. Don’t hardcode the count; read pagination.total.

Full detail for one effect, including its control definitions (types, ranges, defaults). The controls array is what a UI renders into sliders, color pickers, and dropdowns.

Apply an effect to the active output. Optionally override control defaults.

Request body (optional):

{
  "controls": {
    "speed": 7,
    "palette": "SilkCircuit"
  }
}

Response: the applied effect, the resolved control values, any layout binding, the resolved transition (cut, 0 today), and a warnings array.

The currently active effect and its live control values.

Patch controls on the running effect. Changes take effect on the next frame. Note the path segment is current, not active.

Request body:

{
  "controls": {
    "speed": 3,
    "intensity": 90
  }
}

Bind one named control on the running effect to an input source (audio band, sensor reading, etc.) so it modulates live instead of holding a fixed value.

Reset every control on the running effect back to its default.

Patch controls on a specific effect by ID, whether or not it is the active one.

Stop the running effect. Output goes dark.

Rescan the effects directory and pick up newly built effects without restarting the daemon. Call this after shipping an effect from the SDK.

Install an effect from an uploaded file via multipart form upload, so a freshly built HTML bundle reaches the library without a manual file copy.

Cover image for one effect.

Cover image for the active effect.

Get the layout bound to an effect.

Bind an effect to a spatial layout.

Clear an effect’s layout binding.

List discovered and connected devices. Returns data.items plus data.pagination.

Response:

{
  "data": {
    "items": [
      {
        "id": "razer-blackwidow-v4-001",
        "layout_device_id": "razer-blackwidow-v4-001",
        "name": "Razer BlackWidow V4",
        "status": "connected",
        "brightness": 100,
        "total_leds": 126,
        "zones": []
      }
    ],
    "pagination": {
      "offset": 0,
      "limit": 50,
      "total": 1,
      "has_more": false
    }
  },
  "meta": {
    "api_version": "1.0",
    "request_id": "req_019b1f9a-3f4b-7c8d-a2e1-91b4c0d86a25",
    "timestamp": "2026-06-25T18:03:11.482Z"
  }
}

Full detail for one device: zones, LED layout, firmware version, attachment configuration.

Update device settings (name, brightness, zone assignments).

Remove a device from tracking.

Trigger a discovery scan across every backend. Returns newly found devices.

Initiate pairing for a device that requires authentication (Hue link button, Nanoleaf hold-to-pair token). This is the credential path for network devices; see the per-vendor hardware guides for the timed pairing windows.

Forget a device’s stored pairing credentials.

Flash a device’s LEDs so you can spot it physically.

Flash one zone on a device to identify it.

Flash one attachment slot’s LEDs to identify it.

Control surface for a device: fields, types, and current values.

Attachment configuration for a device.

Update a device’s attachment configuration.

Clear a device’s attachment configuration.

Preview attachment placement without persisting it.

List logical-device segments carved out of one physical device.

Create a logical-device segment on a physical device.

Per-device output telemetry snapshot: frame counts, errors, latency.

List every logical-device segment across all physical devices.

Get one logical-device segment.

Update a logical-device segment.

Delete a logical-device segment.

List registered driver modules with their ID, name, and connection state.

Configuration for one driver module.

Control surface for one driver module: fields, types, current values.

List connected display devices.

A JPEG preview frame from a display device. Live frame streaming runs over the display_preview WebSocket channel.

The active face configuration on a display device.

Set the face effect on a display device. Binds an HTML effect to the device in the active scene.

Remove the face assignment from a display device.

Patch control values on a display’s active face.

Patch composition parameters (blend mode, z-order, opacity) for a face render group.

List simulated displays.

Create a simulated display.

Get one simulated display.

Update a simulated display’s configuration.

Delete a simulated display.

The latest composited frame from a simulated display.

List attachment templates (built-in and user-defined).

Create a user-defined attachment template.

Get one attachment template.

Update a user-defined attachment template.

Delete a user-defined attachment template.

List attachment categories (keycap-set, case-panel, stand, etc.).

List attachment vendors that have templates available.

List every registered control surface across devices and drivers.

Get one control surface with its current field values.

Apply typed field values to a control surface.

Request body:

{
  "fields": {
    "protocol": { "type": "enum", "value": "ddp" },
    "ip_address": { "type": "ip", "value": "10.0.0.50" }
  }
}

Invoke a typed control-surface action (Discover, Sync, Reset, and so on).

List defined scenes.

Create a named scene. New scenes are born with a default Primary zone, live mutation mode, and the engine’s default scene transition.

Request body:

{
  "name": "Late Night",
  "description": "Dim amber for late sessions",
  "enabled": true,
  "mutation_mode": "live"
}

The currently active scene.

One scene’s configuration.

Update a scene.

Delete a scene.

Activate a scene, applying its effects and controls with the configured transition.

Deactivate the current scene, returning to the default free-running state.

List a scene’s zones. The response includes groups_revision and an ETag header carrying the same revision for optimistic concurrency.

Create a zone in a scene. Send If-Match with the last seen groups_revision; a stale revision returns 412 Precondition Failed.

Request body:

{
  "name": "Desk",
  "color": "#80ffea"
}

Get one scene zone.

Update zone metadata. Set make_primary to make a zone the default output zone; that structural edit should carry If-Match.

Request body:

{
  "name": "Desk halo",
  "description": "Ambient strips behind the monitor",
  "brightness": 0.8,
  "enabled": true
}

Delete a zone. The default and display zones cannot be deleted through this route.

Assign device outputs to a zone. Each item may reference an existing device-output ID or carry a full payload.

Request body:

{
  "device_zones": [
    { "id": "keyboard-left" }
  ]
}

Unassign one device output from a zone.

Update one zone’s spatial layout. The route takes a SpatialLayout payload and preserves the zone’s existing output roster, so it is for placement edits only; add or remove outputs through the device routes above. Structural edits should carry If-Match.

Request body:

{
  "id": "default-zone-layout",
  "name": "Default zone",
  "canvas_width": 640,
  "canvas_height": 480,
  "zones": [],
  "default_sampling_mode": { "type": "bilinear" },
  "default_edge_behavior": "clamp",
  "spaces": null,
  "version": 1
}

Set how outputs not claimed by any zone should render.

Request body:

{
  "unassigned_behavior": "off"
}

Values are "off", "hold", or { "fallback": "<zone_uuid>" }.

List the layers in a zone.

Add a layer to a zone.

Reorder the layers in a zone.

Update one layer (blend mode, opacity, transform, color, source binding).

Delete a layer.

Patch the control values on one layer’s source effect.

Broadcast a media layer across the scene’s zones in one call.

List saved profiles.

Create a profile from the current state.

Request body:

{
  "name": "Gaming"
}

Get one profile’s saved state.

Update a profile.

Delete a profile.

Apply a profile, restoring its effect, controls, and assignments.

List spatial layouts.

Create a spatial layout.

The active layout.

Preview a layout without applying it. Returns the zone-to-LED mapping that would result, so a UI can render it visually.

One layout’s configuration: device zones, positions, LED mappings.

Update a layout.

Delete a layout.

Apply a layout as the active spatial mapping.

List favorited effects.

Add an effect to favorites.

Request body:

{
  "effect_id": "borealis"
}

Remove an effect from favorites. The path key is the effect ID, not a favorite ID.

List saved presets (effect plus control-value combinations).

Save the current effect and controls as a named preset.

Get one preset.

Update a preset.

Delete a preset.

Apply a preset.

List playlists.

Create a playlist of effects with transition timing.

The currently running playlist, if any.

Get one playlist.

Update a playlist.

Delete a playlist.

Start a playlist. Effects cycle on the playlist’s timing.

Stop the running playlist.

The current global brightness level.

Set global brightness, 0.0 to 1.0.

Request body:

{
  "brightness": 0.8
}

List available audio capture devices for reactive effects. Pick the monitor of your output, not a microphone, if you want lights to follow what’s playing.

Open the platform picker so the user can choose a screen or window capture source for screen-reactive effects.

Show the full current configuration.

Get one configuration value by dotted key path.

Set a configuration value.

Request body:

{
  "key": "audio.enabled",
  "value": true
}

Reset a configuration value to its default.

Request body:

{
  "key": "audio.device_name"
}

Run system diagnostics: device connectivity, audio capture, effect-engine health, and configuration validity. This is the same check the diagnose CLI command and MCP tool run.

A memory diagnostics snapshot: daemon RSS (which includes the in-process Servo renderer), canvas buffer size, and allocation counters. Useful when chasing slow memory growth.

List media assets.

Upload a media asset.

Get asset metadata.

Update asset metadata.

Delete an asset.

Fetch the raw asset bytes.

Fetch the asset thumbnail.