API Documentation

YOUR ROOM ID
YOUR API KEY

Introduction

The Stagetimer API provides an easy way to remote control your timer with scripts and tools like Bitfocus Companion or vMix.

Most of the endpoints operate on a per-room level, meaning it will interact with the currently highlighted timer. You can see which timer is highlighted by a prominent white border around it on the controller page.

The API is also available for the desktop app. You can download the desktop app for Mac and Windows from the Desktop App download page.

The API is available with any paid license.

How to use this API

If you have never used an API or worked with programming code before, then this page may be confusing to you. API is short for Application Programming Interface, it's a way for two computer programs to talk with each other. For example, you can use this API with the popular Bitfocus Companion software. See this how-to guide for a hands-on example: How to use Stagetimer with Companion for Streamdeck

This documentation uses curl in the code examples. curl is nice because you can just copy-paste the code examples into the command line interface of your computer to try them out. On Mac this is the terminal (How to open the terminal), on Windows it's the command prompt (How to open the command prompt).

👉 Some API endpoints allow you to supply additional information as --data. But on Windows you may experience problems with the --data payload. Alternatively, you can add the them as query parameters, like with the amount in this example:

Example
https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/tweak?amount=+10m

Authentication

Stagetimer uses simple token-based authentication. An API key is required. You can generate an API key on the controller page.

You can authenticate to the API by providing your API key in the HTTP authorization bearer token header. Alternatively, a slightly lower-security approach is to provide your API key with the api_key query parameter.

All API requests must be authenticated and made over HTTPS.

Example
# Example using bearer token (recommended)
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/start \
  -H "Authorization: Bearer %YOUR_API_KEY%"

# Example using query parameter
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/start?api_key=%YOUR_API_KEY%

Using the index to target timers/messages

Default timer appearance
Default appearance of a timer
Highlighted timer
Highlighted timer
Running timer
Running timer

Some endpoints operate on a per-timer or per-message level. They require you to define an INDEX. The INDEX points to the n-th message in the list on the controller page, starting at 1. For example, the first timer has INDEX = 1, the second has INDEX = 2 and so on.

Using the Stagetimer API with the Desktop App

The Stagetimer API is also available for use with the desktop app of the software. To use the API with the desktop app, you will need to adjust the API endpoint URLs.

For example, instead of using the URL https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/start as you would with the web version, you will use https://127.0.0.1:3000/api/v0/room/YOUR_ROOM_ID/start, replacing 127.0.0.1 with the IP address and 3000 with the port number chosen when starting the desktop app.

Stagetimer Offline App for MacOS & Windows
Stagetimer Offline App for MacOS & Windows

You can download the desktop app for Mac and Windows from the Desktop App download page. Keep in mind that the API is only available with paid licenses key for the desktop app. This includes both the Pro and Premium subscriptions.

Using the API with the desktop app allows you to remotely control your timer and automate tasks with scripts and tools like Bitfocus Companion or vMix. Most of the endpoints operate on a per-room level, meaning they will interact with the currently highlighted timer. You can see which timer is highlighted by a prominent prominent blue background on the controller page.

Room endpoints

These endpoints affect the entire room. Most use the currently highlighted timer. A highlighted timer has a blue background when it's paused and a red background when it's running.

POST/room/YOUR_ROOM_ID/start

Starts the highlighted timer if it's not running.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/start \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/stop

Stops the highlighted timer if it's running.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/stop \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/toggle

Starts the highlighted timer if it's currently stopped, or stops the timer if it's running. This endpoint is a combination of the start and stop endpoints and toggles between them.

Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/toggle \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/reset

Resets the highlighted timer if it's running.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/reset \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/next

Stops the highlighted timer if it's running. Then highlights and sets, if possible, the next timer in the list.

Parameters

You can use these parameters in two ways:

1. In the POST body: --data "{"key":"value"}" (preferred)

2. As query parameter by adding ?keyA=valueA&keyB=valueB to the API url

Name Description
start optional 1 start the timer immediately, 0 (default) don't start the timer
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/next \
  -H "Authorization: Bearer %YOUR_API_KEY%" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data "{\"start\":0}"

POST/room/YOUR_ROOM_ID/previous

Resets the highlighted timer if it's running. Otherwise activates and sets, if possible, the previous timer in the list.

Parameters

You can use these parameters in two ways:

1. In the POST body: --data "{"key":"value"}" (preferred)

2. As query parameter by adding ?keyA=valueA&keyB=valueB to the API url

Name Description
start optional 1 start the timer immediately, 0 (default) don't start the timer
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/previous \
  -H "Authorization: Bearer %YOUR_API_KEY%" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data "{\"start\":0}"

POST/room/YOUR_ROOM_ID/tweak

