API reference
Every HTTP endpoint, with its parameters, request body and responses, code samples in curl, JavaScript and Python, and a Try it panel.
Everything the web app does goes through this API, so anything else can do it too: scripts, Home Assistant, a Stream Deck, a lighting desk. It is plain HTTP with JSON bodies on the same port as the web app (8080 by default).
Auth. Without a PIN lock every call works for everyone who can reach the port. With one, admin calls need an unlock token from POST /api/unlock, sent as the x-tempolight-token header (or ?token=); guest-area calls work without one when that area is allowed in Settings.
Origin rule. Calls that change something are refused with 403 when a browser sends them from another website. Scripts and apps send no Origin and aren't affected. To send requests from the Try it panel of the docs site, an admin turns on Integrations → Docs site → Let the docs site try API calls (PATCH /api/integrations/docs).
Errors answer {"error": "<a sentence for people>"} with a 4xx or 5xx status.
Live data (status 4 times a second, LED previews, browser audio, the song clock) goes over one WebSocket at /ws, which OpenAPI can't describe: see the WebSocket page.
Base URL
Every call goes to the computer running Tempolight, on the web app's port:
| Server | Address |
|---|---|
| Your Tempolight | http://localhost:8080 |
| Tempolight on another computer | http://{host}:{port} |
Endpoints by area
Everything the web app reads to draw itself, and a health check for monitoring.
StatusWhat is happening right now: the music source, tempo, song part, effect, devices and their latency.
Lights & showPower, brightness, effects, zones and the live pads.
Your own effectsEffects you build from parts on the Effects page.
Scenes & schedulesSaved looks, and times at which they (or on, off, a brightness) happen by themselves.
Home & sleepSunrise alarm, sleep timer and the ambient plan for the day.
Devices & roomLight controllers (WLED, Hue, Nanoleaf, Govee, OpenRGB, LIFX, WiZ, Kasa, Yeelight, Twinkly, DMX) and where their LEDs are in the room.
DMXFixtures on an Art-Net or sACN universe: pars, moving heads, lasers, fog.
MusicSongs played in a browser, their clock, song memory and each song's editable show.
HearingHow Tempolight hears the music: the guided panel on the Music page.
Now playingThe track music apps on this computer play, and the Spotify sign-in.
SpotifyLights that follow the Spotify track with its beat map.
RequestsGuest song requests from `/request`.
SettingsEvery setting, in one call.
Backup & updatesBackup, restore, reset to defaults, updates and quitting.
Wi-FiThe Raspberry Pi image's Wi-Fi setup.
LockThe PIN lock and unlock tokens.
Apple HomeThe built-in HomeKit bridge.
IntegrationsOBS, Twitch, Discord and the Stream Deck plugin.
GamesCounter-Strike 2 and Dota 2 game-state integration.