API Documentation

Remotely control your timers, sessions, and messages using simple HTTP requests. Built for hardware controllers, streaming software, and custom automation scripts.

Introduction

The Tevyr API is an RPC-style API over HTTP that lets you programmatically control your event timers. It's designed for maximum compatibility with tools like Bitfocus Companion, vMix, OBS, and any system that can trigger a URL.

Key design choices:

All endpoints use GET requests — even mutations — so hardware controllers that can only "trigger a URL" work out of the box
Most endpoints interact with the currently active session in your room
Responses are JSON with timestamps, so your integration can compute remaining time locally without constant polling

The API is available on Premium and Enterprise plans. Compare plans to see all features.

How to use this API

If you're new to APIs, don't worry — it's simpler than it looks. An API (Application Programming Interface) allows two programs to communicate. For example, you can use this API with Bitfocus Companion to trigger timer actions from a Stream Deck button.

This documentation uses curl in the code examples. curl is a command-line tool that comes pre-installed on most systems — you can copy-paste examples directly into your terminal to try them out.

Mac: Open Terminal
Windows: Open Command Prompt

If you're completely new to APIs, read the How GET Requests Work and How Targeting Works guides at the end of this page.

Authentication

Every API request (except the connection test) requires a Room API Key. Each key is scoped to a single room and expires after 30 days.

Generate your API key:

Open the Controller for your event
Click the event menu (top-left dropdown)
Select API
Click Generate API Key
Copy the key immediately — it won't be shown again

You can also generate and manage keys from the Dashboard under the API Keys section.

Two ways to authenticate:

Query parameter

The simplest method — append your key to the URL. Best for hardware controllers that can only trigger a URL.

Query parameter

curl "https://api.tevyr.com/v1/users/auth_check?room_id=433019&api_key=YOUR_API_KEY"

Bearer token

More secure — send the key in the HTTP header. Best for scripts and applications.

Bearer token

curl "https://api.tevyr.com/v1/users/auth_check?room_id=433019" \
  -H "Authorization: Bearer YOUR_API_KEY"

Both methods work identically. Use query parameters for hardware controllers (simpler), and Bearer tokens for scripts and applications (more secure).

Getting Started

Follow these steps to make your first API call:

Step 1: Find your Room ID

Your Room ID is the 6-digit passcode shown at the top of the controller page (e.g., 433019). You can also find it in the API modal under "Room ID."

Step 2: Generate an API key

Open the controller, go to the event menu, and click API. Click Generate API Key and copy it.

Step 3: Test the connection

Verify the API is reachable (no authentication needed).

Request

curl "https://api.tevyr.com/v1/"

200 – Response

{
  "ok": true,
  "message": "Welcome to the Tevyr API. Use your API key to control timers, sessions, and messages programmatically.",
  "data": {
    "docs": "https://tevyr.com/docs/api"
  }
}

Step 4: Test authorization

Verify your API key works for the specified room.

Request

curl "https://api.tevyr.com/v1/users/auth_check?room_id=433019&api_key=YOUR_API_KEY"

200 – Response

{
  "ok": true,
  "message": "You are authorized to use Tevyr's APIs for the event: 433019. Valid API key."
}

Cookbook

Copy-paste recipes for the most-common cues. Replace 433019 with your Room ID and YOUR_API_KEY with the key you generated. Every URL works as-is in QLab Network Cues, vMix shortcuts, Companion HTTP buttons, browsers, and any other tool that can fire a URL.

Play next session in the rundown

Advance to the next session and start its timer. The single most-used cue — call this on every cue-go from your control surface.

Request

curl "https://api.tevyr.com/v1/timer/next?room_id=433019&api_key=YOUR_API_KEY&autostart=true"

Toggle the timer (start or pause)

One endpoint that starts the timer if paused and pauses if running. Bind to a single button — your operator never has to know which state it's in.

Request

curl "https://api.tevyr.com/v1/timer/start_stop?room_id=433019&api_key=YOUR_API_KEY"

Reset the current timer

Snap the current session's timer back to its starting duration. Useful when a speaker restarts or you want a clean re-run.

Request

curl "https://api.tevyr.com/v1/timer/reset?room_id=433019&api_key=YOUR_API_KEY"

Add 30 seconds to the running timer

Extend the current session on the fly without stopping the clock. Mirror this with /v1/timer/subtract_time on a second button to trim time when the speaker is over.

Request

curl "https://api.tevyr.com/v1/timer/add_time?room_id=433019&api_key=YOUR_API_KEY&amount=30s"

Send a flash message to all screens

Pulse a message across every screen — useful for "Wrap up", "Time check", or any urgent prompt to the speaker. Auto-clears after 12 pulses (~4 seconds).

Request

curl "https://api.tevyr.com/v1/message/flash?room_id=433019&api_key=YOUR_API_KEY"

Push a one-shot message to the speaker screen

Create a brand-new message and immediately show it. Ideal for ad-hoc prompts — "You're on mute", "Q&A in 2 minutes", etc. The first call creates, the second shows it on the speaker screen only.

Step 1 — create the message

curl "https://api.tevyr.com/v1/message/create?room_id=433019&api_key=YOUR_API_KEY&text=You+are+on+mute&color=red&bold=true"

Step 2 — show it (id from step 1 response)

curl "https://api.tevyr.com/v1/message/show?room_id=433019&api_key=YOUR_API_KEY&id=MESSAGE_ID&screen_selections=speaker"

Trigger a panic blackout on every screen

Black every Tevyr screen instantly. Pair with a clearly-labelled red button — when something on stage goes wrong, one tap kills every output. The companion call /v1/display/disable_blackout brings them back.

Request

curl "https://api.tevyr.com/v1/display/enable_blackout?room_id=433019&api_key=YOUR_API_KEY"

Toggle the ON-AIR light when recording starts

Drive a Tevyr ON-AIR indicator from your stream/recording start cue so the talent always knows when the room is hot. Pair the disable call to a stop-recording cue.

Enable

curl "https://api.tevyr.com/v1/display/enable_on_air?room_id=433019&api_key=YOUR_API_KEY"

Disable

curl "https://api.tevyr.com/v1/display/disable_on_air?room_id=433019&api_key=YOUR_API_KEY"

Read the current timer state (no mutation)

Poll once per second from your custom display to compute remaining time locally. The response includes the active session, duration, and the precise started_at timestamp — no need to hammer the timer endpoints.

Request

curl "https://api.tevyr.com/v1/event/playback_status?room_id=433019&api_key=YOUR_API_KEY"

Jump to a specific session by ID

Skip directly to a named session — useful for "Go to Q&A" or "Cut to break" buttons. Use /v1/session/get_all once to find IDs, then bind one button per destination.

Request

curl "https://api.tevyr.com/v1/session/start?room_id=433019&api_key=YOUR_API_KEY&id=SESSION_ID"

Need something not in the cookbook? Browse the full endpoint reference below — there are 60+ endpoints covering every action available in the controller. For end-to-end integration walk-throughs, see the Integrations guides.

HTTP Endpoints

All endpoints return JSON. Successful responses have "ok": true. Error responses have "ok": false with an "error" message and machine-readable "code".

Rate Limits

API requests are rate-limited per room:

Plan	Limit
Premium	60 requests/minute
Enterprise	300 requests/minute

Rate limit headers are included in every response:

Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1713176460

General

#Test API connection

GET/v1/

Verify that the API is reachable. Use this to confirm your base URL is correct.

Authentication: Not required

Query parameters: None

Request (example)

curl "https://api.tevyr.com/v1/"

200 – Response (example)

{
  "ok": true,
  "message": "Welcome to the Tevyr API. Use your API key to control timers, sessions, and messages programmatically.",
  "data": {
    "docs": "https://tevyr.com/docs/api"
  }
}

#Test API authorization

GET/v1/users/auth_check

Verify that your API key is valid and authorized for the specified room.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room (e.g., 433019)

api_keyRequiredstring

Your Room API key

Request (example)

curl "https://api.tevyr.com/v1/users/auth_check?room_id=433019&api_key=YOUR_API_KEY"

200 – Response (example)

{
  "ok": true,
  "message": "You are authorized to use Tevyr's APIs for the event: 433019. Valid API key."
}

