Buttons offers several distinct ways for another system to reach into it: a general-purpose API, network-listening workflow nodes, a narrow surface-emulation protocol, and an inbound tally listener. They serve different jobs. This page is a chooser: what each one is actually for, what it requires, and which one fits your situation.
The Control API: the supported general-purpose interface#
If you need another system to read state, trigger actions, or manage resources in Buttons, this is the one to reach for first. It's the only interface Buttons documents as a general-purpose, supported way for an external system to operate it.
- What it's for: reading and controlling positions, connections, routing, NMOS, surfaces, workflows, tags, and more, from a script, show-control system, or automation tool.
- Requires: a scoped API key with the specific permissions your integration needs, and at minimum an Individual license (Routing access specifically requires Pro).
- Auth:
Authorization: Bearer <token>, rate-limited system-wide.
Workflow network nodes: build a custom listener yourself#
Workflows can open their own network listeners as part of a graph you build: useful when you need a very specific, ad hoc entry point (say, a lighting console pushing OSC messages, or a small REST endpoint a third-party tool calls directly) rather than the Control API's general resource model.
- OSC Listener and REST Server are fully supported, released nodes. REST Server has its own independent Bearer-token authentication and rate limiting, configured on the node itself; OSC Listener has no authentication of its own: anything that can reach the configured UDP port can send it messages, so keep it off any network you don't trust.
- TCP Server, UDP Receiver, and WebSocket Server (along with their outbound Client counterparts) are experimental: hidden by default, and their configuration and support status can change without notice. Don't build a production integration around them.
Each of these is opened per-workflow, by an admin dragging the node onto a canvas and configuring a port: it's not a fixed system endpoint like the Control API, and it isn't covered by the Control API's authentication or rate-limit settings.
Third-party surface protocol: for building a device, not an integration#
Buttons has a certificate-authenticated WebSocket protocol that lets a device announce itself and send button presses, exactly as a Stream Deck or other adopted panel would. It's deliberately narrow: it can report button presses and receive rendered button state, nothing more; it can't call arbitrary actions or read variables the way the Control API can.
This exists to let hardware or an emulator act as a surface, not as a general integration point. It's off by default (a feature flag has to be enabled), requires a paid license, and there's no public developer guide for building against it. Unless you're specifically building surface hardware or an emulator, use the Control API instead.
TSL Server (Listen): inbound tally and labels only#
A Tally connection set to
Server (Listen) lets another system (a switcher's own tally output, or a third-party controller) send tally state and labels into Buttons over the network. This is a real inbound listener, but it's scoped to tally/label data only; it can't trigger actions or otherwise operate Buttons. See
Configure TSL connections.
Bitfocus Listener: the reverse direction#
Bitfocus Listener is easy to mistake for an external-control interface, but it runs the other way: Buttons is the one that connects out and drives Listener, triggering keypresses and shell commands on the machine Listener is installed on. There's no path for an external system to use Listener to trigger something inside Buttons. See
Connect to Bitfocus Listener.
What isn't a supported external interface#
Buttons' own web interface talks to its backend using an internal API authenticated by browser session cookie, not a bearer token: it has no supported path for external callers and isn't documented as one. There's also no WebSocket or streaming endpoint on the Control API itself for subscribing to live state changes; if you need live updates, poll the Control API or build that logic into a workflow instead.
If you get stuck#
What you need | Use this |
|---|
General read/write access to Buttons resources from a script or another system. | The Control API. |
A very specific inbound listener (OSC, a small REST endpoint) tied to one workflow's logic. | A Workflow OSC Listener or REST Server node. |
You're building hardware or an emulator that should act like a Stream Deck. | The third-party surface protocol: expect to work from the protocol schema directly, since there's no developer guide. |
Tally or label data coming from a switcher or third-party controller. | A Tally connection set to Server (Listen). |
You want Buttons to trigger something on another machine. | Bitfocus Listener: remember it only runs in that direction. |
Something claims to integrate via Buttons' internal web API. | That's not a supported path: point it at the Control API instead. |
Where to go next#
