Control API reference

The Control API's actual endpoints, request/response schemas, and error shapes are generated directly from the running system, not maintained by hand here: this page is a map to that generated reference, plus the handful of things worth knowing before you go read it.

Both reflect exactly what this running instance of Buttons actually supports: always check them directly for the current endpoint list, parameters, and schemas rather than relying on a separate written copy that can drift out of date.

Each API group (Cuelists, Connections, Positions, Surfaces, Workflows, Tags, Backups, Routing) is versioned independently. When a group needs a breaking change, Buttons introduces a new version path alongside the existing one (for example, /control/cuelist/v2 next to /control/cuelist/v1) rather than changing v1's behavior out from under existing integrations. Older versions keep working after an upgrade, but will eventually be deprecated and removed, so prefer the latest version documented for a group when starting new work.

Each endpoint's entry in the generated docs notes the Buttons version it was introduced in, so you can tell whether a given capability is available on the version you're running.

A key's own permissions (see Get started with the Control API) still control exactly what it can do within a group: the license tier above is a separate, prerequisite gate on the group as a whole.

Every response uses one of a small, shared set of error shapes ({ message, code }) rather than each endpoint inventing its own. A handful of these apply across the whole API regardless of which endpoint you call: Forbidden, Too Many Requests, and two license-related errors for an under-licensed group or an exhausted license. Beyond those, each endpoint's own documented errors (for example, Not Found or Conflict) are listed specifically for that endpoint in the generated reference: don't assume every endpoint can return every error code; check the specific endpoint's entry.

A separately-shaped validation error ({ message, errors: [{ path, message }] }) can also appear when a request itself doesn't match the expected schema: this is distinct from the tagged error codes above and reflects a request that failed input validation before reaching your endpoint's own logic.