Event

#Get playback status

GET/v1/event/playback_status

Get the current playback state of the active session and any running ad-hoc timers. Returns timestamps so your integration can compute the remaining time locally.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Computing remaining time

The response returns timestamps in milliseconds since the Unix epoch. Your code must compute the remaining time locally:

When running is true: remaining = finish - Date.now()
When running is false (paused): remaining = finish - pause
Total duration: finish - start

This approach ensures your display stays accurate between polling intervals — even if you poll every 5 seconds, the computed remaining is precise to the millisecond.

Ad-hoc timers

If ad-hoc (on-spot) timers are active, they appear in the adhoc_timers array with the same timestamp format. Only running or paused ad-hoc timers are included. Pending and completed timers are excluded.

Request (example)

curl "https://api.tevyr.com/v1/event/playback_status?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Playback status loaded",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-17T10:00:00.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Opening Keynote",
    "running": true,
    "start": 1713261600000,
    "finish": 1713261780000,
    "pause": null,
    "remaining_seconds": 142,
    "server_time": 1713261638000,
    "adhoc_active": false,
    "adhoc_timers": []
  }
}

#Get event state

GET/v1/event/state

Get the current state of the event including active effects, room settings, and session progress.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Effects

Per-screen effects (blackout, focus, on_air, timer_flash, message_flash, questions_qr) return an object with speaker, audience, staff booleans. Global effects (disco, panic, green, red) are single booleans that apply to all screens.

Sessions

total and completed are counts. active_index is the order index of the currently active session, or null if no session is active.

Request (example)

curl "https://api.tevyr.com/v1/event/state?room_id=433019&api_key=YOUR_API_KEY"

200 – Response (example)

{
  "ok": true,
  "message": "Room loaded",
  "data": {
    "_model": "event_state",
    "_updated_at": "2026-04-17T10:00:00.000Z",
    "room_id": "433019",
    "title": "Main Stage",
    "timezone": "America/New_York",
    "sessions": {
      "total": 8,
      "completed": 3,
      "active_index": 4
    },
    "effects": {
      "blackout": {
        "speaker": false,
        "audience": false,
        "staff": false
      },
      "focus": {
        "speaker": true,
        "audience": true,
        "staff": true
      },
      "on_air": {
        "speaker": false,
        "audience": false,
        "staff": false
      },
      "timer_flash": {
        "speaker": false,
        "audience": false,
        "staff": false
      },
      "message_flash": {
        "speaker": false,
        "audience": false,
        "staff": false
      },
      "questions_qr": {
        "speaker": false,
        "audience": false,
        "staff": false
      },
      "disco": false,
      "panic": false,
      "green": false,
      "red": false
    },
    "settings": {
      "overtime_behavior": "stop",
      "overtime_prefix": "plus",
      "countdown_format": "auto",
      "time_of_day_format": "browser",
      "auto_play_enabled": false
    }
  }
}

#Get activity logs

GET/v1/event/activity_logs

Get human-readable activity logs for the room with pagination. Logs include timer actions, session changes, display effects, messages, and connection events.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

limitinteger

Number of log entries to return. Default: 20, Min: 1, Max: 200

offsetinteger

Offset for pagination. Default: 0. Use this to paginate through the dataset.

Request (example)

curl "https://api.tevyr.com/v1/event/activity_logs?room_id=433019&api_key=YOUR_API_KEY&limit=5"

{
  "ok": true,
  "message": "Logs loaded",
  "data": [
    "2026-04-19T16:42:23.996Z | Master · user@email.com | Session Updated: title → \"Opening Keynote\", duration → 30:00",
    "2026-04-19T16:40:12.000Z | Master · user@email.com | Timer Started at 29:45",
    "2026-04-19T16:39:50.000Z | System | Session Started: Warmup",
    "2026-04-19T16:35:00.000Z | Web Control · user@email.com | Blackout ON (speaker)",
    "2026-04-19T16:30:00.000Z | System | Controller Connected"
  ]
}

Timer Controls

#Start timer

GET/v1/timer/start

Start or resume the timer for the currently active (highlighted) session in the room. If the timer is already running, this returns success without changing anything (idempotent).

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

How it works

Starts the timer for the currently highlighted session (the blue session in the controller)
All connected screens (speaker, audience, staff) and controllers update instantly via WebSocket
The timer state is persisted to the database — refreshing any screen will show the running timer
If the timer is already running, returns the current state without restarting

Request (example)

curl "https://api.tevyr.com/v1/timer/start?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Timer started at 9:56",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-20T12:00:00.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Opening Keynote",
    "running": true,
    "start": 1776686400000,
    "finish": 1776687060000,
    "pause": null,
    "remaining_seconds": 596,
    "server_time": 1776686400000
  }
}

#Stop timer

GET/v1/timer/stop

Stop (pause) the timer for the currently active session. The remaining time is preserved — calling /v1/timer/start again will resume from where it stopped. If the timer is already stopped, this returns success without changing anything (idempotent).

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request (example)

curl "https://api.tevyr.com/v1/timer/stop?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Timer stopped at 0:05:30",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-20T12:05:30.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Opening Keynote",
    "running": false,
    "start": 1776686400000,
    "finish": 1776687060000,
    "pause": 1776686730000,
    "remaining_seconds": 330,
    "server_time": 1776686730000
  }
}

#Toggle timer

GET/v1/timer/start_stop

Start or stop the timer based on its current state. If the timer is running, it will be stopped. If it is stopped, it will be started. This is useful for hardware controllers with a single toggle button.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request (example)

curl "https://api.tevyr.com/v1/timer/start_stop?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Timer started at 0:09:56",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-21T08:00:00.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Opening Keynote",
    "running": true,
    "start": 1776686400000,
    "finish": 1776687060000,
    "pause": null,
    "remaining_seconds": 596,
    "server_time": 1776686400000
  }
}

#Reset timer

GET/v1/timer/reset

Reset the timer to the full session duration. The timer will be paused after reset. Use the autostart parameter to automatically start the timer after resetting.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

autostartboolean

Set to true to automatically start the timer after reset. Default: false

Request (example)

curl "https://api.tevyr.com/v1/timer/reset?room_id=433019&api_key=YOUR_API_KEY"

# With autostart
curl "https://api.tevyr.com/v1/timer/reset?room_id=433019&api_key=YOUR_API_KEY&autostart=true"

{
  "ok": true,
  "message": "Timer reset at 0:03:00",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-21T08:00:00.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Opening Keynote",
    "running": false,
    "start": 1776686400000,
    "finish": 1776686580000,
    "pause": 1776686400000,
    "remaining_seconds": 180,
    "server_time": 1776686400000
  }
}

#Next session

GET/v1/timer/next

Advance to the next session in the list. The current session is reset to pending and the next session is activated with the timer paused. Use the autostart parameter to automatically start the timer after switching.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

autostartboolean

Set to true to automatically start the timer after switching. Default: false

Request (example)

curl "https://api.tevyr.com/v1/timer/next?room_id=433019&api_key=YOUR_API_KEY"

# With autostart
curl "https://api.tevyr.com/v1/timer/next?room_id=433019&api_key=YOUR_API_KEY&autostart=true"

{
  "ok": true,
  "message": "Next timer _Round 1_ selected (`0:03:00`)",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-21T08:00:00.000Z",
    "session_id": "f221ef2f-2b49-4ab0-b83f-66b7833c4c6b",
    "session_name": "Round 1",
    "running": false,
    "start": 1776686400000,
    "finish": 1776686580000,
    "pause": 1776686400000,
    "remaining_seconds": 180,
    "server_time": 1776686400000
  }
}

#Previous session

GET/v1/timer/prev

Go back to the previous session in the list. The current session is reset to pending and the previous session is activated with the timer paused. Use the autostart parameter to automatically start the timer after switching.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

autostartboolean

Set to true to automatically start the timer after switching. Default: false

Request (example)

curl "https://api.tevyr.com/v1/timer/prev?room_id=433019&api_key=YOUR_API_KEY"

# With autostart
curl "https://api.tevyr.com/v1/timer/prev?room_id=433019&api_key=YOUR_API_KEY&autostart=true"

