# Every button in the app is an API call

> runofsho is API-first. Rundowns, timers, messages and outputs are available through a REST API with real-time events, webhooks, OpenAPI and AsyncAPI specs, and TypeScript and PHP SDKs.

- Canonical: https://runofsho.com/developers/
- Last updated: 2026-11-16
- Publisher: runofsho

**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.

## 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.

```bash
# 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](https://runofsho.com/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.
