API Documentation

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.

Unhighlighted timer

Appearance of a timer

Highlighted timer

Appearance of a highlighted timer

Running timer

Appearance of a 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 zero. For example, the first timer has INDEX = 0, the second has INDEX = 1 and so on.

# Enter your room ID and API key to use them in the code examples
YOUR ROOM ID
YOUR API KEY

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

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.io with Streamdeck/Companion

Endpoints

Room Endpoints

These endpoints affect the entire room. Most use the currently highlighted timer. You can see which timer is highlighted by a prominent white border around it on the controller page.


POST/room/YOUR_ROOM_ID/start

Starts the highlighted timer if it's not running.
# 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.
# 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.

๐Ÿ‘‰ Deprecated: start-stop instead of toggle

# 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.
# 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. (Does not start the timer)
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/next \
  -H "Authorization: Bearer YOUR_API_KEY"

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. (Does not start the timer)
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/previous \
  -H "Authorization: Bearer YOUR_API_KEY"

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.

Body parameters

NameDescription
amount requiredA 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).
# 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' \
  -d $'{"amount":"+10m"}'

POST/room/YOUR_ROOM_ID/flash

Flashes the timer and message 3 times.
# 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.
# 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.
# 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 zero. For example, the first timer has INDEX = 0, the second has INDEX = 1 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.
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/timer/0/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.
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/timer/0/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.

๐Ÿ‘‰ Deprecated: start-stop instead of toggle

# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/timer/0/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.
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/timer/0/set \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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

POST/room/YOUR_ROOM_ID/timer/INDEX/flash

Flashes the timer 3 times.
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/timer/0/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 zero. For example, the first timer has INDEX = 0, the second has INDEX = 1 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.
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/message/0/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.
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/message/0/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.
# Try it yourself
curl -v -X POST https://api.stagetimer.io/v0/room/YOUR_ROOM_ID/message/0/toggle \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/room/YOUR_ROOM_ID/message/INDEX/flash

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