{
  "ok": true,
  "message": "Previous timer _Warmup_ selected (`0:11:00`)",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-21T08:00:00.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Warmup",
    "running": false,
    "start": 1776686400000,
    "finish": 1776687060000,
    "pause": 1776686400000,
    "remaining_seconds": 660,
    "server_time": 1776686400000
  }
}

#Add time

GET/v1/timer/add_time

Add time to the current timer. Use either amount (time shorthand like "30s", "5m") or milliseconds (exact value). Defaults to 1 minute if neither is provided. Maximum adjustment is 24 hours. Cannot be used on target-time sessions or during overtime.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

amountstring

Time to add: number + unit (s/m/h). E.g. 30s, 5m, 1h. Max 24h

millisecondsinteger

Time to add in milliseconds. E.g. 30000. Max 86400000. Default: 60000 (1 min)

Request (example)

curl "https://api.tevyr.com/v1/timer/add_time?room_id=433019&api_key=YOUR_API_KEY&amount=30s"

# Using milliseconds
curl "https://api.tevyr.com/v1/timer/add_time?room_id=433019&api_key=YOUR_API_KEY&milliseconds=30000"

{
  "ok": true,
  "message": "Added 30s to timer. New countdown: `0:01:30`",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-21T08:00:00.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Opening Keynote",
    "running": true,
    "start": 1776686400000,
    "finish": 1776686490000,
    "pause": null,
    "remaining_seconds": 90,
    "server_time": 1776686400000
  }
}

#Subtract time

GET/v1/timer/subtract_time

Subtract time from the current timer. Use either amount (time shorthand like "30s", "5m") or milliseconds (exact value). Defaults to 1 minute if neither is provided. Maximum adjustment is 24 hours. Remaining time is clamped to zero. Cannot be used on target-time sessions or during overtime.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

amountstring

Time to subtract: number + unit (s/m/h). E.g. 30s, 5m, 1h. Max 24h

millisecondsinteger

Time to subtract in milliseconds. E.g. 30000. Max 86400000. Default: 60000 (1 min)

Request (example)

curl "https://api.tevyr.com/v1/timer/subtract_time?room_id=433019&api_key=YOUR_API_KEY&amount=1m"

# Using milliseconds
curl "https://api.tevyr.com/v1/timer/subtract_time?room_id=433019&api_key=YOUR_API_KEY&milliseconds=60000"

{
  "ok": true,
  "message": "Subtracted 1m from timer. New countdown: `0:02:00`",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-21T08:00:00.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Opening Keynote",
    "running": true,
    "start": 1776686400000,
    "finish": 1776686520000,
    "pause": null,
    "remaining_seconds": 120,
    "server_time": 1776686400000
  }
}

#Scrub playhead

GET/v1/timer/scrub_playhead

Jump the playhead forward or backward by a specified number of milliseconds. Positive values jump forward (less remaining time), negative values jump backward (more remaining time). Cannot jump beyond the start position or below zero. Duration stays unchanged. Maximum jump is 24 hours.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

millisecondsRequiredinteger

Jump offset in ms. Positive = forward, negative = backward. Max ±86400000

Request (example)

# Jump forward 30 seconds
curl "https://api.tevyr.com/v1/timer/scrub_playhead?room_id=433019&api_key=YOUR_API_KEY&milliseconds=30000"

# Jump backward 1 minute
curl "https://api.tevyr.com/v1/timer/scrub_playhead?room_id=433019&api_key=YOUR_API_KEY&milliseconds=-60000"

{
  "ok": true,
  "message": "Jumped forward 30s. New countdown: `0:01:30`",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-21T08:00:00.000Z",
    "session_id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
    "session_name": "Opening Keynote",
    "running": true,
    "start": 1776686400000,
    "finish": 1776686490000,
    "pause": null,
    "remaining_seconds": 90,
    "server_time": 1776686400000
  }
}

Ad-Hoc Timers

Control ad-hoc (on-spot) timers that run independently alongside session timers. Target a specific timer by timer_id or index (1-based position in the list). At least one is required. Note: Index is 1-based — index=1 targets the first timer, index=2 the second, and so on.

#Start ad-hoc timer

GET/v1/adhoc/start

Start an ad-hoc timer. Optionally set the display mode and target screens.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the ad-hoc timer. Either timer_id or index is required

indexinteger

1-based position in the timer list (1 = first timer, 2 = second, etc.). Either timer_id or index is required

screen_modestring

Display mode: "override" (full screen) or "split" (side-by-side). Default: keeps current value (new timers default to "override")

screen_selectionsstring

Comma-separated target screens: speaker,audience,staff. Default: keeps current value (new timers default to "audience")

Request (example)

# By index (first timer)
curl "https://api.tevyr.com/v1/adhoc/start?room_id=433019&api_key=YOUR_API_KEY&index=1"

# By timer_id with screen options
curl "https://api.tevyr.com/v1/adhoc/start?room_id=433019&api_key=YOUR_API_KEY&timer_id=abc123&screen_mode=split&screen_selections=speaker,audience"

{
  "ok": true,
  "message": "Ad-hoc timer _Setup_ started",
  "data": {
    "_model": "adhoc_timer_status",
    "adhoc_id": "abc123-def456",
    "adhoc_name": "Setup",
    "running": true,
    "remaining_seconds": 120,
    "duration_seconds": 300,
    "display_mode": "split",
    "target_screens": ["speaker", "audience"],
    "server_time": 1776686400000
  }
}

#Reset ad-hoc timer

GET/v1/adhoc/reset

Reset an ad-hoc timer to its full duration. The timer will be paused after reset. Use autostart to automatically start the timer after resetting.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the ad-hoc timer. Either timer_id or index is required

indexinteger

1-based position in the timer list (1 = first timer, 2 = second, etc.). Either timer_id or index is required

autostartboolean

Set to true to automatically start the timer after reset. Default: false

Request (example)

# Reset timer 1
curl "https://api.tevyr.com/v1/adhoc/reset?room_id=433019&api_key=YOUR_API_KEY&index=1"

# Reset + autostart
curl "https://api.tevyr.com/v1/adhoc/reset?room_id=433019&api_key=YOUR_API_KEY&index=1&autostart=true"

{
  "ok": true,
  "message": "Ad-hoc timer _Timer 1_ reset at 0:10:00",
  "data": {
    "_model": "adhoc_timer_status",
    "adhoc_id": "abc123-def456",
    "adhoc_name": "Timer 1",
    "running": false,
    "remaining_seconds": 600,
    "duration_seconds": 600,
    "display_mode": "override",
    "target_screens": ["speaker", "audience"],
    "server_time": 1776686400000
  }
}

#Toggle ad-hoc timer

GET/v1/adhoc/start_stop

Toggle an ad-hoc timer between playing and paused. If paused, starts the timer (screen options applied). If running, stops the timer (screen options ignored).

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the ad-hoc timer. Either timer_id or index is required

indexinteger

1-based position in the timer list (1 = first timer, 2 = second, etc.). Either timer_id or index is required

screen_modestring

Display mode: "override" or "split". Only applied when starting. Default: keeps current

screen_selectionsstring

Comma-separated target screens: speaker,audience,staff. Only applied when starting. Default: keeps current

Request (example)

curl "https://api.tevyr.com/v1/adhoc/start_stop?room_id=433019&api_key=YOUR_API_KEY&index=1"

{
  "ok": true,
  "message": "Ad-hoc timer _Setup_ started",
  "data": {
    "_model": "adhoc_timer_status",
    "adhoc_id": "abc123-def456",
    "adhoc_name": "Setup",
    "running": true,
    "remaining_seconds": 120,
    "duration_seconds": 300,
    "display_mode": "override",
    "target_screens": ["speaker", "audience"],
    "server_time": 1776686400000
  }
}

#Stop ad-hoc timer

GET/v1/adhoc/stop

Pause an ad-hoc timer. The remaining time is preserved.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the ad-hoc timer. Either timer_id or index is required

indexinteger

1-based position in the timer list (1 = first timer, 2 = second, etc.). Either timer_id or index is required

Request (example)

# By index
curl "https://api.tevyr.com/v1/adhoc/stop?room_id=433019&api_key=YOUR_API_KEY&index=1"

