1. Home
  2. Developers

Developers

Every button in the app is an API call

The web app talks to the same public API you do. If something works in the interface, it works from your code, your Stream Deck or your vision mixer.

Updated
SHORT ANSWER

runofsho exposes rundowns, rooms, timers, messages and output screens through a documented REST API with real-time events and signed webhooks. The specification is published as OpenAPI 3.1 and AsyncAPI 3.0, with typed TypeScript and PHP SDKs. API access is included on every plan, including Free.

ON THIS PAGE
  1. The model in four nouns
  2. What a show looks like in curl
  3. Designed for live use
  4. Integrations
  5. FAQ

The model in four nouns

  • An event holds one or more rundowns.
  • A rundown is an ordered list of items. Every item is a timer with a name, speaker, duration and wrap-up thresholds.
  • A room is one stage or group of screens. It plays one rundown.
  • Room state is the single object a display needs: the current and next item, playback timestamps, the active message and the wrap-up phase.

The server never ticks. Playback is three timestamps, and every screen computes the time remaining from a clock it syncs with the server. That is why a hundred screens show the same second.

What a show looks like in curl

The calls below are the shape of a real session. The base URL and API reference open with public launch.

# Create an event, a rundown and two items
curl -X POST $API/events -H "Authorization: Bearer $KEY" \
  -d '{"name":"Product Summit","timezone":"America/New_York"}'
curl -X POST $API/events/$EVENT/rundowns -d '{"name":"Main stage"}'
curl -X POST $API/rundowns/$RUNDOWN/items \
  -d '{"name":"Keynote","speaker":"Dana Kim","duration":"20m","wrap_up_yellow_s":120,"wrap_up_red_s":30}'

# Put it on a stage and run it
curl -X POST $API/rooms -d '{"name":"Main Hall","active_rundown_id":"'$RUNDOWN'"}'
curl -X POST $API/rooms/$ROOM/playback/start
curl -X POST $API/rooms/$ROOM/playback/add-time -d '{"amount":"1m"}'
curl -X POST $API/rooms/$ROOM/messages -d '{"text":"Please wrap up","color":"red"}'
curl -X POST $API/rooms/$ROOM/playback/next -d '{"expected_version":14}'

Designed for live use

Concern How the API handles it
Two operators press Next at once Commands accept expected_version. The second, stale press is rejected instead of skipping a speaker.
A request times out and is retried Commands accept an Idempotency-Key, and explicit start and stop exist beside toggle.
A rundown is reordered Items can be targeted by your own external_id, not by position.
Displays must not control the show Output tokens are read-only and limited to one room. API keys have scopes: read, operate, manage, admin.
Screens drift apart Clients sync to server time and compute the countdown locally from shared timestamps.
Other systems need to react Signed webhooks with retries and a delivery log, plus real-time events over a socket or server-sent events.

Integrations

These are built on the same API. They are implemented and are being validated against physical hardware and the real applications ahead of launch.

  • Bitfocus Companion: a module with actions and feedbacks for rooms and timers.
  • vMix: JSON and XML data source feeds, plus a transparent overlay view.
  • OBS: a transparent overlay output you add as a browser source.
  • Stream Deck, MIDI and OSC: a per-room control map decides what each key, note or address does.
  • Zapier, Make and n8n: recipes that use webhooks and plain HTTP requests.

FAQ

Is the API included on the free plan?

Yes, at 60 requests a minute. Pro and Studio allow 600 a minute. See pricing.

Is there an OpenAPI specification?

Yes. The REST API is described in OpenAPI 3.1 and the real-time events in AsyncAPI 3.0. Both are generated from the running code, so they cannot drift from behavior. They will be published with the API reference at launch.

Which SDKs exist?

TypeScript and PHP clients are generated from the specification. The TypeScript SDK also handles clock sync and live room state.

See it run before your next show.

Open the sample room, start a cue, add a minute and send a message. No account needed.

Try a sample room