API Reference

Every route, with curl.

Base URL http://localhost:8500. All bodies are JSON. Replace bulb-1 with your device's id from config.json. Interactive Swagger docs are auto-generated at /docs on your running instance.

Color — the main thing you're here for

# RGB
curl -X POST http://localhost:8500/api/devices/bulb-1/color \
  -H "Content-Type: application/json" \
  -d '{"r": 255, "g": 0, "b": 0}'

# HSV (h: 0-359, s/v: 0-100)
curl -X POST http://localhost:8500/api/devices/bulb-1/color/hsv \
  -H "Content-Type: application/json" \
  -d '{"h": 120, "s": 100, "v": 100}'

Power & brightness

curl -X POST http://localhost:8500/api/devices/bulb-1/power -d '{"on": true}' -H "Content-Type: application/json"
curl -X POST http://localhost:8500/api/devices/bulb-1/brightness -d '{"value": 60}' -H "Content-Type: application/json"

Scenes, presets, effects

curl -X POST http://localhost:8500/api/devices/bulb-1/scenes/apply -d '{"scene_id":"movie_night"}' -H "Content-Type: application/json"
curl -X POST http://localhost:8500/api/devices/bulb-1/presets/apply -d '{"preset_id":"ocean"}' -H "Content-Type: application/json"
curl -X POST http://localhost:8500/api/devices/bulb-1/effects/start -d '{"effect":"rainbow","speed":1.5}' -H "Content-Type: application/json"

Audio-reactive lighting

Full mode list and design notes on the Audio-Reactive Lighting page.

curl http://localhost:8500/api/audio/devices

curl -X POST http://localhost:8500/api/devices/bulb-1/audio-reactive/start \
  -H "Content-Type: application/json" \
  -d '{"device_index": 1, "mode": "band_fixed", "sensitivity": 1.0, "min_dwell_ms": 90}'

curl http://localhost:8500/api/devices/bulb-1/audio-reactive/status
curl -X POST http://localhost:8500/api/devices/bulb-1/audio-reactive/stop

Group orchestration

curl -X POST http://localhost:8500/api/groups/all/audio-reactive/start \
  -H "Content-Type: application/json" \
  -d '{"device_index": 1, "mode": "band_fixed", "role_mode": "phase_offset"}'

Network discovery

curl http://localhost:8500/api/system/discovery
curl -X POST http://localhost:8500/api/system/scan

Remote-access auth

See Remote Access & Security before enabling this beyond your LAN.

curl -X POST http://localhost:8500/api/system/remote-auth/enable \
  -H "Content-Type: application/json" -d '{"pin": "your-real-pin-here"}'

curl -X POST http://localhost:8500/api/auth/login \
  -H "Content-Type: application/json" -d '{"pin":"your-real-pin-here"}'

# Session management (v0.3.0) — list, revoke one, or revoke everyone
curl http://localhost:8500/api/auth/sessions
curl -X POST http://localhost:8500/api/auth/sessions/revoke -d '{"session_id":"..."}' -H "Content-Type: application/json"
curl -X POST http://localhost:8500/api/auth/sessions/revoke-all

# Per-IP login rate limit, independent of the existing lockout
curl -X POST http://localhost:8500/api/system/remote-auth/rate-limit \
  -H "Content-Type: application/json" -d '{"max_attempts": 20, "window_s": 60}'

Every auth event (login success/failure, lockout, revocation) is appended to backend/data/auth_audit.log — one JSON line per event, never containing the PIN or a raw session token.

Analytics v0.3.0

Real per-device on-time, derived from logged history — not fabricated wattage (this bulb has no real power-draw sensor).

curl "http://localhost:8500/api/analytics/usage?period=today"
curl "http://localhost:8500/api/analytics/usage?period=7d"

CLI — `bulbctl` v0.3.0

A stdlib-only Python CLI wrapping this whole API, for scripting/cron without hand-rolling curl:

python cli/bulbctl.py list
python cli/bulbctl.py on bulb-1
python cli/bulbctl.py color bulb-1 ff0000
python cli/bulbctl.py brightness bulb-1 60
python cli/bulbctl.py scene bulb-1 movie_night
python cli/bulbctl.py login   # if the PIN gate is enabled

Timers, schedule, groups, history, diagnostics

Endpoint	Purpose
`/api/devices/{id}/timers/sleep`	Sleep timer with gradual fade-out
`/api/devices/{id}/timers/wake`	Wake/sunrise timer
`/api/devices/{id}/schedule`	Recurring time-of-day rules
`/api/groups/{id}/power`, `/color`	Broadcast to every device in a group
`/api/devices/{id}/history`	Last 200 actions, timestamped
`/api/devices/{id}/test-connection`	TCP reachability + latency + status round-trip

Full reference for every one of the 60+ routes — favorites, sleep/wake timer status, schedule rule management, group color broadcast, discovery ignore/unignore, session management, analytics — is in the complete API.md, or explore it live at /docs on your running instance.