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.

Daemon identity plus authorized runtime status. identity is always present so discovery probes can verify the daemon. status is present for loopback clients and requests with a valid read or control key. Anonymous remote requests to a keyed daemon receive the public identity without the status block.

Response:

{
  "data": {
    "identity": {
      "instance_id": "studio-daemon",
      "instance_name": "Studio",
      "version": "0.3.2",
      "device_count": 3,
      "auth_required": true
    },
    "status": {
      "running": true,
      "version": "0.3.2",
      "device_count": 3,
      "effect_count": 59,
      "active_effect": "borealis",
      "global_brightness": 85,
      "audio_available": true,
      "screen_capture_capacity": {
        "admission_enforced": true,
        "physical_transition_byte_capacity": 268435456,
        "physical_transition_backend_capacity": 4,
        "physical_reserved_bytes": 33177600,
        "physical_available_bytes": 235257856,
        "steady_total_byte_budget": 134217728,
        "steady_total_backend_capacity": 2,
        "steady_publication_byte_budget": 134217728,
        "transition_publication_backend_capacity": 2
      },
      "input": {
        "enabled": true,
        "host_capture_registered": true,
        "host_capturing": true,
        "devices_opened": 3,
        "devices_denied": 1,
        "degraded": "access_denied",
        "backends": ["evdev"],
        "source_graph_generation": 2,
        "sources": []
      },
      "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"
  }
}

status.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.

status.screen_capture_capacity reports the byte fences that gate screen-capture publication admission. The fences are installed on Linux and Windows, where admission_enforced is true and the capacity fields are populated; on other platforms the object collapses to { "admission_enforced": false } with every fence field omitted. When an analysis plan is active, additional analysis_* fields describe its resolution, byte budgets, and compute capacity.

status.input is the host keyboard/mouse capture health snapshot. enabled is the consent gate from config, host_capturing reports whether a host backend is actively reading input, and devices_opened versus devices_denied separates “input is off” from “input is on but blocked”. The denied counter counts device nodes that are present but unreadable, a Linux-specific failure (udev rules missing); Windows has no per-node denial, so its session-level failure arrives through degraded instead, as one of no_interactive_session, access_denied, or unavailable. Each entry in sources carries per-source lifecycle, freshness, and issue detail.

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

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.

Request macOS Automation access for an already-running media application. The endpoint requires a control credential and accepts either Apple Music or Spotify:

{
  "adapter": "music"
}

The response reports the selected adapter and whether access was authorized. The daemon returns 422 when the application is not running and 409 when Automation access is unavailable or denied.

List the effect catalog. Returns data.items (effect summaries) and data.total.

Filter with category, source, audio_reactive, screen_reactive, input_reactive, and q (a case-insensitive substring match over name, description, author, and tags). Expand each summary with include=controls,presets. The catalog route answers complete, so it carries no data.page block.

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
      }
    ],
    "total": 59
  },
  "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 data.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.

Replace the target zone’s layer stack with one new layer running this effect. The server validates the effect, zone, and controls before committing, mints a fresh layer id, then wakes paused output.

Request body (optional):

{
  "zone": "84b20af9-0700-4b82-8488-88314b87fb5c",
  "controls": {
    "speed": { "kind": "float", "value": 7.0 },
    "palette": { "kind": "enum", "value": "SilkCircuit" }
  },
  "transition": { "type": "cut" }
}

Omit zone to target the primary zone, which the daemon creates if needed. The response contains the updated zone resource, including the new layer id, the applied transition, and the output-wake outcome. A post-commit wake failure is reported inside a 200 response. Repair output through PATCH /output instead of retrying apply, because every apply creates another layer id.

List bundled and saved presets available for one effect.

Apply one effect-scoped preset through the same stack-replacement contract as POST /effects/{id}/apply. Preset CRUD remains under /library/presets, but the library does not expose a second apply route.

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.

