1.1 marks endpoints added in StageTime 1.1. Everything from 1.0 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 App ▸ 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.
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. |
Example Response
{
"ok": true,
"version": "1.1.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,
"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
}
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/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 (1–6). |
Presets
| Method | Endpoint | Description |
|---|
| GET | /api/presets | List presets (name, seconds, wrapUpSeconds). |
| GET | /api/preset/1 | Load preset slot N (1–5): clears, sets time and wrap-up. |
| GET | /api/preset/load?name=Keynote | Load a preset by name. |
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/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. |
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.
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