# By timer_id
curl "https://api.tevyr.com/v1/adhoc/stop?room_id=433019&api_key=YOUR_API_KEY&timer_id=abc123"

{
  "ok": true,
  "message": "Ad-hoc timer _Setup_ stopped",
  "data": {
    "_model": "adhoc_timer_status",
    "adhoc_id": "abc123-def456",
    "adhoc_name": "Setup",
    "running": false,
    "remaining_seconds": 85,
    "duration_seconds": 300,
    "display_mode": "override",
    "target_screens": ["speaker", "audience", "staff"],
    "server_time": 1776686400000
  }
}

#Toggle ad-hoc screens

GET/v1/adhoc/screen_toggle

Change the display mode and/or target screens for an ad-hoc timer without affecting its play/pause state. The timer keeps running or stays paused.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the ad-hoc timer. Either timer_id or index is required

indexinteger

1-based position in the timer list (1 = first timer, 2 = second, etc.). Either timer_id or index is required

screen_modestring

Display mode: "override" (full screen) or "split" (side-by-side)

screen_selectionsstring

Comma-separated target screens: speaker,audience,staff

Request (example)

# Change to split mode on speaker + audience
curl "https://api.tevyr.com/v1/adhoc/screen_toggle?room_id=433019&api_key=YOUR_API_KEY&index=1&screen_mode=split&screen_selections=speaker,audience"

# Change screens only (keep current mode)
curl "https://api.tevyr.com/v1/adhoc/screen_toggle?room_id=433019&api_key=YOUR_API_KEY&timer_id=abc123&screen_selections=staff"

{
  "ok": true,
  "message": "Ad-hoc timer _Setup_ screens updated",
  "data": {
    "_model": "adhoc_timer_status",
    "adhoc_id": "abc123-def456",
    "adhoc_name": "Setup",
    "running": true,
    "remaining_seconds": 120,
    "duration_seconds": 300,
    "display_mode": "split",
    "target_screens": ["speaker", "audience"],
    "server_time": 1776686400000
  }
}

#Create ad-hoc timer

GET/v1/adhoc/create_adhoc

Create a new ad-hoc 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. Subject to plan limits.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

namestring

Timer name. Default: "Timer [n]"

speakerstring

Speaker name. Default: blank

notesstring

Notes for the timer. Default: blank

labelsarray

Indexed notation: labels[0][name]=VT&labels[0][color]=%23F44336

appearancestring

Display type: countdown, countup, tod, countdown_tod, countup_tod. Default: countdown

typestring

Timer type: duration, target_time, time_warp. Default: duration

hoursinteger

Duration hours. Default: 0

minutesinteger

Duration minutes. Default: 10

secondsinteger

Duration seconds. Default: 0

wrap_up_yellowinteger

Warning threshold in seconds. Default: 60

wrap_up_redinteger

Critical threshold in seconds. Default: 15

triggerstring

Start mode: manual, linked, scheduled. Default: manual

start_timestring

ISO datetime for scheduled start. Required when trigger=scheduled

finish_timestring

ISO datetime for target finish. Required when type=target_time

screen_modestring

Display mode: override or split. Default: override

screen_selectionsstring

Comma-separated screens: speaker,audience,staff. Default: audience

Request (example)

# Create with defaults (10 min countdown)
curl "https://api.tevyr.com/v1/adhoc/create_adhoc?room_id=433019&api_key=YOUR_API_KEY"

# Create with custom params
curl "https://api.tevyr.com/v1/adhoc/create_adhoc?room_id=433019&api_key=YOUR_API_KEY&name=Break&minutes=5&seconds=30&screen_mode=split&screen_selections=speaker,staff"

# Create with labels
curl "https://api.tevyr.com/v1/adhoc/create_adhoc?room_id=433019&api_key=YOUR_API_KEY&name=VT&labels%5B0%5D%5Bname%5D=VT&labels%5B0%5D%5Bcolor%5D=%23F44336"

{
  "ok": true,
  "message": "Timer created",
  "data": {
    "_id": "8ef423c7-f52d-4fd5-ac71-25030cd16609",
    "_model": "timer",
    "_updated_at": "2026-04-22T08:00:00.000Z",
    "name": "Break",
    "speaker": null,
    "notes": null,
    "labels": [],
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "duration": "0:05:30",
    "hours": 0,
    "minutes": 5,
    "seconds": 30,
    "wrap_up_yellow": 60,
    "wrap_up_red": 15,
    "trigger": "MANUAL",
    "start_time": null,
    "start_time_uses_date": false,
    "finish_time": null,
    "finish_time_uses_date": false
  }
}

#Update ad-hoc timer

GET/v1/adhoc/update_adhoc

Partial update of an ad-hoc timer. Only the parameters you provide will be changed. All other properties remain unchanged.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the ad-hoc timer. Either timer_id or index is required

indexinteger

1-based position in the timer list (1 = first timer, 2 = second, etc.). Either timer_id or index is required

namestring

Timer name

speakerstring

Speaker name

notesstring

Notes for the timer

labelsarray

Indexed notation: labels[0][name]=VT&labels[0][color]=%23F44336

appearancestring

Display type: countdown, countup, tod, countdown_tod, countup_tod

typestring

Timer type: duration, target_time, time_warp

hoursinteger

Duration hours (if any h/m/s provided, duration is recomputed)

minutesinteger

Duration minutes

secondsinteger

Duration seconds

wrap_up_yellowinteger

Warning threshold in seconds

wrap_up_redinteger

Critical threshold in seconds

triggerstring

Start mode: manual, linked, scheduled

start_timestring

ISO datetime for scheduled start

finish_timestring

ISO datetime for target finish

screen_modestring

Display mode: override or split

screen_selectionsstring

Comma-separated screens: speaker,audience,staff

Request (example)

# Update name only
curl "https://api.tevyr.com/v1/adhoc/update_adhoc?room_id=433019&api_key=YOUR_API_KEY&index=1&name=Warmup"

# Update duration + thresholds
curl "https://api.tevyr.com/v1/adhoc/update_adhoc?room_id=433019&api_key=YOUR_API_KEY&index=1&minutes=15&wrap_up_yellow=90&wrap_up_red=30"

# Update screens
curl "https://api.tevyr.com/v1/adhoc/update_adhoc?room_id=433019&api_key=YOUR_API_KEY&timer_id=abc123&screen_mode=split&screen_selections=speaker,audience"

{
  "ok": true,
  "message": "Timer updated",
  "data": {
    "_id": "2d161a14-865d-4489-a8e9-9b3b56000d8a",
    "_model": "timer",
    "_updated_at": "2026-04-22T09:32:11.945Z",
    "name": "Warmup",
    "speaker": "Alice",
    "notes": null,
    "labels": [],
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "duration": "0:15:00",
    "hours": 0,
    "minutes": 15,
    "seconds": 0,
    "wrap_up_yellow": 90,
    "wrap_up_red": 30,
    "trigger": "MANUAL",
    "start_time": null,
    "start_time_uses_date": false,
    "finish_time": null,
    "finish_time_uses_date": false
  }
}

#Delete ad-hoc timer

GET/v1/adhoc/delete

Delete an ad-hoc timer from the room. The timer is removed from all screens immediately.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the ad-hoc timer. Either timer_id or index is required

indexinteger

1-based position in the timer list (1 = first timer, 2 = second, etc.). Either timer_id or index is required

Request (example)

curl "https://api.tevyr.com/v1/adhoc/delete?room_id=433019&api_key=YOUR_API_KEY&index=3"

{
  "ok": true,
  "message": "Timer deleted"
}

#Get ad-hoc timer

GET/v1/adhoc/get_adhoc

Get the properties of a single ad-hoc timer. Read-only — does not change timer state.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the ad-hoc timer. Either timer_id or index is required

indexinteger

1-based position in the timer list (1 = first timer, 2 = second, etc.). Either timer_id or index is required

Request (example)

curl "https://api.tevyr.com/v1/adhoc/get_adhoc?room_id=433019&api_key=YOUR_API_KEY&index=1"

