API Documentation

YOUR ROOM ID
YOUR API KEY

Introduction

The Stagetimer API enables you to remotely control your timer using scripts and tools like Bitfocus Companion or vMix. It offers both HTTP endpoints and a socket.io endpoint for real-time updates. Most endpoints interact with the currently highlighted timer, indicated by a blue background on the controller page.

The API is accessible with any paid license and is also available for the desktop app.

How to use this API

If you're new to APIs or programming, this page may seem confusing. An API (Application Programming Interface) allows two computer programs to communicate. For example, you can use this API with the Bitfocus Companion software. For a hands-on example, see: 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. For Mac, use Terminal (How to open the terminal), and for Windows, use Command Prompt (How to open the command prompt).

If you are completely new to APIs then read "Understanding GET Requests and Query Parameters" and "Targeting Timers and Messages" at the end of this page.

Authentication

Stagetimer uses token-based authentication, requiring an API key generated on the controller page. Authenticate by sending your API key using the api_key query parameter, or send it as a "bearer token" in the HTTP Authorization header. All API requests must be authenticated and made over HTTPS.

Authenticate with query parameter (Example)
curl "https://api.stagetimer.io/v1/test_auth?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
Authenticate with bearer token (Example)
curl "https://api.stagetimer.io/v1/test_auth?room_id=YOUR_ROOM_ID" -H "Authorization: Bearer YOUR_API_KEY"
API credentials in the controller menu
API credentials are available in the menu of the controller page
API credentials popup
Use the “API documentation” button to prefill this page with your credentials

HTTP Endpoints

The OpenAPI spec for this API is available here: Download stagetimer-api-v1-spec.yaml

General

Test API connection

GEThttps://api.stagetimer.io/v1/

The root endpoint can be used to verify the connection to the API. It responds with a greeting and a list of available routes.

Query parameters:

This endpoint doesn't accept query parameters.

Request (example)
curl "https://api.stagetimer.io/v1/"
200 – Response (example)
{
 "ok": true,
 "message": "This is the stagetimer.io Web API v1",
 "data": {
  "docs": "https://stagetimer.io/docs/api-v1/",
  "routes": [
   "/start",
   "/stop",
   "/next",
   "/previous",
   "..."
  ]
 }
}

General

Test API authorization

GEThttps://api.stagetimer.io/v1/test_auth

Used to verify that authorization is working. Returns a message confirming authorization.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/test_auth?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "You are authorized to use the Stagetimer API for room: XYZABCDE"
}

Room

Get playback status

GEThttps://api.stagetimer.io/v1/get_status

Get the playback status of the highlighted timer in the room. start, finish, and pause are timestamps in milliseconds since the Unix epoch. Calculate the duration with duration = finish - start and the remaining time with remaining time = finish - now. If the timer is paused, then running = false, and pause is the point in time when it was paused.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/get_status?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Playback status loaded",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Room

Get room

GEThttps://api.stagetimer.io/v1/get_room

Get the state of a room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/get_room?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Room loaded",
 "data": {
  "_id": "6ADP4P5U",
  "_model": "room",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "name": "Main stage",
  "blackout": false,
  "focus_message": false,
  "logo": "https://stagetimer.io/assets/logo-dark.png",
  "timezone": "Europe/Berlin"
 }
}

Room

Get logs

GEThttps://api.stagetimer.io/v1/get_logs

Get logs for past events in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
limit
Optional <integer>
Default: 20
Min: 1
Max: 200
Limit the requested amount of log messages.
offset
Optional <integer>
Default: 0
Min: 0
Max: 200
Request log messages with this offset. Use this to paginate over the dataset.
Request (example)
curl "https://api.stagetimer.io/v1/get_logs?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Logs loaded",
 "data": [
  "2023-05-01T08:40:06.463Z | Device YCB7 | Added `1m` to timer. New value: `0:03:00`",
  "..."
 ]
}

Transport

Start

GEThttps://api.stagetimer.io/v1/start

Start/resume the highlighted timer in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/start?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer started at 0:01:00",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Transport

Stop

GEThttps://api.stagetimer.io/v1/stop

Stop the highlighted timer in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/stop?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer stopped at `0:00:30",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Transport

Start/stop

GEThttps://api.stagetimer.io/v1/start_or_stop

Start OR stop the currently highlighted timer.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/start_or_stop?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer stopped at `0:00:30",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Transport

