HTTP API documentation

1 / Base URL and access

The API uses HTTP/1.1 on the local network and is available at http://luma.local or the device IP address. Never expose the device's port 80 directly to the Internet.

• Requests and responses use JSON with Content-Type: application/json.
• API responses use Cache-Control: no-store.
• Successful commands return {"ok":true}; errors use an HTTP 4xx/5xx status and, where applicable, {"ok":false,"error":"..."}.

2 / Local authentication

When api.auth_required is true, protected routes require Authorization: Bearer <token>. Only unlock assets, GET /api/auth/status and POST /api/auth/login remain public.

The local password must contain at least 8 characters; an empty string removes it. Interactive sessions live in RAM for 12 hours and are revoked after a password change or reboot. After five failed logins the device returns 429 try_later for 30 seconds. The persistent verifier uses PBKDF2-HMAC-SHA256 with a random salt and versioned cost.

Interactive session

read -s LUMA_PASSWORD
LUMA_TOKEN=$(curl -fsS -H 'Content-Type: application/json' \
  -d "{\"password\":\"$LUMA_PASSWORD\"}" \
  http://luma.local/api/auth/login | jq -er .token)

curl -fsS -H "Authorization: Bearer $LUMA_TOKEN" \
  http://luma.local/api/state

Persistent integration token

For Home Assistant, Node-RED, backends and automations, create a separate credential using an administrative session. Store the secret field in a secret store, never in a repository.

INTEGRATION=$(curl -fsS -X POST \
  -H "Authorization: Bearer $LUMA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"Home Assistant"}' \
  http://luma.local/api/tokens)

LUMA_API_TOKEN=$(printf '%s' "$INTEGRATION" | jq -er .secret)
LUMA_TOKEN_ID=$(printf '%s' "$INTEGRATION" | jq -er .id)

3 / State and data model

• Six wired channels 0..5 for PWM mono LEDs, with per-channel INA219 measurement.
• RGB/RGBW/CCT groups with base 0 or 3, depending on layout.
• Addressable S1/S2 strips as virtual groups 6 and 7; they use an external supply and have no power measurement.
• Scenes scenarios, wall switches 1..2, and zones/sensors.

/api/state.system exposes nvs_queue_overflows, nvs_queue_pending and nvs_flush_failures. A non-zero error counter indicates an asynchronous commit that did not reach flash.

/api/state.inputEvents keeps the latest 32 SW1/SW2 events in RAM, in order, with sequence, timestamp, switchId and type. The sequence restarts after reboot and the queue is not persistent.

4 / Wired channels 0–5

pwm:0 is not off: use {"state":false} so the previous level is retained. dimming_ms is the full 0→100% transition time, integer 0..10000; zero is immediate.

curl -fS -X POST -H "Authorization: Bearer $LUMA_TOKEN" \
  -H 'Content-Type: application/json' \
  http://luma.local/api/channel/0 -d '{"state":true,"pwm":60}'

5 / RGB, RGBW, CCT groups and strips

Analogue groups use base 0 or 3; S1/S2 strips use base 6 and 7. In analogue groups, channel positive terminals must be bridged while PWM returns remain separate. Displayed power is the sum of the INA readings and the most restrictive branch governs group derating.

For strip configuration, port 0 = S1 and 1 = S2. Chip 0: WS2812/13/15/SK6812 RGB (GRB); 1: WS2811/UCS1903 RGB 800 kHz; 2: SK6812 RGBW; 3: APA102/SK9822. Chip 3 uses S1 for data and S2 for clock, therefore excluding the second strip.

curl -fS -X POST -H "Authorization: Bearer $LUMA_TOKEN" \
  -H 'Content-Type: application/json' \
  http://luma.local/api/group/6 \
  -d '{"state":true,"brightness":40,"color":"#ff0000","effect":"rainbow"}'

6 / Scenes and wall switches

Scene actions are {type:"channel"|"group"|"all", target, state, value, color?}. For switches, channel_mask uses bits 0–5 for channels and 6/7 for S1/S2; zero means all.

7 / Network, zones and configuration

/api/config/layout accepts: mono6, rgb_mono, mono_rgb, rgb2, rgbw_mono, cct_mono4, m_cct_m3, m2_cct_m2, m3_cct_m, mono4_cct, cct2_mono2, mono2_cct2, rgb_cct_m, cct_m_rgb, rgbw_cct.

8 / Energy and pricing

curl -fsS -H "Authorization: Bearer $LUMA_TOKEN" \
  http://luma.local/api/energy/history | jq '.today, .month'

curl -fS -X POST -H "Authorization: Bearer $LUMA_TOKEN" \
  -H 'Content-Type: application/json' -d '{"value":0.2845}' \
  http://luma.local/api/prefs/kwh-price

9 / Local schedules

Maximum 16 schedules. Channel masks 1..0x3f, weekdays 1..0x7f (bit 0 = Monday), minutes 0..1439, event 0=fixed, 1=sunrise, 2=sunset, solar offset -180..180. Impossible payloads return 422 invalid_schedule.

10 / OTA

11 / KNXnet/IP

The current build includes the KNXnet/IP tunnelling client. Configuration and mappings are persistent and every route requires authentication.

Group addresses are main/middle/sub (0..31/0..7/0..255). KNX Secure secrets are never returned.

12 / MQTT

The user-configurable MQTT client is separate from the private OBJEX Cloud connection. Routes require local authentication; passwords and CAs are never returned.

Empty secret fields retain the existing value; use the dedicated routes to clear them. The mqtt transport requires allowPlaintext:true. MQTT commands always pass through canonical state and cannot bypass electrical or thermal protection.

13 / Home Assistant

The direct integration is independent from MQTT: it uses Zeroconf and HTTP REST on the LAN. Inventory follows Channel setup and exposes mono, RGB, RGBW, CCT and strips as logical entities.

Do not manually create REST switches in YAML. Enable Settings → Protocols → Home Assistant, install the luma component and complete pairing under Settings → Devices & services. The password is used once; the component stores only its dedicated token.

14 / Limits, errors and concurrency

• Ordinary bodies: maximum 8 KB and 4 s; login: 512 B; authenticated import: 64 KB and 10 s.
• 400 invalid JSON/type/URL; 401 missing or expired authentication; 404 missing resource; 409 conflict; 422 impossible configuration; 500 persistence failure; 503 subsystem not ready.
• Import, channel map, scenes, schedules and zones restore the previous snapshot after an error.
• Do not send concurrent commands to the same field expecting a merge: the last valid command wins and firmware state remains the source of truth.

15 / Feature availability

• DALI endpoints /api/dali/* are feature-gated and absent from the current build.
• KNX is enabled. A build that excludes it returns 404 from /api/knx/* without changing configuration.
• Cloud MQTT is managed automatically and exposes no manual HTTP commands. The public MQTT client uses independent credentials and namespace.
• The API can grow with firmware; when in doubt, /api/state is the authoritative reflection of available features.

16 / Destructive actions

These operations can erase data, interrupt service or revoke access. Export the configuration and verify the target before running them.