{
  "ok": true,
  "message": "Timer loaded",
  "data": {
    "_id": "2d161a14-865d-4489-a8e9-9b3b56000d8a",
    "_model": "timer",
    "_updated_at": "2026-04-22T09:45:01.170Z",
    "name": "Timer 1",
    "speaker": "Thomas",
    "notes": "Very tall, remember to adjust camera angle",
    "labels": [{ "name": "VT", "color": "#F44336" }],
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "duration": "0:10:00",
    "hours": 0,
    "minutes": 10,
    "seconds": 0,
    "wrap_up_yellow": 60,
    "wrap_up_red": 15,
    "trigger": "MANUAL",
    "start_time": null,
    "start_time_uses_date": false,
    "finish_time": null,
    "finish_time_uses_date": false
  }
}

#Get all ad-hoc timers

GET/v1/adhoc/get_all_adhoc

Get all ad-hoc timers in the room, ordered by position. Read-only.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request (example)

curl "https://api.tevyr.com/v1/adhoc/get_all_adhoc?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Timers loaded",
  "data": [
    {
      "_id": "2d161a14-865d-4489-a8e9-9b3b56000d8a",
      "_model": "timer",
      "_updated_at": "2026-04-22T09:00:00.000Z",
      "name": "Timer 1",
      "speaker": "Thomas",
      "notes": null,
      "labels": [{ "name": "VT", "color": "#F44336" }],
      "appearance": "COUNTDOWN",
      "type": "DURATION",
      "duration": "0:10:00",
      "hours": 0,
      "minutes": 10,
      "seconds": 0,
      "wrap_up_yellow": 60,
      "wrap_up_red": 15,
      "trigger": "MANUAL",
      "start_time": null,
      "start_time_uses_date": false,
      "finish_time": null,
      "finish_time_uses_date": false
    },
    "..."
  ]
}

Display Effects

Control visual effects on output screens. Emergency effects (blackout, flash, red/green light) are mutually exclusive — enabling one automatically disables the others. All emergency effects are toggles — calling the same endpoint twice turns it on then off.

#Timer flash

GET/v1/display/timer_flash

Flash the timer display on selected screens. Customizable repeat count. Each pulse is 0.5 seconds.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

countinteger

Number of flash pulses (1-999). Default: 3

screen_selectionsstring

Comma-separated screens: speaker,audience,staff. Default: all screens

Request (example)

# Flash all screens 3 times (default)
curl "https://api.tevyr.com/v1/display/timer_flash?room_id=433019&api_key=YOUR_API_KEY"

# Flash speaker only 10 times
curl "https://api.tevyr.com/v1/display/timer_flash?room_id=433019&api_key=YOUR_API_KEY&count=10&screen_selections=speaker"

{
  "ok": true,
  "message": "Triggered flashing (×10)"
}

#Blackout (toggle)

GET/v1/display/blackout

Toggle panic blackout on all screens. Calling twice turns it on then off. Mutually exclusive with flash, red light, and green light.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request (example)

curl "https://api.tevyr.com/v1/display/blackout?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Blackout ON"
}

#Disco flash (toggle)

GET/v1/display/flash

Toggle continuous disco flash on all screens. Mutually exclusive with blackout, red light, and green light.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request (example)

curl "https://api.tevyr.com/v1/display/flash?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Flash ON"
}

#Red light (toggle)

GET/v1/display/red_light

Toggle red light indicator on all screens. Mutually exclusive with blackout, flash, and green light.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request (example)

curl "https://api.tevyr.com/v1/display/red_light?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Red Light ON"
}

#Green light (toggle)

GET/v1/display/green_light

Toggle green light indicator on all screens. Mutually exclusive with blackout, flash, and red light.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request (example)

curl "https://api.tevyr.com/v1/display/green_light?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Green Light ON"
}

#Screen blackout (toggle)

GET/v1/display/screen_blackout

Toggle blackout on individual screens. Screens in the selection are toggled — if currently on, turned off; if off, turned on. Other screens are unaffected.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens to toggle: speaker,audience,staff

Request (example)

curl "https://api.tevyr.com/v1/display/screen_blackout?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker,audience"

{
  "ok": true,
  "message": "Blackout: speaker ON, audience ON",
  "data": {
    "active_screens": ["speaker", "audience"]
  }
}

#Focus mode (toggle)

GET/v1/display/focus

Toggle focus mode on individual screens. Focus mode isolates the timer display, dimming other elements.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens to toggle: speaker,audience,staff

Request (example)

curl "https://api.tevyr.com/v1/display/focus?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

{
  "ok": true,
  "message": "Focus: speaker ON",
  "data": {
    "active_screens": ["speaker"]
  }
}

#On Air (toggle)

GET/v1/display/on_air

Toggle the On Air indicator on individual screens. Requires Basic plan or higher.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens to toggle: speaker,audience,staff

Request (example)

curl "https://api.tevyr.com/v1/display/on_air?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker,audience"

{
  "ok": true,
  "message": "On Air: speaker ON, audience ON",
  "data": {
    "active_screens": ["speaker", "audience"]
  }
}

#QR Code (toggle)

GET/v1/display/qr_code

Toggle the Q&A QR code overlay on output screens. The QR code links to the audience question submission page. Requires Premium plan or higher.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsstring

Comma-separated screens: speaker,audience,staff. Default: all screens

Request (example)

# Toggle QR on all screens
curl "https://api.tevyr.com/v1/display/qr_code?room_id=433019&api_key=YOUR_API_KEY"

# Toggle QR on speaker only
curl "https://api.tevyr.com/v1/display/qr_code?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

{
  "ok": true,
  "message": "QR Code ON"
}

#Timer visibility (toggle)

GET/v1/display/hide_timer

Toggle timer visibility on individual screens. Screens in the selection are toggled — if the timer is currently visible, it will be hidden; if hidden, it will be shown. Default: timer visible on all screens.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens to toggle: speaker,audience,staff

Request (example)

# Hide timer on speaker screen
curl "https://api.tevyr.com/v1/display/hide_timer?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

# Show it again (toggle)
curl "https://api.tevyr.com/v1/display/hide_timer?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

{
  "ok": true,
  "message": "Timer visible on: audience, staff",
  "data": {
    "visible_screens": ["audience", "staff"]
  }
}

#Enable screen blackout

GET/v1/display/enable_blackout

Enable blackout on selected screens. Idempotent — calling twice has no additional effect.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens: speaker,audience,staff

Request

curl "https://api.tevyr.com/v1/display/enable_blackout?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker,audience"

{
  "ok": true,
  "message": "Blackout: speaker ON, audience ON",
  "data": { "active_screens": ["speaker", "audience"] }
}

#Disable screen blackout

GET/v1/display/disable_blackout

Disable blackout on selected screens. Idempotent.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens: speaker,audience,staff

Request

curl "https://api.tevyr.com/v1/display/disable_blackout?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

{
  "ok": true,
  "message": "Blackout: speaker OFF",
  "data": { "active_screens": ["audience"] }
}

#Enable focus mode

GET/v1/display/enable_focus

Enable focus mode on selected screens. Idempotent.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens: speaker,audience,staff

Request

curl "https://api.tevyr.com/v1/display/enable_focus?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

{
  "ok": true,
  "message": "Focus: speaker ON",
  "data": { "active_screens": ["speaker"] }
}

#Disable focus mode

GET/v1/display/disable_focus

Disable focus mode on selected screens. Idempotent.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens: speaker,audience,staff

Request

curl "https://api.tevyr.com/v1/display/disable_focus?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker,audience,staff"

{
  "ok": true,
  "message": "Focus: speaker OFF, audience OFF, staff OFF",
  "data": { "active_screens": [] }
}

#Enable On Air

GET/v1/display/enable_on_air

Enable On Air indicator on selected screens. Idempotent. Requires Basic plan or higher.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens: speaker,audience,staff

Request

curl "https://api.tevyr.com/v1/display/enable_on_air?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker,audience"

{
  "ok": true,
  "message": "On Air: speaker ON, audience ON",
  "data": { "active_screens": ["speaker", "audience"] }
}

#Disable On Air

GET/v1/display/disable_on_air

Disable On Air indicator on selected screens. Idempotent.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsRequiredstring

Comma-separated screens: speaker,audience,staff