Reset

GEThttps://api.stagetimer.io/v1/reset

Reset or restart the currently highlighted timer.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
autostart
Optional <boolean>
Default: false
Set to true to automatically start the timer after the action is triggered.
Request (example)
curl "https://api.stagetimer.io/v1/reset?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer _Timer 1_ reset (`0:00:30`)",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Transport

Next

GEThttps://api.stagetimer.io/v1/next

Highlight the next timer in the list. Optionally, you can automatically start the next timer once it's highlighted.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
autostart
Optional <boolean>
Default: false
Set to true to automatically start the timer after the action is triggered.
Request (example)
curl "https://api.stagetimer.io/v1/next?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Next timer _Timer 1_ selected (`0:05:00`)",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Transport

Previous

GEThttps://api.stagetimer.io/v1/previous

Reset the currently highlighted timer if it is running. If the highlighted timer is not running, highlight the previous timer in the list. Optionally, you can automatically start the previous timer once it's highlighted.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
autostart
Optional <boolean>
Default: false
Set to true to automatically start the timer after the action is triggered.
Request (example)
curl "https://api.stagetimer.io/v1/previous?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Previous timer _Timer 1_ selected (`0:01:00`)",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Transport

Add time

GEThttps://api.stagetimer.io/v1/add_time

Add an amount of time to the highlighted timer in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
amount
Required <string>
Example: 30s
An amount of time specified by a number followed by a divison of time. Eg. 5s for 5 seconds, 10m for 10 minutes, etc.
Request (example)
curl "https://api.stagetimer.io/v1/add_time?room_id=YOUR_ROOM_ID&amount=30s&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Added `30s` to timer. New value: `0:01:30`",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Transport

Subtract time

GEThttps://api.stagetimer.io/v1/subtract_time

Subtract an amount of time from the highlighted timer in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
amount
Required <string>
Example: 30s
An amount of time specified by a number followed by a divison of time. Eg. 5s for 5 seconds, 10m for 10 minutes, etc.
Request (example)
curl "https://api.stagetimer.io/v1/subtract_time?room_id=YOUR_ROOM_ID&amount=30s&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Subtracted `30s`` from timer. New value: `0:01:00`",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Viewer

Flash the screen

GEThttps://api.stagetimer.io/v1/start_flashing

Flashes the screen in the room. Can be used to grab the attention of speakers.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
count
Optional <integer>
Example: 10
Default: 3
Number of times to repeat the action. Accepted numbers: 1 - 999.
Request (example)
curl "https://api.stagetimer.io/v1/start_flashing?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Triggered flashing (×5)"
}

Viewer

Stop flashing

GEThttps://api.stagetimer.io/v1/stop_flashing

Stops any flashing timers and message on the screen.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/stop_flashing?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Stopped flashing"
}

Viewer

Enable blackout mode

GEThttps://api.stagetimer.io/v1/enable_blackout

Enable blackout mode in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/enable_blackout?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Blackout mode enabled"
}

Viewer

Disable blackout mode

GEThttps://api.stagetimer.io/v1/disable_blackout

Disable blackout mode in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/disable_blackout?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Blackout mode disabled"
}

Viewer

Toggle blackout mode

GEThttps://api.stagetimer.io/v1/toggle_blackout

Toggle (enable OR disable) blackout mode in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/toggle_blackout?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Blackout mode toggled (enabled)"
}

Viewer

Enable focus mode

GEThttps://api.stagetimer.io/v1/enable_focus

Enable focus mode in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/enable_focus?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Focus mode enabled"
}

Viewer

Disable focus mode

GEThttps://api.stagetimer.io/v1/disable_focus

Disable focus mode in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/disable_focus?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Focus mode disabled"
}

Viewer

Toggle focus mode

GEThttps://api.stagetimer.io/v1/toggle_focus

Toggle (enable OR disable) focus mode in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/toggle_focus?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Focus mode toggled (enabled)"
}

Timers

Start timer

GEThttps://api.stagetimer.io/v1/start_timer

Start/resume a specific timer in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
timer_id
Optional <string>
Example: 63f59467d68bfdeef6b3bfc3
ID of the timer to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/start_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer started at 0:01:00",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Timers

