Blog
Why runofsho is built API-first
Every button in the interface calls the same public API that your own tools can call. That was the first design decision, and it shaped the rest.
runofsho is API-first because live shows already run on other equipment. Vision mixers, button panels, graphics and automation need to read and control the same timing the crew sees. Building the app on its own public API means nothing in the interface is out of reach of an integration, and the documentation cannot drift from behavior.
ON THIS PAGE
The booth is already full of other tools
A show is not run from one application. There is a vision mixer, a graphics machine, a playback system, an audio console, usually a panel of programmable buttons, and somebody's laptop with a script on it. A rundown tool that cannot talk to any of them becomes one more screen that a person has to keep in step by hand.
So the question we started with was not "what should the interface look like?" It was "what would this need to expose so that a show could be run without touching the interface at all?"
What API-first means here
Three commitments:
- The app has no private shortcuts. If the web app can do it, a request to the public API can do it, with the same permissions model.
- The specification is generated from the running code. The reference describes what the server does, because it is produced by the server.
- Displays are just clients. A stage timer, a backstage screen and a third-party overlay all read the same room state.
The clock problem
The naive way to build a shared timer is to have a server send a tick every second. It fails in the way that matters most: screens fall out of step when a network hiccups, and a hundred displays show ninety-eight different seconds.
runofsho does not tick. Playback is stored as timestamps: when the item started, how long it has been paused, how long it should run. Each screen syncs its clock with the server once and then computes the time remaining locally, many times a second. A display that drops off the network for a moment comes back to the correct time without being told anything.
That design has a useful side effect for developers. You do not need a streaming connection to show an accurate countdown. One request for room state and one for server time is enough to draw a correct timer.
Built for the ways live control goes wrong
A public API for live shows has to assume a button will be pressed twice.
| Failure | What happens without protection | What the API does |
|---|---|---|
| Two operators press Next together | The show skips a speaker | Commands can carry the version they expect. The stale one is rejected. |
| A request times out and retries | The cue fires twice | An idempotency key makes the retry a no-op. |
| A toggle is sent twice | Play becomes pause | Explicit start and stop exist beside toggle. |
| The rundown is reordered mid-show | "Item 3" is now a different talk | Items can be addressed by your own stable ID. |
| A display link leaks | Someone controls the show | Output links are read-only and limited to one room. |
What it makes possible
- A button panel that starts the next item and lights up when a speaker goes into overtime.
- A vision mixer that shows the countdown as a data source or overlay.
- A webhook that posts to a team channel when a session starts late.
- An automation that rolls walk-on music when the timer hits zero.
- A custom view for a client who wants the agenda in their own design.
Integrations for Bitfocus Companion, vMix, OBS overlays, Stream Deck, MIDI and OSC are built on this API. We want to be direct about their status: they are implemented, and they are still being validated against real hardware before launch.
The trade-off
API-first is slower to build. Every feature needs a designed, documented, versioned contract before it has a button. We think that cost is worth paying once, by us, rather than repeatedly by every crew that wants to connect one more device.
There is more detail, including example requests, on the developer page.
FAQ
What does API-first mean?
The public API is designed first and the product's own interface is built on top of it. Anything a user can do in the app can also be done by code.
Do I need to be a developer to use runofsho?
No. The web app is complete on its own. The API matters when you want your booth hardware or other software to follow or control the show.
Is the API a paid extra?
No. API access is included on every plan, including the free one, with a request limit that rises on paid plans. See pricing.