Request

curl "https://api.tevyr.com/v1/display/disable_on_air?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

{
  "ok": true,
  "message": "On Air: speaker OFF",
  "data": { "active_screens": ["audience"] }
}

#Enable QR Code

GET/v1/display/enable_qr_code

Show QR code on selected screens. Idempotent. Requires Premium plan or higher.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsstring

Comma-separated screens: speaker,audience,staff. Default: all screens

Request

curl "https://api.tevyr.com/v1/display/enable_qr_code?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

{
  "ok": true,
  "message": "QR Code ON"
}

#Disable QR Code

GET/v1/display/disable_qr_code

Hide QR code from screens. Idempotent.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request

curl "https://api.tevyr.com/v1/display/disable_qr_code?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "QR Code OFF"
}

Messages

Show, hide, and toggle saved messages on output screens. Messages are targeted by message_id or index (1-based position in the saved message list). Each screen can display a different message simultaneously.

#Show message

GET/v1/message/show

Show a saved message on selected screens. Optionally enable focus mode to display the message fullscreen.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

message_idstring

ID of the saved message. Either message_id or index is required

indexinteger

1-based position in the message list. Either message_id or index is required

screen_selectionsstring

Comma-separated screens: speaker,audience,staff. Default: all screens

focusboolean

Enable focus mode (fullscreen message). Default: false

Request (example)

# Show message 1 on all screens
curl "https://api.tevyr.com/v1/message/show?room_id=433019&api_key=YOUR_API_KEY&index=1"

# Show on speaker only with focus
curl "https://api.tevyr.com/v1/message/show?room_id=433019&api_key=YOUR_API_KEY&index=1&screen_selections=speaker&focus=true"

{
  "ok": true,
  "message": "Message showing",
  "data": {
    "_id": "e5f46622-be82-fdaa-44bb-a54c12345678",
    "_model": "message",
    "_updated_at": "2026-04-22T08:00:00.000Z",
    "showing": true,
    "text": "Question for the speaker: How do we scale?",
    "color": "white",
    "bold": false,
    "uppercase": false
  }
}

#Hide message

GET/v1/message/hide

Hide the currently displayed message from selected screens. No message_id or index needed — clears whatever is showing. Also disables focus mode on hidden screens if active.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

screen_selectionsstring

Comma-separated screens: speaker,audience,staff. Default: all screens

Request (example)

# Hide from all screens
curl "https://api.tevyr.com/v1/message/hide?room_id=433019&api_key=YOUR_API_KEY"

# Hide from speaker only (audience/staff keep their messages)
curl "https://api.tevyr.com/v1/message/hide?room_id=433019&api_key=YOUR_API_KEY&screen_selections=speaker"

{
  "ok": true,
  "message": "Message hidden"
}

#Toggle message

GET/v1/message/toggle_message

Toggle a saved message — if currently showing on selected screens, hide it; if hidden, show it. Optionally enable focus mode when showing.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

message_idstring

ID of the saved message. Either message_id or index is required

indexinteger

1-based position in the message list. Either message_id or index is required

screen_selectionsstring

Comma-separated screens: speaker,audience,staff. Default: all screens

focusboolean

Enable focus mode when showing. Default: false

Request (example)

curl "https://api.tevyr.com/v1/message/toggle_message?room_id=433019&api_key=YOUR_API_KEY&index=1"

{
  "ok": true,
  "message": "Message showing",
  "data": {
    "_id": "e5f46622-be82-fdaa-44bb-a54c12345678",
    "_model": "message",
    "_updated_at": "2026-04-22T08:00:00.000Z",
    "showing": true,
    "text": "Question for the speaker",
    "color": "white",
    "bold": false,
    "uppercase": false
  }
}

#Flash message

GET/v1/message/flash

Flash the currently displayed message on selected screens. Customizable pulse count. Each pulse is 0.33 seconds. Auto-stops after all pulses complete.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

countinteger

Number of flash pulses (1-999). Default: 12 (~4 seconds)

screen_selectionsstring

Comma-separated screens: speaker,audience,staff. Default: all screens

Request

curl "https://api.tevyr.com/v1/message/flash?room_id=433019&api_key=YOUR_API_KEY&count=20"

{
  "ok": true,
  "message": "Message flash triggered (×20)"
}

#Create message

GET/v1/message/create

Create a new saved message in the room. Subject to plan limits.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

textstring

Message content. Default: blank. Max 5000 chars

colorstring

Text color: white, green, red. Default: white

boldboolean

Bold text. Default: false

uppercaseboolean

Uppercase text. Default: false

screen_selectionsstring

Comma-separated screens. Default: all

Request

curl "https://api.tevyr.com/v1/message/create?room_id=433019&api_key=YOUR_API_KEY&text=Hello+World&color=green&bold=true"

{
  "ok": true,
  "message": "Message created",
  "data": {
    "_id": "abc123",
    "_model": "message",
    "_updated_at": "2026-04-22T08:00:00.000Z",
    "showing": false,
    "text": "Hello World",
    "color": "green",
    "bold": true,
    "uppercase": false,
    "screen_selections": ["speaker", "audience", "staff"]
  }
}

#Update message

GET/v1/message/update

Partial update of a saved message. Only provided parameters are changed.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

message_idstring

ID of the message. Either message_id or index required

indexinteger

1-based position. Either message_id or index required

textstring

New message content

colorstring

Text color: white, green, red

boldboolean

Bold text

uppercaseboolean

Uppercase text

screen_selectionsstring

Comma-separated screens

Request

curl "https://api.tevyr.com/v1/message/update?room_id=433019&api_key=YOUR_API_KEY&index=1&text=Updated+text&color=red"

{
  "ok": true,
  "message": "Message updated",
  "data": {
    "_id": "abc123",
    "_model": "message",
    "_updated_at": "2026-04-22T08:00:00.000Z",
    "showing": false,
    "text": "Updated text",
    "color": "red",
    "bold": false,
    "uppercase": false,
    "screen_selections": ["speaker"]
  }
}

#Delete message

GET/v1/message/delete

Delete a saved message from the room.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

message_idstring

ID of the message. Either message_id or index required

indexinteger

1-based position. Either message_id or index required

Request

curl "https://api.tevyr.com/v1/message/delete?room_id=433019&api_key=YOUR_API_KEY&index=3"

{
  "ok": true,
  "message": "Message deleted"
}

#Get message

GET/v1/message/get_message

Get a single saved message. Read-only.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

message_idstring

ID of the message. Either message_id or index required

indexinteger

1-based position. Either message_id or index required

Request

curl "https://api.tevyr.com/v1/message/get_message?room_id=433019&api_key=YOUR_API_KEY&index=1"

{
  "ok": true,
  "message": "Message loaded",
  "data": {
    "_id": "abc123",
    "_model": "message",
    "_updated_at": "2026-04-22T08:00:00.000Z",
    "showing": false,
    "text": "Hello World",
    "color": "white",
    "bold": false,
    "uppercase": false,
    "screen_selections": ["speaker", "audience", "staff"]
  }
}

#Get all messages

GET/v1/message/get_all_messages

Get all saved messages in the room. Read-only.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request

curl "https://api.tevyr.com/v1/message/get_all_messages?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Messages loaded",
  "data": {
    "messages": [
      {
        "_id": "abc123",
        "_model": "message",
        "_updated_at": "2026-04-22T08:00:00.000Z",
        "showing": false,
        "text": "Hello World",
        "color": "white",
        "bold": false,
        "uppercase": false,
        "screen_selections": ["speaker", "audience", "staff"]
      }
    ]
  }
}

Sessions

Start, stop, and navigate to specific sessions by timer_id (UUID) or index (1-based position). Unlike Timer Controls which act on the currently active session, Session endpoints let you target any session in your rundown.

#Start session

GET/v1/session/start

Start or resume a specific session by ID or index. If the target session is already active, it simply starts the timer. If it's a different session, the endpoint navigates to it first (resetting the current session), then starts the timer. Teleprompters, overtime, target-time, and extend mode are all handled automatically.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the session. Either timer_id or index is required

indexinteger

1-based position in the session list. Either timer_id or index is required

Request (by index)

