API Documentation
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.
curl "https://api.stagetimer.io/v1/test_auth?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"curl "https://api.stagetimer.io/v1/test_auth?room_id=YOUR_ROOM_ID" -H "Authorization: Bearer YOUR_API_KEY"
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.
curl "https://api.stagetimer.io/v1/"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/test_auth?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/get_status?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/get_room?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| limit | Optional <integer> Default: Min: Max: Limit the requested amount of log messages. |
| offset | Optional <integer> Default: Min: Max: Request log messages with this offset. Use this to paginate over the dataset. |
curl "https://api.stagetimer.io/v1/get_logs?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/start?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/stop?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/start_or_stop?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| autostart | Optional <boolean> Default: Set to |
curl "https://api.stagetimer.io/v1/next?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| autostart | Optional <boolean> Default: Set to |
curl "https://api.stagetimer.io/v1/previous?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| amount | Required <string> Example: An amount of time specified by a number followed by a divison of time. Eg. |
curl "https://api.stagetimer.io/v1/add_time?room_id=YOUR_ROOM_ID&amount=30s&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| amount | Required <string> Example: An amount of time specified by a number followed by a divison of time. Eg. |
curl "https://api.stagetimer.io/v1/subtract_time?room_id=YOUR_ROOM_ID&amount=30s&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| count | Optional <integer> Example: Default: Number of times to repeat the action. Accepted numbers: |
curl "https://api.stagetimer.io/v1/start_flashing?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/stop_flashing?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/enable_blackout?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/disable_blackout?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/toggle_blackout?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/enable_focus?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/disable_focus?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/toggle_focus?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| timer_id | Optional <string> Example: ID of the timer to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/start_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| timer_id | Optional <string> Example: ID of the timer to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/stop_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| timer_id | Optional <string> Example: ID of the timer to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/start_or_stop_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| timer_id | Optional <string> Example: ID of the timer to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/reset_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/get_all_timers?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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",
"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: ID of the room you are targeting. |
|---|---|
| timer_id | Optional <string> Example: ID of the timer to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/get_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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",
"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: ID of the room you are targeting. |
|---|---|
| name | Optional <string> Example: Default: Name of the timer. |
| speaker | Optional <string> Example: Default: Used to identify speakers. |
| notes | Optional <string> Example: Default: Notes related to the timer or speaker. |
| appearance | Optional <string> Default: Defines how the timer is displayed. Read more: Timer Appearances |
| type | Optional <string> Default: Defines the type of timer, ie. how runtime length is handled. Read more: Timer Types |
| hours | Optional <integer> Example: Default: Duration (hours). |
| minutes | Optional <integer> Example: Default: Duration (minutes). |
| seconds | Optional <integer> Example: Default: Duration (seconds). |
| wrap_up_yellow | Optional <integer> Default: Yellow wrap-up time (in seconds from the end). |
| wrap_up_red | Optional <integer> Default: Red wrap-up time (in seconds from the end). |
| trigger | Optional <string> Default: Defines how the timer is triggered (started). Read more: Timer Triggers |
| start_time | Optional <string> Example: Default: Set a hard start time for this cue. Required when |
| start_time_uses_date | Optional <boolean> Default: Determines if the date-part of |
| finish_time | Optional <string> Example: Default: Finish time for the cue. Required when |
| finish_time_uses_date | Optional <boolean> Default: Determines if the date-part of |
curl "https://api.stagetimer.io/v1/create_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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",
"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: ID of the room you are targeting. |
|---|---|
| timer_id | Optional <string> Example: ID of the timer to target in the room. |
| index | Optional <integer> Example: 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 |
| name | Optional <string> Example: Default: Name of the timer. |
| speaker | Optional <string> Example: Default: Used to identify speakers. |
| notes | Optional <string> Example: Default: Notes related to the timer or speaker. |
| appearance | Optional <string> Default: Defines how the timer is displayed. Read more: Timer Appearances |
| type | Optional <string> Default: Defines the type of timer, ie. how runtime length is handled. Read more: Timer Types |
| hours | Optional <integer> Example: Default: Duration (hours). |
| minutes | Optional <integer> Example: Default: Duration (minutes). |
| seconds | Optional <integer> Example: Default: Duration (seconds). |
| wrap_up_yellow | Optional <integer> Default: Yellow wrap-up time (in seconds from the end). |
| wrap_up_red | Optional <integer> Default: Red wrap-up time (in seconds from the end). |
| trigger | Optional <string> Default: Defines how the timer is triggered (started). Read more: Timer Triggers |
| start_time | Optional <string> Example: Default: Set a hard start time for this cue. Required when |
| start_time_uses_date | Optional <boolean> Default: Determines if the date-part of |
| finish_time | Optional <string> Example: Default: Finish time for the cue. Required when |
| finish_time_uses_date | Optional <boolean> Default: Determines if the date-part of |
curl "https://api.stagetimer.io/v1/update_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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",
"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: ID of the room you are targeting. |
|---|---|
| timer_id | Optional <string> Example: ID of the timer to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/delete_timer?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| message_id | Optional <string> Example: ID of the message to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/show_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| message_id | Optional <string> Example: ID of the message to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/hide_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| message_id | Optional <string> Example: ID of the message to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/show_or_hide_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|
curl "https://api.stagetimer.io/v1/get_all_messages?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| message_id | Optional <string> Example: ID of the message to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/get_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| text | Optional <string> Example: Default: Contents of the message. |
| color | Optional <string> Default: Color of the message text. Options: |
| bold | Optional <boolean> Default: Whether the message text is bold or not. |
| uppercase | Optional <boolean> Default: Whether the message text is uppercase or not. |
curl "https://api.stagetimer.io/v1/create_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| message_id | Optional <string> Example: ID of the message to target in the room. |
| index | Optional <integer> Example: 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 |
| text | Optional <string> Example: Default: Contents of the message. |
| color | Optional <string> Default: Color of the message text. Options: |
| bold | Optional <boolean> Default: Whether the message text is bold or not. |
| uppercase | Optional <boolean> Default: Whether the message text is uppercase or not. |
curl "https://api.stagetimer.io/v1/update_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"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: ID of the room you are targeting. |
|---|---|
| message_id | Optional <string> Example: ID of the message to target in the room. |
| index | Optional <integer> Example: 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 |
curl "https://api.stagetimer.io/v1/delete_message?room_id=YOUR_ROOM_ID&api_key=YOUR_API_KEY"{
"ok": true,
"message": "Message deleted"
}Socket.io Endpoint
You can also connect to a socket.io endpoint using client libraries for various programming languages:
- JavaScript: socket.io-client on npm
- Python: python-socketio on Read the Docs
- Java: socket.io-client-java on GitHub
- Go: go-socket.io-client on GoDoc
- Rust: rust-socketio on GitHub
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:
# Click connect ...Events
The server will send the following events:
playback_status – For all time-related changes like start, stop, next, and previous.
{ "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.
{ "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.
{"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).
{ "count": 3 }Code Examples
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) });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
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:
https://api.example.com/resource?key1=value1&key2=value2In 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:
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.