api reference

Design

Two rules explain every choice below:

• Reading state never requires polling. Subscribe to /api/v1/events once and you are told about every change. GET /api/v1/zones exists to bootstrap or for one-shot scripts.
• Commands are plain HTTP. No handshake, no socket, no correlation ids — a curl one-liner or a five-line shell script is a first-class client.

Every successful command is followed by an event, so you never have to read back after writing: zone.changed for anything that alters a zone's state, and queue.changed, favorites.changed or recents.changed for the collections — those say that something changed and leave you to re-read the page you are showing.