curl "https://api.tevyr.com/v1/session/start?room_id=433019&api_key=YOUR_API_KEY&index=3"

Request (by timer_id)

curl "https://api.tevyr.com/v1/session/start?room_id=433019&api_key=YOUR_API_KEY&timer_id=6e7bed23-87e4-4809-b5ab-0688346e7dd6"

{
  "ok": true,
  "message": "Timer started at 0:05:00",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-22T08:00:00.000Z",
    "room_id": "433019",
    "session": {
      "id": "6e7bed23-87e4-4809-b5ab-0688346e7dd6",
      "title": "Panel Discussion",
      "status": "active",
      "duration_seconds": 300,
      "is_running": true,
      "remaining_seconds": 300,
      "started_at": "2026-04-22T08:00:00.000Z"
    },
    "adhoc_timers": []
  }
}

#Stop session

GET/v1/session/stop

Stop the timer on a specific session by ID or index. If the target session is not currently playing, returns a 200 no-op response without making any changes. Unlike /v1/timer/stop which always targets the active session, this endpoint lets you specify which session to stop.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the session. Either timer_id or index is required

indexinteger

1-based position in the session list. Either timer_id or index is required

Request

curl "https://api.tevyr.com/v1/session/stop?room_id=433019&api_key=YOUR_API_KEY&index=3"

{
  "ok": true,
  "message": "Timer stopped at 0:02:55",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-04-22T08:00:00.000Z",
    "room_id": "433019",
    "session": {
      "id": "6e7bed23-...",
      "title": "Panel Discussion",
      "status": "active",
      "is_running": false,
      "remaining_seconds": 175
    }
  }
}

#Toggle session

GET/v1/session/start_stop

Toggle play/pause on a specific session by ID or index. If the target is the active session and running, it stops. If paused, it starts. If the target is a different session entirely, it navigates to that session and starts it — same behavior as Start session.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the session. Either timer_id or index is required

indexinteger

1-based position in the session list. Either timer_id or index is required

Request

curl "https://api.tevyr.com/v1/session/start_stop?room_id=433019&api_key=YOUR_API_KEY&index=3"

{
  "ok": true,
  "message": "Timer stopped at 0:02:55",
  "data": {
    "_model": "playback_status",
    "session_name": "Round 2",
    "running": false,
    "remaining_seconds": 175
  }
}

#Reset session

GET/v1/session/reset

Reset a specific session's timer to its original duration. If the target is a different session, it navigates to that session first (making it the active session), then resets. Use autostart=true to automatically start the timer after resetting.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the session. Either timer_id or index is required

indexinteger

1-based position in the session list. Either timer_id or index is required

autostartboolean

If true, start the timer immediately after resetting. Default: false

Request

# Reset and keep paused
curl "https://api.tevyr.com/v1/session/reset?room_id=433019&api_key=YOUR_API_KEY&index=3"

# Reset and auto-start
curl "https://api.tevyr.com/v1/session/reset?room_id=433019&api_key=YOUR_API_KEY&index=3&autostart=true"

{
  "ok": true,
  "message": "Timer reset at 0:03:00",
  "data": {
    "_model": "playback_status",
    "session_name": "Round 2",
    "running": false,
    "remaining_seconds": 180
  }
}

#Create session

GET/v1/session/create

Create a new session at the end of the list. All parameters except room_id and api_key are optional. Default thresholds are 20% (yellow) and 10% (red) of the duration. Subject to plan session limits. Setting trigger=LINKED automatically links this session from the previous one.

Validation: wrap_up_red must be less than wrap_up_yellow, both must be less than the duration. finish_time is required when type=TARGET_TIME. start_time is required when trigger=SCHEDULED.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

namestring

Session name. Default: "Session [n]"

speakerstring

Speaker name

notesstring

Notes (max 5,000 characters)

hoursinteger

Duration hours. Default: 0

minutesinteger

Duration minutes. Default: 5

secondsinteger

Duration seconds. Default: 0

appearancestring

COUNTDOWN, COUNTUP, TOD, COUNTDOWN_TOD, or COUNTUP_TOD. Default: COUNTDOWN

typestring

DURATION or TARGET_TIME. Default: DURATION

triggerstring

MANUAL, LINKED, or SCHEDULED. Default: MANUAL

wrap_up_yellowinteger

Warning threshold in seconds. Default: 20% of duration

wrap_up_redinteger

Critical threshold in seconds. Default: 10% of duration

start_timestring

ISO datetime. Required when trigger=SCHEDULED

finish_timestring

ISO datetime. Required when type=TARGET_TIME

Request

curl "https://api.tevyr.com/v1/session/create?room_id=433019&api_key=YOUR_API_KEY&name=Keynote&speaker=Jane&minutes=30"

{
  "ok": true,
  "message": "Timer created",
  "data": {
    "_id": "a1b2c3d4-...",
    "_model": "timer",
    "name": "Keynote",
    "speaker": "Jane",
    "duration": "0:30:00",
    "hours": 0, "minutes": 30, "seconds": 0,
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "trigger": "MANUAL",
    "wrap_up_yellow": 360,
    "wrap_up_red": 180
  }
}

#Update session

GET/v1/session/update

Partial update of a session. Only the parameters you provide will be changed. Changing trigger automatically manages the link chain between sessions — setting to LINKED connects to the previous session, setting to MANUAL breaks the link and isolates the session.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the session. Either timer_id or index is required

indexinteger

1-based position in the session list. Either timer_id or index is required

namestring

Session name

speakerstring

Speaker name

notesstring

Notes (max 5,000 characters)

hoursinteger

Duration hours

minutesinteger

Duration minutes

secondsinteger

Duration seconds

appearancestring

COUNTDOWN, COUNTUP, TOD, COUNTDOWN_TOD, or COUNTUP_TOD

typestring

DURATION or TARGET_TIME

triggerstring

MANUAL, LINKED, or SCHEDULED. Manages link chain automatically

wrap_up_yellowinteger

Warning threshold in seconds

wrap_up_redinteger

Critical threshold in seconds

start_timestring

ISO datetime for scheduled start

finish_timestring

ISO datetime for target time end

Request

# Update name and speaker
curl "https://api.tevyr.com/v1/session/update?room_id=433019&api_key=YOUR_API_KEY&index=3&name=Panel&speaker=Alice"

# Link a session
curl "https://api.tevyr.com/v1/session/update?room_id=433019&api_key=YOUR_API_KEY&index=4&trigger=linked"

{
  "ok": true,
  "message": "Timer updated",
  "data": {
    "_id": "f221ef2f-...",
    "_model": "timer",
    "name": "Panel",
    "speaker": "Alice",
    "duration": "0:03:00",
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "trigger": "MANUAL"
  }
}

#Delete session

GET/v1/session/delete

Delete a session from the room. If the deleted session is currently active, the timer is cleared. Link chains between adjacent sessions bridge automatically.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the session. Either timer_id or index is required

indexinteger

1-based position in the session list. Either timer_id or index is required

Request

curl "https://api.tevyr.com/v1/session/delete?room_id=433019&api_key=YOUR_API_KEY&index=5"

{
  "ok": true,
  "message": "Timer deleted"
}

#Get session

GET/v1/session/get

Get the properties of a single session. Read-only — does not change session state.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

timer_idstring

UUID of the session. Either timer_id or index is required

indexinteger

1-based position in the session list. Either timer_id or index is required

Request

curl "https://api.tevyr.com/v1/session/get?room_id=433019&api_key=YOUR_API_KEY&index=1"

{
  "ok": true,
  "message": "Timer loaded",
  "data": {
    "_id": "6e7bed23-...",
    "_model": "timer",
    "name": "Warmup",
    "speaker": null,
    "notes": "Light footwork and combos",
    "labels": [],
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "duration": "0:11:00",
    "hours": 0, "minutes": 11, "seconds": 0,
    "wrap_up_yellow": 120,
    "wrap_up_red": 60,
    "trigger": "MANUAL",
    "start_time": null,
    "start_time_uses_date": false,
    "finish_time": null,
    "finish_time_uses_date": false
  }
}

#Get all sessions

GET/v1/session/get_all

Get all sessions in the room, ordered by position. Read-only.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request