List discovered and connected devices. Returns data.items, data.total, and a data.page block, because this route genuinely pages: limit defaults to 50 and anything above 200 is rejected. Follow page.has_more, advancing offset by the number of items you received, until it reads false. Add ?include=attachments to embed each device’s attachment profile in the same response.

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,
        "segments": []
      }
    ],
    "total": 1,
    "page": {
      "offset": 0,
      "limit": 50,
      "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: segments, LED layout, firmware version, attachment configuration.

Update device settings such as name and brightness.

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 segment 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. Send "validate_only": true to return the computed profile without persisting it, publishing events, or changing the live device.

Clear a device’s attachment configuration.

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.

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. The body is the same control-patch shape the layer-control route takes, keyed by field id. Control surfaces have no input bindings, so a non-empty clear_bindings is rejected here.

Request body:

{
  "values": {
    "protocol": { "kind": "enum", "value": "ddp" },
    "ip": { "kind": "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"
}

Capture the complete live scene as a new snapshot-mode scene. The snapshot keeps the active scene’s zones, members, layers, controls, display faces, and current named layout reference. Global output brightness is not captured.

Request body:

{
  "name": "Current Rig",
  "description": "Captured after tuning the desk"
}

Read the complete live scene document. The response always exists and embeds every authored zone, each zone’s member device segments, and every layer with its real id. The document’s revision is also returned as ETag.

Read one stored scene as a complete document, including its zones, members, layouts, and layer stacks. The response carries the document’s revision and the same value as an ETag header.

Replace one stored scene in full. Read the current document first, remove the server-owned revision and is_default fields, apply the intended edits, and send the result with the previous revision in If-Match.

The route id is authoritative. If the body includes id, it must match the route or the daemon returns 422 Unprocessable Entity. Existing zone and layer ids must already belong to this scene. Omit either id only when creating that resource, and the daemon mints it. Omitted optional fields are cleared, so partial update bodies are not accepted. A stale If-Match returns 412 Precondition Failed with the current revision.

Delete a scene.

Activate a scene, applying its effects and controls with the configured transition. The response reports the post-commit layout and brightness outcomes separately, because either side effect may fail after the scene switch has committed. Send {} to use the scene’s authored transition, or pass { "transition_ms": 250 } to override its duration for this activation.

Patch the live scene’s name or unassigned_behavior. The default scene cannot be renamed. This structural write optionally accepts If-Match.

Return to the default scene and receive the new live scene document.

Clear every non-display layer stack, or pass { "zone": "<zone_uuid>" } to clear one non-display zone. Display zones remain owned by the display API, and a targeted display clear is rejected. This is the canonical stop gesture and optionally accepts If-Match.

Create a custom zone. Send If-Match with the last seen scene revision when you need optimistic concurrency; a stale revision returns 412 Precondition Failed.

Request body:

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

Get one live zone resource.

Update a zone’s name, enabled state, brightness, or color. The structural write optionally accepts If-Match.

Request body:

{
  "name": "Desk halo",
  "brightness": 0.8,
  "enabled": true
}

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

Assign one device’s segments to a zone. The response carries the minted member ids, which are the resource identities for later removal.

Request body:

{
  "device_id": "razer:huntsman-v3",
  "segments": ["left", "right"]
}

Remove one membership by the member id returned in the live zone document.

Replace the zone-scoped spatial placement override. The compact body contains placements, keyed by member id. Add or remove members through the member routes. This structural write optionally accepts If-Match.

List the layers in a zone.

Append a layer to a zone. The server mints its id. This structural write optionally accepts If-Match.

Reorder the stack with every layer id exactly once, from bottom to top.

Replace a whole layer. Every successful replacement mints a fresh layer id, even when the effect is unchanged.

Delete a layer.

Patch an effect layer with { "values": {...}, "clear_bindings": [...] }. Control patches never use If-Match. A vanished layer returns 404 layer_not_found.

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 outputs, 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.

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.

Deactivate the running playlist.

Read global output power and brightness.

Response:

{
  "power": "running",
  "brightness": 0.8
}

power is running or paused. A destructive stop leaves outputs dark, so it reads as paused here; the stop’s other consequences are visible on the effect surface. brightness is a float on 0.0 to 1.0.

Set power, brightness, or both. Every field is optional, but a document that sets neither returns 422 rather than quietly succeeding, so a client that drops its payload hears about it. Use GET to read.

Request body:

{
  "power": "paused",
  "brightness": 0.35
}

A brightness outside 0.0 to 1.0 returns 422 naming the offending field, and it is refused before power moves, so a rejected patch changes nothing.

Request Input Monitoring authorization from the process that owns host keyboard capture. The response reports whether access is currently authorized and names the process topology that owns the grant.

Request Screen Recording authorization from the process that owns screen capture. The response reports whether access is currently authorized and names the process topology that owns the grant.

Open the platform picker so the user can choose a display, window, or application for screen-reactive effects. An accepted display persists by its stable display UUID. Window and application choices persist as session_scoped, so Hypercolor remembers the privacy boundary without writing the selected window ID or bundle ID to configuration. Cancelling the picker leaves the current source unchanged.

New in 0.3.0. List the display outputs the capture backend can address, for building a monitor picker. Each entry carries a ready-to-store value for the capture.source config key.

Response:

[
  {
    "index": 0,
    "id": "DP-1",
    "name": "\\\\.\\DISPLAY1",
    "width": 2560,
    "height": 1440,
    "primary": true,
    "value": "monitor:DP-1"
  }
]

The list is empty on platforms where the backend picks its own source (the XDG portal on Linux); a UI uses that emptiness to decide between a monitor dropdown and the portal picker button.

Show the full current configuration.

Secret-classified sections render masked as {"redacted": true}: every drivers entry, plus any top-level section this build does not model. Driver settings are read and edited through /api/v1/drivers/{id}/config.

Read one configuration value. The dotted key is a single path segment.

Write one configuration value and persist it. The request body is the value itself:

true

Add ?live=false to persist without re-applying the change to the running daemon; the default re-applies every live-classified key.

The response carries the effective value, whether the daemon applied it live, whether the key is boot-frozen (requires_restart), and which sections are currently waiting on a restart (pending_restart).

Restore one configuration value to its default. Takes the same ?live= query parameter as the write.

Restore the whole configuration to defaults. The drivers map, unmodeled extension sections, and the include list survive the reset.

Describe every configuration key: how a change applies (live with a section, live_on_read, next_scan, restart, or inert), how it renders on read surfaces, whether the daemon validates it beyond type checking, and which writes need a protected-control credential (protection: open, section_root, or tree). Clients derive their live and restart affordances from this table.

Run system diagnostics: device connectivity, audio capture, effect-engine health, memory, and configuration validity. Memory failures are reported as the named memory check in the same response. The diagnose CLI command and MCP tool use this exact check vocabulary.

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.