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 offline version.

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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 highlighted timer in the room

Query parameters

room_id

Required <string>

Example: 6ADP4P5U

Unique identifier for a room

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

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

Unique identifier for a room

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 highlighted and started at `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 highlighted timer in the room 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

Unique identifier for a room

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 highlighted, set 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
 }
}

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

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

Unique identifier for a room

timer_id

Optional <string>

Example: 63f59467d68bfdeef6b3bfc3

Unique identifier for a timer. (Auto-generated)

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

Unique identifier for a room

timer_id

Optional <string>

Example: 63f59467d68bfdeef6b3bfc3

Unique identifier for a timer. (Auto-generated)

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

Unique identifier for a room

timer_id

Optional <string>

Example: 63f59467d68bfdeef6b3bfc3

Unique identifier for a timer. (Auto-generated)

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

Unique identifier for a room

timer_id

Optional <string>

Example: 63f59467d68bfdeef6b3bfc3

Unique identifier for a timer. (Auto-generated)

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

Unique identifier for a room

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",
   "duration": "0:01:00",
   "hours": 0,
   "minutes": 1,
   "seconds": 30,
   "wrap_up_yellow": 60,
   "wrap_up_red": 15,
   "start_time": "2023-05-01T08:40:06.463Z",
   "finish_time": "2023-05-01T08:40:06.463Z"
  },
  "..."
 ]
}

Timers

Get timer

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

Get a timer in the room

Query parameters

room_id

Required <string>

Example: 6ADP4P5U

Unique identifier for a room

timer_id

Optional <string>

Example: 63f59467d68bfdeef6b3bfc3

Unique identifier for a timer. (Auto-generated)

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",
  "duration": "0:01:00",
  "hours": 0,
  "minutes": 1,
  "seconds": 30,
  "wrap_up_yellow": 60,
  "wrap_up_red": 15,
  "start_time": "2023-05-01T08:40:06.463Z",
  "finish_time": "2023-05-01T08:40:06.463Z"
 }
}

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

Unique identifier for a room

name

Optional <string>

Example: Timer 1

Default: Timer <N>

Name of the timer.

speaker

Optional <string>

Example: Thomas

Default: <empty>

Used to identify speakers.

notes

Optional <string>

Example: Very tall, remember to adjust camera angle

Default: <empty>

Notes related to the timer or speaker.

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

yellow

Optional <integer>

Default: 60

Yellow wrap-up time (in seconds from the end).

red

Optional <integer>

Default: 15

Red wrap-up time (in seconds from the end).

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",
  "duration": "0:01:00",
  "hours": 0,
  "minutes": 1,
  "seconds": 30,
  "wrap_up_yellow": 60,
  "wrap_up_red": 15,
  "start_time": "2023-05-01T08:40:06.463Z",
  "finish_time": "2023-05-01T08:40:06.463Z"
 }
}

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

Unique identifier for a room

timer_id

Optional <string>

Example: 63f59467d68bfdeef6b3bfc3

Unique identifier for a timer. (Auto-generated)

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

Used to identify speakers.

notes

Optional <string>

Example: Very tall, remember to adjust camera angle

Default: <empty>

Notes related to the timer or speaker.

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

yellow

Optional <integer>

Default: 60

Yellow wrap-up time (in seconds from the end).

red

Optional <integer>

Default: 15

Red wrap-up time (in seconds from the end).

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",
  "duration": "0:01:00",
  "hours": 0,
  "minutes": 1,
  "seconds": 30,
  "wrap_up_yellow": 60,
  "wrap_up_red": 15,
  "start_time": "2023-05-01T08:40:06.463Z",
  "finish_time": "2023-05-01T08:40:06.463Z"
 }
}

Timers

Delete timer

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

Delete a timer in the room.

Query parameters

room_id

Required <string>

Example: 6ADP4P5U

Unique identifier for a room

timer_id

Optional <string>

Example: 63f59467d68bfdeef6b3bfc3

Unique identifier for a timer. (Auto-generated)

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

Unique identifier for a room

message_id

Optional <string>

Example: e5f46622be82fdaa44bba54c

Unique identifier for a message. (Auto-generated)

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

Unique identifier for a room

message_id

Optional <string>

Example: e5f46622be82fdaa44bba54c

Unique identifier for a message. (Auto-generated)

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

Unique identifier for a room

message_id

Optional <string>

Example: e5f46622be82fdaa44bba54c

Unique identifier for a message. (Auto-generated)

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

Unique identifier for a room

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": {
  "timers": [
   {
    "_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

Unique identifier for a room

message_id

Optional <string>

Example: e5f46622be82fdaa44bba54c

Unique identifier for a message. (Auto-generated)

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

Unique identifier for a room

text

Optional <string>

Example: Question for the speaker: [...]

Default: <empty>

Contents of the message.

color

Optional <string>

Default: white

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

Unique identifier for a room

message_id

Optional <string>

Example: e5f46622be82fdaa44bba54c

Unique identifier for a message. (Auto-generated)

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

Contents of the message.

color

Optional <string>

Default: white

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

Unique identifier for a room

message_id

Optional <string>

Example: e5f46622be82fdaa44bba54c

Unique identifier for a message. (Auto-generated)

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 '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 the following events:

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

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

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

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

message – When a message is shown or hidden.

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

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/v1', {
  path: 'socket.io',
  auth: { room_id: 'YOUR_ROOM_ID', api_key: 'YOUR_API_KEY' },
})

socket.on('connect', () => { console.info('connected') });
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.