curl "https://api.tevyr.com/v1/session/get_all?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Timers loaded",
  "data": [
    {
      "_id": "6e7bed23-...",
      "_model": "timer",
      "name": "Warmup",
      "duration": "0:11:00",
      "trigger": "MANUAL"
    },
    {
      "_id": "f221ef2f-...",
      "_model": "timer",
      "name": "Round 1",
      "duration": "0:06:30",
      "trigger": "LINKED"
    },
    "..."
  ]
}

Macros

Macros bundle a sequence of timer, message, display, polling, and integration actions into a single fire-and-forget run. Build them in the dashboard's Macros panel, then trigger them from a hardware button (Stream Deck, X-keys), a custom HTTP script, or any tool that can hit a URL. Two GET endpoints — list available macros, then fire one by ID. See the Macros guide for the full feature reference.

#List macros

GET/v1/macros/list

Returns every enabled macro for the room, with the metadata a hardware controller needs to render labeled buttons (id, name, description, icon, color, step count). Disabled macros are excluded.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

api_keyRequiredstring

Your Room API key

Request

curl "https://api.tevyr.com/v1/macros/list?room_id=433019&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "2 macros",
  "data": {
    "_model": "macros_list",
    "_updated_at": "2026-05-17T14:32:08.412Z",
    "room_id": "433019",
    "macros": [
      {
        "id": "8e2c1d6f-...",
        "name": "House lights down",
        "description": "Blackout + green light + start recording",
        "icon": "Power",
        "color": "violet",
        "step_count": 3,
        "manual": true,
        "lifecycle_count": 0
      },
      {
        "id": "a9b4f320-...",
        "name": "Speaker on deck",
        "description": "Flash timer + Slack ping + focus mode",
        "icon": "Bell",
        "color": "amber",
        "step_count": 4,
        "manual": true,
        "lifecycle_count": 1
      }
    ]
  }
}

#Run a macro

GET/v1/macros/run

Fire a macro by ID. Returns 202 Accepted with an execution_id immediately — the run continues asynchronously on the server. Step-by-step status is broadcast to dashboard clients over WebSocket; the API caller doesn't see live progress.

Spam protection: skip_if_running defaults to true so a bumped Stream Deck button won't fire a second concurrent run while the first is still going. Pass skip_if_running=false only when overlapping runs are intentional.

Authentication: Required

Query parameters

room_idRequiredstring

The 6-digit passcode of your room

macro_idRequiredstring

The macro UUID (from /v1/macros/list)

skip_if_runningboolean

Default true. When true, returns status=skipped if a run of this macro is already in flight.

api_keyRequiredstring

Your Room API key

Request — fire a macro

curl "https://api.tevyr.com/v1/macros/run?room_id=433019&macro_id=8e2c1d6f-...&api_key=YOUR_API_KEY"

Request — allow concurrent runs

curl "https://api.tevyr.com/v1/macros/run?room_id=433019&macro_id=8e2c1d6f-...&skip_if_running=false&api_key=YOUR_API_KEY"

{
  "ok": true,
  "message": "Macro started",
  "data": {
    "_model": "macro_run_result",
    "_updated_at": "2026-05-17T14:33:12.084Z",
    "execution_id": "f0c7d1a3-...",
    "status": "started",
    "reason": null,
    "macro_id": "8e2c1d6f-..."
  }
}

Error Responses

All error responses follow the same format. The ok field is false, the message field contains a human-readable description, and the code field provides a machine-readable error code for programmatic handling.

400 Bad Request

Invalid or missing parameters.

400 Bad Request

{
  "ok": false,
  "message": "room_id is required",
  "code": "VALIDATION_ERROR"
}

401 Unauthorized

Missing or invalid API key.

401 Unauthorized

{
  "ok": false,
  "message": "Access Denied: Valid API key required",
  "code": "INVALID_API_KEY"
}

403 Forbidden

Insufficient plan or wrong room.

403 Forbidden

{
  "ok": false,
  "message": "API access requires a Premium or Enterprise plan",
  "code": "PLAN_REQUIRED"
}

404 Not Found

Endpoint or room not found.

404 Not Found

{
  "ok": false,
  "message": "Endpoint not found",
  "code": "NOT_FOUND"
}

429 Too Many Requests

Rate limit exceeded.

429 Too Many Requests

{
  "ok": false,
  "message": "Too many requests. Please try again later.",
  "code": "RATE_LIMITED"
}

Guides

How GET Requests Work

GET is the standard HTTP method used to retrieve data. When you open a URL in your browser, it performs a GET request behind the scenes. The Tevyr API uses GET requests for all operations — reading state, controlling timers, and managing sessions.

Query parameters pass additional information to the server as part of the URL. They follow the base URL after a ?, with each parameter separated by &:

Example URL

https://api.tevyr.com/v1/event/playback_status?room_id=433019&api_key=YOUR_KEY

In this example:

room_id=433019 tells the API which room to target
api_key=YOUR_KEY authenticates your request

Special characters in parameter values must be URL-encoded (for example, # becomes %23).

How Targeting Works

By default, action endpoints such as start, stop, and reset operate on the currently active session — the one highlighted in your controller. No additional targeting is required for these commands.

To target a specific session or ad-hoc timer, provide its unique ID (a UUID such as 6e7bed23-87e4-4809-b5ab-0688346e7dd6) via the timer_id parameter. Alternatively, use the index parameter with a 1-based position number. Retrieve available IDs and indices through the Get playback status or Get all sessions endpoints.

Session states in the controller:

Pending — session has not been started
Active — session is loaded and ready, indicated by a colored background
Running — timer is counting down, indicated by a red background

Commands sent through the Timer Controls category (start, stop, reset) always apply to the active session. To verify which session is active, query the playback status endpoint before issuing commands. To target a different session directly, use the Session category endpoints with timer_id or index.

Automating a Full Show

Tevyr enables fully autonomous event rundowns with zero human involvement. The server-side scheduler triggers the first session at the exact scheduled time, linked sessions chain automatically from there, teleprompter scripts scroll in sync, webhooks fire to external systems, and audio alerts sound at every threshold — all without anyone pressing a button.

Session automation:

Scheduled sessions — set trigger=SCHEDULED with a start_time and the server triggers it automatically at the exact time. No manual start required — the show begins on its own.
Linked sessions — set trigger=LINKED and the session auto-starts the moment the previous timer reaches zero. Chain your entire rundown and every session fires in sequence.
Teleprompter auto-play — attach a script to any session and it begins scrolling automatically when that session starts. As sessions advance, scripts transition seamlessly — the previous stops, the next takes over.

Webhooks — trigger external systems in real time:

Tevyr sends HTTP POST requests to your endpoints when key events occur. Use webhooks to integrate with lighting consoles, camera systems, streaming software, or any HTTP-capable device.

timer.started timer.finished — start/stop recording, switch OBS scenes, trigger sound cues
timer.warning timer.critical — change stage lighting color, flash confidence monitors
session.started session.changed — update digital signage, notify green room, switch cameras
session.overtime session.upcoming — send Slack alerts, page the next speaker

Audio alerts — no hardware required:

Each output screen can play browser-generated sounds (chime, beep, or bell) when the timer crosses warning, critical, or zero thresholds. Configure volume, pulse count, and repeat intervals per screen — no external sound system needed.

Additional automation:

Sponsor wall — auto-rotating logo grids with fade, swipe, or marquee transitions during breaks.
Live polling — push interactive polls and quizzes to audience screens with real-time vote visualization.
Screen effects — blackout, flash, on-air indicators, and focus mode — all triggerable via the API.
Messages — send targeted text overlays to speaker, audience, or staff screens programmatically.

Example autonomous rundown:

09:00 Keynote (10 min) — scheduled + teleprompter + webhook → start recording

↳ auto-starts next

09:10 Q&A (5 min) — linked + webhook → switch to audience camera

↳ auto-starts next

09:15 Break (3 min) — linked + sponsor wall auto-rotates

↳ auto-starts next

09:18 Panel (20 min) — linked + teleprompter + live poll at 09:30

From the first scheduled session to the final closing remarks — zero human involvement. The server triggers, sessions chain, scripts scroll, webhooks fire, alerts sound, and every connected screen updates in real time.