Stop timer

GEThttps://api.stagetimer.io/v1/stop_timer

Stop a specific timer in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
timer_id
Optional <string>
Example: 63f59467d68bfdeef6b3bfc3
ID of the timer to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/stop_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer stopped at `0:00:30",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Timers

Start/stop a timer

GEThttps://api.stagetimer.io/v1/start_or_stop_timer

Toggle (start/stop) a specific timer in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
timer_id
Optional <string>
Example: 63f59467d68bfdeef6b3bfc3
ID of the timer to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/start_or_stop_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer stopped at `0:00:30",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Timers

Reset timer

GEThttps://api.stagetimer.io/v1/reset_timer

Reset a specific timer in the room to its original duration.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
timer_id
Optional <string>
Example: 63f59467d68bfdeef6b3bfc3
ID of the timer to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/reset_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer reset to `0:01:00",
 "data": {
  "_model": "playback_status",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": false,
  "start": 1677055206453,
  "finish": 1677055206453,
  "pause": 1677055206453,
  "server_time": 1677055206453
 }
}

Timers

Get all timers

GEThttps://api.stagetimer.io/v1/get_all_timers

Get all timers in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/get_all_timers?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timers loaded",
 "data": [
  {
   "_id": "63f59467d68bfdeef6b3bfc3",
   "_model": "timer",
   "_updated_at": "2023-05-01T08:40:06.463Z",
   "name": "Timer 1",
   "speaker": "Thomas",
   "notes": "Very tall, remember to adjust camera angle",
   "labels": [
    {
     "name": "VT",
     "color": "#F44336"
    }
   ],
   "appearance": "COUNTDOWN",
   "type": "DURATION",
   "duration": "0:01:00",
   "hours": 0,
   "minutes": 1,
   "seconds": 30,
   "wrap_up_yellow": 60,
   "wrap_up_red": 15,
   "trigger": "MANUAL",
   "start_time": "2023-05-01T08:40:06.463Z",
   "start_time_uses_date": false,
   "finish_time": "2023-05-01T08:40:06.463Z",
   "finish_time_uses_date": false
  },
  "..."
 ]
}

Timers

Get timer

GEThttps://api.stagetimer.io/v1/get_timer

Get a timer in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
timer_id
Optional <string>
Example: 63f59467d68bfdeef6b3bfc3
ID of the timer to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/get_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer loaded",
 "data": {
  "_id": "63f59467d68bfdeef6b3bfc3",
  "_model": "timer",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "name": "Timer 1",
  "speaker": "Thomas",
  "notes": "Very tall, remember to adjust camera angle",
  "labels": [
   {
    "name": "VT",
    "color": "#F44336"
   }
  ],
  "appearance": "COUNTDOWN",
  "type": "DURATION",
  "duration": "0:01:00",
  "hours": 0,
  "minutes": 1,
  "seconds": 30,
  "wrap_up_yellow": 60,
  "wrap_up_red": 15,
  "trigger": "MANUAL",
  "start_time": "2023-05-01T08:40:06.463Z",
  "start_time_uses_date": false,
  "finish_time": "2023-05-01T08:40:06.463Z",
  "finish_time_uses_date": false
 }
}

Timers

Create timer

GEThttps://api.stagetimer.io/v1/create_timer

Create a new timer in the room. New timers are added to the end of the list. Default values are used for any parameter not provided. IDs are auto-generated.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
name
Optional <string>
Example: Timer 1
Default: Timer [n]
Name of the timer.
speaker
Optional <string>
Example: Thomas
Default: [blank]
Used to identify speakers.
notes
Optional <string>
Example: Very tall, remember to adjust camera angle
Default: [blank]
Notes related to the timer or speaker.
labels
Optional <array>
Example: [ { "name": "VT", "color": "#F44336" } ]
Default: []
Colored tags visible on the controller page. Can be provided using indexed notation in the URL query string.
Example usage: ?labels[0][name]=VT&labels[0][color]=%23F44336&labels[1][name]=Break&labels[1][color]=%234CAF50
This represents an array of two labels:
  1. Name: "VT", Color: "#F44336" (Red)
  2. Name: "Break", Color: "#4CAF50" (Green)

Note: The '#' in color codes must be URL-encoded as '%23'.
You can add as many labels as needed by incrementing the index and providing both 'name' and 'color' for each.
appearance
Optional <string>
Default: COUNTDOWN
Possible values: COUNTDOWN, COUNTUP, TOD, COUNTDOWN_TOD, COUNTUP_TOD, HIDDEN
Defines how the timer is displayed. Read more: Timer Appearances
type
Optional <string>
Default: DURATION
Possible values: DURATION, FINISH_TIME
Defines the type of timer, ie. how runtime length is handled. Read more: Timer Types
hours
Optional <integer>
Example: 0
Default: 0
Duration (hours).
minutes
Optional <integer>
Example: 1
Default: 10
Duration (minutes).
seconds
Optional <integer>
Example: 30
Default: 0
Duration (seconds).
wrap_up_yellow
Optional <integer>
Default: 60
Yellow wrap-up time (in seconds from the end).
wrap_up_red
Optional <integer>
Default: 15
Red wrap-up time (in seconds from the end).
trigger
Optional <string>
Default: MANUAL
Possible values: MANUAL, LINKED, SCHEDULED
Defines how the timer is triggered (started). Read more: Timer Triggers
start_time
Optional <string>
Example: 2023-05-01T08:40:06.463Z
Default: null
Set a hard start time for this cue. Required when trigger=SCHEDULED, but otherwise optional.
start_time_uses_date
Optional <boolean>
Default: false
Determines if the date-part of start_time is being used. If true, then the the full date is used (e.g. 11 am on Oct 6). But if false, the start date is interpreted as today and the date part ignored (e.g. 11 am today).
finish_time
Optional <string>
Example: 2023-05-01T08:40:06.463Z
Default: null
Finish time for the cue. Required when type=FINISH_TIME, otherwise ignored.
finish_time_uses_date
Optional <boolean>
Default: false
Determines if the date-part of finish_time is being used. If true, then the the full date is used (e.g. 11 am on Oct 6). But if false, the start date is interpreted as today and the date part ignored (e.g. 11 am today).
Request (example)
curl "https://api.stagetimer.io/v1/create_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer created",
 "data": {
  "_id": "63f59467d68bfdeef6b3bfc3",
  "_model": "timer",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "name": "Timer 1",
  "speaker": "Thomas",
  "notes": "Very tall, remember to adjust camera angle",
  "labels": [
   {
    "name": "VT",
    "color": "#F44336"
   }
  ],
  "appearance": "COUNTDOWN",
  "type": "DURATION",
  "duration": "0:01:00",
  "hours": 0,
  "minutes": 1,
  "seconds": 30,
  "wrap_up_yellow": 60,
  "wrap_up_red": 15,
  "trigger": "MANUAL",
  "start_time": "2023-05-01T08:40:06.463Z",
  "start_time_uses_date": false,
  "finish_time": "2023-05-01T08:40:06.463Z",
  "finish_time_uses_date": false
 }
}

Timers

Update timer

GEThttps://api.stagetimer.io/v1/update_timer

Update a timer in the room. This is a partial update, only the parameters you provide will be changed.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
timer_id
Optional <string>
Example: 63f59467d68bfdeef6b3bfc3
ID of the timer to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
name
Optional <string>
Example: Timer 1
Default: Timer [n]
Name of the timer.
speaker
Optional <string>
Example: Thomas
Default: [blank]
Used to identify speakers.
notes
Optional <string>
Example: Very tall, remember to adjust camera angle
Default: [blank]
Notes related to the timer or speaker.
labels
Optional <array>
Example: [ { "name": "VT", "color": "#F44336" } ]
Default: []
Colored tags visible on the controller page. Can be provided using indexed notation in the URL query string.
Example usage: ?labels[0][name]=VT&labels[0][color]=%23F44336&labels[1][name]=Break&labels[1][color]=%234CAF50
This represents an array of two labels:
  1. Name: "VT", Color: "#F44336" (Red)
  2. Name: "Break", Color: "#4CAF50" (Green)

Note: The '#' in color codes must be URL-encoded as '%23'.
You can add as many labels as needed by incrementing the index and providing both 'name' and 'color' for each.
appearance
Optional <string>
Default: COUNTDOWN
Possible values: COUNTDOWN, COUNTUP, TOD, COUNTDOWN_TOD, COUNTUP_TOD, HIDDEN
Defines how the timer is displayed. Read more: Timer Appearances
type
Optional <string>
Default: DURATION
Possible values: DURATION, FINISH_TIME
Defines the type of timer, ie. how runtime length is handled. Read more: Timer Types
hours
Optional <integer>
Example: 0
Default: 0
Duration (hours).
minutes
Optional <integer>
Example: 1
Default: 10
Duration (minutes).
seconds
Optional <integer>
Example: 30
Default: 0
Duration (seconds).
wrap_up_yellow
Optional <integer>
Default: 60
Yellow wrap-up time (in seconds from the end).
wrap_up_red
Optional <integer>
Default: 15
Red wrap-up time (in seconds from the end).
trigger
Optional <string>
Default: MANUAL
Possible values: MANUAL, LINKED, SCHEDULED
Defines how the timer is triggered (started). Read more: Timer Triggers
start_time
Optional <string>
Example: 2023-05-01T08:40:06.463Z
Default: null
Set a hard start time for this cue. Required when trigger=SCHEDULED, but otherwise optional.
start_time_uses_date
Optional <boolean>
Default: false
Determines if the date-part of start_time is being used. If true, then the the full date is used (e.g. 11 am on Oct 6). But if false, the start date is interpreted as today and the date part ignored (e.g. 11 am today).
finish_time
Optional <string>
Example: 2023-05-01T08:40:06.463Z
Default: null
Finish time for the cue. Required when type=FINISH_TIME, otherwise ignored.
finish_time_uses_date
Optional <boolean>
Default: false
Determines if the date-part of finish_time is being used. If true, then the the full date is used (e.g. 11 am on Oct 6). But if false, the start date is interpreted as today and the date part ignored (e.g. 11 am today).
Request (example)
curl "https://api.stagetimer.io/v1/update_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer updated",
 "data": {
  "_id": "63f59467d68bfdeef6b3bfc3",
  "_model": "timer",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "name": "Timer 1",
  "speaker": "Thomas",
  "notes": "Very tall, remember to adjust camera angle",
  "labels": [
   {
    "name": "VT",
    "color": "#F44336"
   }
  ],
  "appearance": "COUNTDOWN",
  "type": "DURATION",
  "duration": "0:01:00",
  "hours": 0,
  "minutes": 1,
  "seconds": 30,
  "wrap_up_yellow": 60,
  "wrap_up_red": 15,
  "trigger": "MANUAL",
  "start_time": "2023-05-01T08:40:06.463Z",
  "start_time_uses_date": false,
  "finish_time": "2023-05-01T08:40:06.463Z",
  "finish_time_uses_date": false
 }
}

Timers

Delete timer

GEThttps://api.stagetimer.io/v1/delete_timer

Delete a timer in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
timer_id
Optional <string>
Example: 63f59467d68bfdeef6b3bfc3
ID of the timer to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/delete_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Timer deleted"
}

Messages

Show message

GEThttps://api.stagetimer.io/v1/show_message

Show a message in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
message_id
Optional <string>
Example: e5f46622be82fdaa44bba54c
ID of the message to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/show_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Message showing",
 "data": {
  "_id": "e5f46622be82fdaa44bba54c",
  "_model": "message",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "showing": false,
  "text": "Question for the speaker: [...]",
  "color": "white",
  "bold": false,
  "uppercase": false
 }
}

Messages

Hide message

GEThttps://api.stagetimer.io/v1/hide_message

Hide a message in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
message_id
Optional <string>
Example: e5f46622be82fdaa44bba54c
ID of the message to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/hide_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Message hidden",
 "data": {
  "_id": "e5f46622be82fdaa44bba54c",
  "_model": "message",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "showing": false,
  "text": "Question for the speaker: [...]",
  "color": "white",
  "bold": false,
  "uppercase": false
 }
}

Messages

Toggle message

GEThttps://api.stagetimer.io/v1/show_or_hide_message

Show OR hide a message in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
message_id
Optional <string>
Example: e5f46622be82fdaa44bba54c
ID of the message to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/show_or_hide_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Message hidden",
 "data": {
  "_id": "e5f46622be82fdaa44bba54c",
  "_model": "message",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "showing": false,
  "text": "Question for the speaker: [...]",
  "color": "white",
  "bold": false,
  "uppercase": false
 }
}

Messages

Get all messages

GEThttps://api.stagetimer.io/v1/get_all_messages

Get all messages in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
Request (example)
curl "https://api.stagetimer.io/v1/get_all_messages?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Messages loaded",
 "data": {
  "messages": [
   {
    "_id": "e5f46622be82fdaa44bba54c",
    "_model": "message",
    "_updated_at": "2023-05-01T08:40:06.463Z",
    "showing": false,
    "text": "Question for the speaker: [...]",
    "color": "white",
    "bold": false,
    "uppercase": false
   },
   "..."
  ]
 }
}

Messages

Get message

GEThttps://api.stagetimer.io/v1/get_message

Get a message in the room

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
message_id
Optional <string>
Example: e5f46622be82fdaa44bba54c
ID of the message to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/get_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Message loaded",
 "data": {
  "_id": "e5f46622be82fdaa44bba54c",
  "_model": "message",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "showing": false,
  "text": "Question for the speaker: [...]",
  "color": "white",
  "bold": false,
  "uppercase": false
 }
}

Messages

Create message

GEThttps://api.stagetimer.io/v1/create_message

Create a new message in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
text
Optional <string>
Example: Question for the speaker: [...]
Default: [blank]
Contents of the message.
color
Optional <string>
Default: white
Possible values: white, green, red
Color of the message text. Options: 'white', 'green', 'red'.
bold
Optional <boolean>
Default: false
Whether the message text is bold or not.
uppercase
Optional <boolean>
Default: false
Whether the message text is uppercase or not.
Request (example)
curl "https://api.stagetimer.io/v1/create_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Message created",
 "data": {
  "_id": "e5f46622be82fdaa44bba54c",
  "_model": "message",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "showing": false,
  "text": "Question for the speaker: [...]",
  "color": "white",
  "bold": false,
  "uppercase": false
 }
}

Messages

Update message

GEThttps://api.stagetimer.io/v1/update_message

Update a message in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
message_id
Optional <string>
Example: e5f46622be82fdaa44bba54c
ID of the message to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
text
Optional <string>
Example: Question for the speaker: [...]
Default: [blank]
Contents of the message.
color
Optional <string>
Default: white
Possible values: white, green, red
Color of the message text. Options: 'white', 'green', 'red'.
bold
Optional <boolean>
Default: false
Whether the message text is bold or not.
uppercase
Optional <boolean>
Default: false
Whether the message text is uppercase or not.
Request (example)
curl "https://api.stagetimer.io/v1/update_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Message updated",
 "data": {
  "_id": "e5f46622be82fdaa44bba54c",
  "_model": "message",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "showing": false,
  "text": "Question for the speaker: [...]",
  "color": "white",
  "bold": false,
  "uppercase": false
 }
}

Messages

Delete message

GEThttps://api.stagetimer.io/v1/delete_message

Delete a message in the room.

Query parameters:

room_id
Required <string>
Example: 6ADP4P5U
ID of the room you are targeting.
message_id
Optional <string>
Example: e5f46622be82fdaa44bba54c
ID of the message to target in the room.
index
Optional <integer>
Example: 2
Index of a timer or message to target in a room. Note: Index is not zero-based, it starts at 1. Example: To target the second timer from the top, set index=2
Request (example)
curl "https://api.stagetimer.io/v1/delete_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"
200 – Response (example)
{
 "ok": true,
 "message": "Message deleted"
}

Socket.io Endpoint

You can also connect to a socket.io endpoint using client libraries for various programming languages:

The socket.io endpoint receives real-time push messages from the server whenever there is a change in the room. These changes can be triggered by the controller page, the API, or the server itself. Note that the socket.io endpoint does not listen for any incoming messages.

The socket.io endpoint lives under the '/v1/socket.io' path. Please provide the 'auth' option when connecting. See code examples for details.

To test the socket, click "Connect" and then initiate an action in the room:

YOUR ROOM ID
YOUR API KEY
Socket.io Messages
# Click connect ...

Events

The server will send these events when the relevant data of a room changes.

Note: The server will send some initial data immediately after connecting a socket.

playback_status

For all time-related changes like start, stop, next, and previous.

playback_status
{
  "_model": "playback_status",
  "_updated_at": "2023-05-05T17:24:27.972Z",
  "timer_id": "63f59467d68bfdeef6b3bfc3",
  "running": true,
  "start": 1683307019129,
  "finish": 1683393418129,
  "pause": 1683304760524
}

room

For events affecting the room and viewer, like blackout and focus message.

room
{
  "_id": "EQY1FE7Q",
  "_model": "room",
  "_updated_at": "2023-05-05T17:24:27.972Z",
  "blackout": true,
  "focus_message": true,
  "logo": "https://stagetimer.io/assets/logo-dark.png"
}

message

When a message is shown or hidden. Or when an active message is updated.

message
{
  "_id": "638368e354cc641dcd3f1fe1",
  "_model": "message",
  "_updated_at": "2023-06-15T20:25:34.539Z",
  "showing": true,
  "text": "Wrap up!",
  "color": "red",
  "bold": false,
  "uppercase": false
}

current_timer

The currently highlighted timer. Emitted when a new timer is highlighted or on updates.

next_timer

The next timer after the currently highlighted. Emitted when a new timer is highlighted or on updates.

current_timer / next_timer
{
  "_id": "63f59467d68bfdeef6b3bfc3",
  "_model": "timer",
  "_updated_at": "2023-05-01T08:40:06.463Z",
  "name": "Timer 1",
  "speaker": "Thomas",
  "notes": "Very tall, remember to adjust camera angle",
  "appearance": "COUNTDOWN",
  "type": "DURATION",
  "duration": "0:01:00",
  "hours": 0,
  "minutes": 1,
  "seconds": 30,
  "wrap_up_yellow": 60,
  "wrap_up_red": 15,
  "trigger": "MANUAL",
  "start_time": "2023-05-01T08:40:06.463Z",
  "start_time_uses_date": false,
  "finish_time": "2023-05-01T08:40:06.463Z",
  "finish_time_uses_date": false
}

flash

When a manual flash is triggered. (Note that this event is not sent for scheduled flashing like when the timer hits 0:00).

flash
{ "count": 3 }

Code Examples

JavaScript (socket.io-client)
import { io } from "socket.io-client";

const socket = io('https://api.stagetimer.io', {
  path: '/v1/socket.io',
  auth: { room_id: 'YOUR_ROOM_ID', api_key: 'YOUR_API_KEY' },
});

socket.on('connect', () => { console.info('Connection Success') });
socket.on('connect_error', (error) => { console.error('Connection Error:', error); });
socket.onAny((event, payload) => { console.info(event, payload) });
Python (python-socketio)
import socketio

sio = socketio.Client()

@sio.event
def connect():
    print('Connected to Socket.io')

@sio.on('*')
def catch_all(event, data):
    print('Message received', event, data)

auth = { 'room_id': 'YOUR_ROOM_ID', 'api_key': 'YOUR_API_KEY' }
sio.connect('https://api.stagetimer.io', {}, auth, None, None, 'v1/socket.io')

Further Reading

Targeting Timers and Messages

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

Some endpoints require an index or unique id to target specific timers or messages. The index is a 1-based value pointing to a timer or message in the list on the controller page. For example, the first timer has index = 1, the second has index = 2, and so on. Use the "Get all timers" or "Get all messages" endpoints to get the id.

Understanding GET Requests and Query Parameters

A GET request is a common HTTP method used to request data from a server or API. When you access a website, your browser sends a GET request to the server hosting the website to fetch and display the content. In Stagetimer API, we use GET requests to interact with the timers.

Query parameters are key-value pairs appended to the URL, allowing you to provide additional data to the server. They start with a ? after the main URL, followed by the key-value pairs separated by &. For example:

Example
https://api.example.com/resource?key1=value1&key2=value2

In Stagetimer's API, you'll use query parameters to specify room IDs, API keys, indexes, and other relevant information. Here's an example of a GET request with query parameters for the Stagetimer API:

Example
curl -v "https://api.stagetimer.io/v1/start?room_id=6ADP4P5U&api_key=123456"

In this example, we're sending a GET request to start the timer in the specified room.

When using GET requests with query parameters, remember to URL-encode special characters to ensure proper handling by the server.