1.2 marks endpoints added in StageTime 1.2 and 1.1 those from 1.1. Everything older is unchanged.
Overview
StageTime includes a built-in HTTP API that binds to 0.0.0.0 on the configured port (default 8088), so it's reachable from any device on the same network. Every endpoint is a plain GET and returns JSON: { "ok": true, ... } on success, or { "ok": false, "error": "..." } with a 4xx status. CORS is open, so browser-based tools can call it directly. Change the port from App ▸ Change API Port….
The same reference is served live by the app at http://<computer-ip>:8088/ (HTML) and /api/help (JSON), and Help ▸ API Reference… opens it in a window with the base URLs for that machine. Options changed through the API are remembered across launches and mirrored on the remote. Every endpoint that existed in 1.0 works exactly as before.
API key (1.2). When a key is set under App ▸ API Key…, every request that changes something must carry it as ?key=… or an X-API-Key header, or it gets a 401. /api/status, /api/events, /api/help, /api/presets, /api/quickmessages, /api/displays, /api/rundown, /display and /manual stay open. Every request is listed in App ▸ Connection Log….
Status & Events
Status reflects the display's most recent report. A command returns ok as soon as it is dispatched, so a status read within a few milliseconds may not show the change yet; /api/events pushes it the moment it lands.
| Method | Endpoint | Description |
|---|
| GET | /api/status | Full state as JSON: time, light color, mode, options, preset and quick-message slots. |
| GET | /api/events | Server-Sent Events stream. One data: line with the status object on every change, plus a : ping every 15 seconds. Use for instant Companion feedback instead of polling. |
| GET | /api/help | This reference as JSON. |
| GET | /manual | 1.2 The built-in manual as a web page. |
| GET | /api/displays | 1.2 Monitors attached to the computer, with which one holds the display and which are mirrors. |
| GET | /api/log | 1.2 Every request received since launch (up to 1000). Needs the key when one is set. |
Example Response
{
"ok": true,
"version": "1.2.0",
"remainingSeconds": 573,
"running": true,
"localMode": false,
"countUpMode": false,
"overtime": false,
"formattedTime": "09:33",
"formattedTimeSigned": "09:33",
"lightColor": "green",
"lightColorHex": "#00ff00",
"progress": 0.955,
"wrapUpSeconds": 120,
"flashOn": true,
"flashBorder": false,
"stopAtZero": false,
"soundOn": false,
"showMilliseconds": false,
"showProgress": false,
"bgBlue": false,
"blackout": false,
"cornerClock": false,
"showEndsAt": true,
"endsAt": "3:45:00 PM",
"elapsedRunSeconds": 27,
"buzzerSound": "default",
"buzzerVolume": 100,
"apiKeySet": false,
"mirrors": [],
"messageVisible": false,
"messageWithTimer": false,
"messageShownWithTimer": false,
"autoMessageAtZero": false,
"autoMessageText": "TIME'S UP",
"timeZone": "system",
"hour12": true,
"preset_1_name": "Keynote",
"preset_1_time": "45:00",
"presetCount": 1,
"quick_1_text": "WRAP UP",
"quick_2_text": "TIME'S UP",
"quick_3_text": "Q&A",
"quickCount": 3,
"rundownCount": 4,
"rundownIndex": 2,
"rundownCue": "Keynote",
"rundownNext": "Q&A",
"rundownStandby": 3,
"rundownAutoAdvance": true,
"rundownActual": 27,
"rundownOver": -573,
"webRemoteEnabled": true,
"webRemoteSessions": 1
}
Timer
| Method | Endpoint | Description |
|---|
| GET | /api/start | Start the countdown or stopwatch. Ignored when a countdown is at 00:00 (set a time first). |
| GET | /api/stop | Stop. |
| GET | /api/toggle | Start if stopped, stop if running. |
| GET | /api/clear | Stop and reset to 00:00. |
| GET | /api/set?minutes=M&seconds=S | Clear and set the countdown to M:S. Either parameter may be omitted. |
| GET | /api/add?minutes=M&seconds=S | Add time (or subtract with negative values). Works while running. |
| GET | /api/endat?time=HH:MM | 1.1 Count down to a wall-clock time (24h, in the display's clock zone; tomorrow if already past) and start. |
Modes
| Method | Endpoint | Description |
|---|
| GET | /api/mode/countdown | Countdown mode (also leaves clock or stopwatch mode). |
| GET | /api/mode/local | Show the clock instead of a timer. |
| GET | /api/countup/on | Stopwatch mode on. |
| GET | /api/countup/off | Stopwatch mode off. |
| GET | /api/milliseconds/on | 1.1 Stopwatch shows MM:SS.mmm. |
| GET | /api/milliseconds/off | 1.1 Stopwatch shows MM:SS. |
Countdown Options
| Method | Endpoint | Description |
|---|
| GET | /api/wrapup?minutes=M&seconds=S | Yellow light when this much time remains. 0 disables. |
| GET | /api/flash/on | Flash the red light at zero. |
| GET | /api/flash/off | Don't flash the light. |
| GET | /api/flashborder/on | 1.1 Pulse a red glow around the timer box at zero, in addition to the light. |
| GET | /api/flashborder/off | 1.1 Border flash off. |
| GET | /api/stopatzero/on | Hold at 00:00 instead of counting into overtime. |
| GET | /api/stopatzero/off | Count into overtime. |
| GET | /api/sound/on | 1.1 Buzzer when the countdown reaches zero. |
| GET | /api/sound/off | 1.1 Buzzer off. |
| GET | /api/sound/test | 1.1 Play the buzzer now. |
| GET | /api/sound/volume?level=N | 1.2 Buzzer volume, 0 to 100. |
| GET | /api/sound/default | 1.2 Back to the built-in beeps (a custom sound is chosen under Options ▸ Buzzer Sound…). |
| GET | /api/progress/on | 1.1 Progress bar under the digits, on the display and the remote. |
| GET | /api/progress/off | 1.1 Progress bar off. |
| GET | /api/automessage/on | 1.1 Automatically show a message when the countdown reaches zero. |
| GET | /api/automessage/off | 1.1 Auto-message off. |
| GET | /api/automessage?text=… | 1.1 Set the text of that automatic message (default TIME'S UP). |
Messages
| Method | Endpoint | Description |
|---|
| GET | /api/message?text=WRAP%20UP | Show a message (max 6 words). URL-encode the text. Uses the "keep timer visible" preference. |
| GET | /api/message?text=…&withTimer=1 | 1.1 Same, overriding that preference for this message (1 beneath the timer, 0 full screen). |
| GET | /api/message/hide | Retract the message. |
| GET | /api/messagewithtimer/on | 1.1 Preference: messages sit below the timer instead of replacing it. |
| GET | /api/messagewithtimer/off | 1.1 Preference: messages replace the timer. |
| GET | /api/quickmessages | 1.1 List saved quick messages. |
| GET | /api/quickmessage/1 | 1.1 Show quick message slot N. Slots above 6 work too; only 1–6 appear in status. |
Presets
| Method | Endpoint | Description |
|---|
| GET | /api/presets | List presets (name, seconds, wrapUpSeconds). |
| GET | /api/preset/1 | Load preset slot N: clears, sets time and wrap-up. Slots above 5 work too; only 1–5 appear in status. |
| GET | /api/preset/load?name=Keynote | Load a preset by name. |
Rundown
1.2 Cues are numbered from 1 in list order. One cue is live, one is on standby; GO fires the standby cue and moves standby to the one after it.
| Method | Endpoint | Description |
|---|
| GET | /api/rundown | The cue list with each cue's planned time, status, actual run time and over/under. Open without a key. |
| GET | /api/rundown/go | GO: load and start the standby cue, put the following cue on standby. /api/rundown/next does the same. |
| GET | /api/rundown/standby/N | Put cue N on standby, so the next GO fires it. |
| GET | /api/rundown/prev | Load and start the previous cue. |
| GET | /api/rundown/go/N | Load and start cue N. |
| GET | /api/rundown/load/N | Load cue N without starting it. |
| GET | /api/rundown/autoadvance/on | Fire the standby cue automatically when the live one reaches zero (/off to stop). |
| GET | /api/rundown/cuename/on | Show the live cue's name at the top of the display (/off to hide). |
| GET | /api/rundown/reset | Clear every cue's run data and make none live. The list stays. |
| GET | /api/rundown/clear | Delete every cue. |
Display & Clock
| Method | Endpoint | Description |
|---|
| GET | /api/blackout/on | 1.1 Black out the display instantly. The timer keeps running underneath. |
| GET | /api/blackout/off | 1.1 Restore the display. |
| GET | /api/blackout/toggle | 1.1 Toggle blackout — handy for a single button. |
| GET | /api/cornerclock/on | 1.1 Small time-of-day clock in the corner of the display. |
| GET | /api/cornerclock/off | 1.1 Corner clock off. |
| GET | /api/endsat/on | 1.2 Show "Ends 3:45:00 PM" in the top-left corner while a countdown runs, "Ended …" in overtime. |
| GET | /api/endsat/off | 1.2 Ends-at readout off. |
| GET | /api/mirror/N/on | 1.2 Mirror the display onto monitor N (numbered as in /api/displays); /off removes it. |
| GET | /api/background/blue | Blue background for keying. |
| GET | /api/background/black | Black background. |
| GET | /api/clock/12h | 1.1 12-hour clock format. |
| GET | /api/clock/24h | 1.1 24-hour clock format. |
| GET | /api/timezone?tz=Area/City | 1.1 Clock time zone (IANA name such as America/New_York, or system). Also used by /api/endat. |
Web Pages
1.2 Pages for a browser rather than a script. None of them need the API key; the web remote has its own PIN.
| Method | Endpoint | Description |
|---|
| GET | /display | The display as a web page for OBS, vMix or any browser. Add ?bg=black, ?bg=blue or ?bg=transparent to pin the background. |
| GET | /display/events | Server-Sent Events stream of the visual state /display renders from. |
| GET | /remote | The remote as a web page, behind the PIN set under App ▸ Web Remote…. Off by default. |
| GET | /remote/rundown | The rundown for signed-in devices, with a live preview of the display. |
| GET | /remote/logout | Sign this device out of the web remote. |
| GET | /manual | The built-in manual. |
Status Fields
/api/status returns the fields below; /api/events streams the same object.
remainingSeconds — seconds left on the countdown (negative in overtime), or elapsed seconds on the stopwatch.
running — true while the countdown or stopwatch is running.
localMode / countUpMode — clock mode / stopwatch mode.
overtime — true once a countdown has passed zero.
formattedTime — timer as MM:SS (absolute value). Unchanged since 1.0.
formattedTimeSigned — timer as MM:SS, with a leading - in overtime.
lightColor / lightColorHex — gray, green, yellow or red, and the same as a hex color for Companion button styling.
progress — fraction of the countdown remaining, 0 to 1.
wrapUpSeconds — yellow-light threshold in seconds (0 = off).
flashOn, flashBorder, stopAtZero, soundOn, showMilliseconds, showProgress, bgBlue, blackout, cornerClock — the matching options.
messageVisible — a message is on the display. messageWithTimer — the "keep timer visible" preference. messageShownWithTimer — whether the message currently showing uses that layout.
autoMessageAtZero / autoMessageText — the auto-message option and its text.
timeZone / hour12 — clock zone (IANA name or system) and format.
preset_N_name / preset_N_time / presetCount — preset slots 1–5 (empty strings when unused).
quick_N_text / quickCount — quick message slots 1–6.
1.2 showEndsAt / endsAt — the ends-at option and the time it shows. elapsedRunSeconds — whole seconds the clock has actually run since the last clear (pauses excluded). buzzerSound / buzzerVolume — default or custom, and 0–100. apiKeySet — a key is required for changes. mirrors — monitor numbers currently mirroring.
1.2 rundownCount, rundownIndex (live cue, 0 when none), rundownCue / rundownNext (names), rundownStandby, rundownAutoAdvance, rundownActual (seconds the live cue has run), rundownOver (actual minus planned; negative while under).
1.2 webRemoteEnabled / webRemoteSessions — the web remote option and how many devices are signed in.
version — app version.
Quick Test
With StageTime running, try these from a terminal:
# Check current status
curl http://localhost:8088/api/status
# Set timer to 10 minutes
curl http://localhost:8088/api/set?minutes=10
# Start the countdown
curl http://localhost:8088/api/start
# Show a message on screen
curl "http://localhost:8088/api/message?text=WRAP%20UP"
# Black out the display (and bring it back)
curl http://localhost:8088/api/blackout/toggle
# Follow every state change live
curl -N http://localhost:8088/api/events
