External API
Control your show from your own code: a livestream overlay, a bot, a custom page. Three endpoints. Request access under Settings → Account & API.
Authentication
Sign an HS256 JWT with payload {"accessToken": "<your API access token>"} using your API secret key. No other claims or expiry are required. Send it as Authorization: Bearer <jwt>. Sign on a server you control; anyone with the secret can act as your show. Refreshing the secret invalidates every existing token.
import jwt, requests
token = jwt.encode({"accessToken": ACCESS_TOKEN}, SECRET_KEY, algorithm="HS256")
r = requests.get("https://pickthelights.com/external-api/showDetails", headers={"Authorization": f"Bearer {token}"})Endpoints
Base URL: https://pickthelights.com/external-api
| Method | Path | Body |
|---|---|---|
| GET | /showDetails | — · returns preferences, sequences, queue, votes, playing now/next |
| POST | /addSequenceToQueue | {"sequence": "<name>", "viewerLatitude"?, "viewerLongitude"?} (Jukebox mode) |
| POST | /voteForSequence | same (Voting mode) |
Use the sequence's name (the MadMapper timeline name), not its display name.
Responses
| Status | Meaning |
|---|---|
| 200 | Success |
| 202 | Refused — body {"message": CODE}: QUEUE_FULL, SEQUENCE_REQUESTED, ALREADY_REQUESTED, ALREADY_VOTED, DAILY_VOTE_LIMIT_REACHED, INVALID_LOCATION, INVALID_LOCATION_CODE, SEQUENCE_UNAVAILABLE, VIEWER_CONTROL_DISABLED, CATEGORY_LIMIT, NAUGHTY |
| 401 | Authentication failed |
| 429 | Rate limited (120 requests/minute). Poll showDetails no faster than every 5 s. |
Agent API
The agent uses a separate API under /agent-api/ authenticated with the show token (X-Show-Token header): heartbeat, sync, next, playing, idle, config. If you want to build your own agent for other software, the reference agent is the contract.