Overview
StageTime includes a built-in HTTP API that binds to 0.0.0.0 on the configured port (default 8088). All responses are JSON with CORS headers. Accessible from any device on the same network. Change the port from App → Change API Port… in the menu bar.
Timer Control
| Method | Endpoint | Description |
|---|
| GET | /api/start | Start the countdown. |
| GET | /api/stop | Pause the countdown. |
| GET | /api/toggle | Toggle start / stop. |
| GET | /api/clear | Reset the timer to 00:00. |
Set & Adjust Time
| Method | Endpoint | Description |
|---|
| GET | /api/set?minutes=N | Set the timer to N minutes. Also accepts seconds. |
| GET | /api/set?minutes=N&seconds=S | Set timer to N minutes and S seconds. |
| GET | /api/add?minutes=N | Add N minutes (use negative values to subtract). |
| GET | /api/add?seconds=S | Add S seconds (use negative values to subtract). |
Display Modes
| Method | Endpoint | Description |
|---|
| GET | /api/mode/countdown | Switch to countdown mode. |
| GET | /api/mode/local | Switch to local time display. |
| GET | /api/countup/on | Enable count-up (stopwatch) mode. |
| GET | /api/countup/off | Disable count-up mode. |
Messages
| Method | Endpoint | Description |
|---|
| GET | /api/message?text=WRAP%20UP | Show a message on the display. URL-encode the text. |
| GET | /api/message/hide | Hide the current message. |
Options
| Method | Endpoint | Description |
|---|
| GET | /api/flash/on | Enable flash at zero. |
| GET | /api/flash/off | Disable flash at zero. |
| GET | /api/stopatzero/on | Enable stop at zero. |
| GET | /api/stopatzero/off | Disable stop at zero. |
| GET | /api/wrapup?minutes=2 | Set wrap-up warning to 2 minutes. Also accepts seconds. |
| GET | /api/wrapup?minutes=0&seconds=0 | Disable wrap-up warning. |
| GET | /api/background/blue | Set display background to blue. |
| GET | /api/background/black | Set display background to black. |
Presets
| Method | Endpoint | Description |
|---|
| GET | /api/presets | List all saved presets as a JSON array. |
| GET | /api/preset/1 | Load preset by slot number (1–5). |
| GET | /api/preset/load?name=Keynote | Load preset by name. |
Status
| Method | Endpoint | Description |
|---|
| GET | /api/status | Returns the full current state as JSON. |
Example Response
{
"ok": true,
"remainingSeconds": 573,
"running": true,
"localMode": false,
"countUpMode": false,
"flashOn": false,
"stopAtZero": false,
"wrapUpSeconds": 120,
"messageVisible": false,
"formattedTime": "09:33",
"lightColor": "green",
"lightColorHex": "#00ff00"
}
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"