Tweaks the highlighted timer by adding or subtracting time. You have to pass a JSON payload in the body with the amount of time.

Parameters

You can use these parameters in two ways:

1. In the POST body: --data "{"key":"value"}" (preferred)

2. As query parameter by adding ?keyA=valueA&keyB=valueB to the API url

Name Description
amount required A string representing the time added or subtracted. For example, +10m adds 10 minutes and -30s subtracts 30 seconds. Valid are any combination of a prefix (+ or -), a number and a one-letter unit (s for seconds, m for minutes and h for hours).
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/tweak \
  -H "Authorization: Bearer %YOUR_API_KEY%" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data "{\"amount\":\"+10m\"}"

POST/room/YOUR_ROOM_ID/flash

Flashes the timer and message 3 times.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/flash \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/blackout

Toggles the blackout on and off.

Parameters

You can use these parameters in two ways:

1. In the POST body: --data "{"key":"value"}" (preferred)

2. As query parameter by adding ?keyA=valueA&keyB=valueB to the API url

Name Description
force optional 1 to force enable blackout, 0 to force disable blackout
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/blackout \
  -H "Authorization: Bearer %YOUR_API_KEY%"

GET/room/YOUR_ROOM_ID/ping

This endpoint has no effect. It only returns a pong with HTTP status 200 for testing purposes. This enpoint works with GET, POST and all other HTTP verbs.
Example
# Try it yourself
curl -v https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/ping \
  -H "Authorization: Bearer %YOUR_API_KEY%"

Individual timer endpoints

Timer indexes

These endpoints affect a specific timer. They require you to define an INDEX. The INDEX points to the n-th timer in the list on the controller page, starting at 1. For example, the first timer has INDEX = 1, the second has INDEX = 2 and so on.

POST/room/YOUR_ROOM_ID/timer/INDEX/start

Start the timer with the given INDEX. If another timer was running, it will stop the previous timer and activate the new timer. If no timer with the given INDEX exists, then nothing happens.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/timer/1/start \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/timer/INDEX/stop

Stops the timer with the given INDEX, but only if it's the currently highlighted one. If no timer with the given INDEX exists, then nothing happens.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/timer/1/stop \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/timer/INDEX/toggle

Starts or stops the timer with the given INDEX. This endpoint is a combination of the start and stop endpoints and toggles between them.

Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/timer/1/toggle \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/timer/INDEX/set

Sets the timer with the given INDEX. If the timer is running, it is reset. If no timer with the given INDEX exists, then nothing happens.

Parameters

You can use these parameters in two ways:

1. In the POST body: --data "{"key":"value"}" (preferred)

2. As query parameter by adding ?keyA=valueA&keyB=valueB to the API url

Name Description
start optional 1 start the timer immediately, 0 (default) don't start the timer
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/timer/1/set \
  -H "Authorization: Bearer %YOUR_API_KEY%" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data "{\"start\":0}"

POST/room/YOUR_ROOM_ID/timer/INDEX/reset

Resets the running timer with the given INDEX. If no timer with the given INDEX exists, then nothing happens.

👉 Technically identical to /room/YOUR_ROOM_ID/timer/INDEX/set

Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/timer/1/reset \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/timer/INDEX/flash

Flashes the timer 3 times.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/timer/1/flash \
  -H "Authorization: Bearer %YOUR_API_KEY%"

Individual message endpoints

Timer indexes

These endpoints affect a specific message. They require you to define an INDEX. The INDEX points to the n-th message in the list on the controller page, starting at 1. For example, the first message has INDEX = 1, the second has INDEX = 2 and so on.

POST/room/YOUR_ROOM_ID/message/INDEX/show

Shows the message with the given INDEX. If no message with the given INDEX exists, then nothing happens.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/message/1/show \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/message/INDEX/hide

Hides the message with the given INDEX. If no message with the given INDEX exists, then nothing happens.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/message/1/hide \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/message/INDEX/toggle

Shows or hides the message with the given INDEX. This endpoint is a combination of the show and hide endpoints and toggles between them.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/message/1/toggle \
  -H "Authorization: Bearer %YOUR_API_KEY%"

POST/room/YOUR_ROOM_ID/message/INDEX/flash

Flashes the message 3 times.
Example
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/%YOUR_ROOM_ID%/message/1/flash \
  -H "Authorization: Bearer %YOUR_API_KEY%"

Conclusion

The Stagetimer API allows users to remotely control their timer with scripts and tools such as Bitfocus Companion or vMix. The API uses token-based authentication and offers various endpoints that operate on a per-room, per-timer, or per-message level. Users can start, stop, reset, or tweak timers, as well as change messages and control the room's appearance. The API can be used with the popular Bitfocus Companion software and requires a stable internet connection and an updated browser. A Pro or Premium subscription grants access to additional features and an offline device license.