Pro Feature
Documentation
Control your teleprompter, manage scripts, and integrate GoodEvening.tv into your production workflow with a simple REST API.
Base URL
https://api.goodevening.tv/functions/v1 Authentication
All API endpoints require a Pro subscription. You can authenticate with either an API key or a Supabase JWT.
API Key (recommended)
Generate an API key in the app under Settings → API Keys.
The full key is shown once at creation — copy it immediately. Pass it via the
X-API-Key header.
curl https://api.goodevening.tv/functions/v1/teleprompter-scripts \ -H "X-API-Key: ge_ak_YourKeyHere"
JWT (for app integrations)
If you're building a Supabase-native integration, you can use a standard JWT from
supabase.auth.getSession().
curl https://api.goodevening.tv/functions/v1/teleprompter-scripts \ -H "Authorization: Bearer YOUR_JWT" \ -H "apikey: YOUR_SUPABASE_ANON_KEY"
Rate Limits
| Requests | 60 per minute per user |
| Bulk commands | Max 20 commands, 2s max delay per command, 15s total budget |
| API keys | 5 active keys per account |
When rate limited, the API returns
429 Too Many Requests.
Wait until the next minute window before retrying.
Scripts
Manage your server-side script library. Scripts created via the API are stored in the cloud and accessible from any device.
/teleprompter-scripts List all your scripts.
curl https://api.goodevening.tv/functions/v1/teleprompter-scripts \ -H "X-API-Key: ge_ak_YourKeyHere"
/teleprompter-scripts?id=SCRIPT_ID Get a single script by ID.
/teleprompter-scripts Create a new script.
curl -X POST https://api.goodevening.tv/functions/v1/teleprompter-scripts \
-H "X-API-Key: ge_ak_YourKeyHere" \
-H "Content-Type: application/json" \
-d '{
"title": "Opening Monologue",
"content": "Good evening, and welcome to the show..."
}' /teleprompter-scripts?id=SCRIPT_ID Update an existing script. Only include fields you want to change.
curl -X PUT "https://api.goodevening.tv/functions/v1/teleprompter-scripts?id=SCRIPT_ID" \
-H "X-API-Key: ge_ak_YourKeyHere" \
-H "Content-Type: application/json" \
-d '{ "title": "Updated Title" }' /teleprompter-scripts?id=SCRIPT_ID Soft-delete a script (can be restored).
Sessions
Create and manage teleprompter relay sessions. A session gives you a room code that connects your API client to a running teleprompter instance.
/teleprompter-session Create a new session. Returns a room code and QR URL.
curl -X POST https://api.goodevening.tv/functions/v1/teleprompter-session \
-H "X-API-Key: ge_ak_YourKeyHere" \
-H "Content-Type: application/json" \
-d '{ "action": "create" }'
# Response:
# { "roomCode": "abc123", "displayCode": "ABC-123", "qrUrl": "https://app.goodevening.tv/remote?room=abc123" } /teleprompter-session?roomCode=CODE Check if a session is active and how many clients are connected.
/teleprompter-session Send a heartbeat to check connected clients.
curl -X POST https://api.goodevening.tv/functions/v1/teleprompter-session \
-H "X-API-Key: ge_ak_YourKeyHere" \
-H "Content-Type: application/json" \
-d '{ "action": "heartbeat", "roomCode": "abc123" }' /teleprompter-session?roomCode=CODE Close a session and clean up the relay room.
Teleprompter Control
Send commands to a running teleprompter. You need an active session room code first.
/teleprompter-control | Command | Parameters | Description |
|---|---|---|
| play | — | Start scrolling |
| pause | — | Stop scrolling |
| toggle | — | Toggle play/pause |
| set_speed | wpm (50–400) | Set scroll speed in words per minute |
| nudge | direction (forward/back), unit (line/paragraph) | Jump forward or back |
| jump_section | label | Jump to a named section |
| reset | — | Reset to beginning |
Example
curl -X POST https://api.goodevening.tv/functions/v1/teleprompter-control \
-H "X-API-Key: ge_ak_YourKeyHere" \
-H "Content-Type: application/json" \
-d '{
"roomCode": "abc123",
"command": "set_speed",
"wpm": 180
}' Bulk Commands
Send up to 20 commands in sequence via the session endpoint. Each command can include an optional
delay_ms
(max 2 seconds) before execution. Total execution is capped at 15 seconds.
curl -X POST https://api.goodevening.tv/functions/v1/teleprompter-session \
-H "X-API-Key: ge_ak_YourKeyHere" \
-H "Content-Type: application/json" \
-d '{
"action": "bulk_command",
"roomCode": "abc123",
"commands": [
{ "command": "set_speed", "wpm": 120 },
{ "command": "play" },
{ "command": "set_speed", "wpm": 180, "delay_ms": 2000 }
]
}' Error Handling
All errors return JSON with an
error field
and a standard HTTP status code.
| Status | Meaning |
|---|---|
| 400 | Bad request — missing or invalid parameters |
| 401 | Unauthorized — invalid or missing API key / JWT |
| 403 | Forbidden — valid credentials but no Pro subscription |
| 404 | Not found — resource doesn't exist or isn't yours |
| 429 | Rate limited — wait until the next minute window |
| 502 | Relay error — teleprompter relay is unreachable |
Quick Start
Full workflow — create a script, start a session, and control the prompter:
# 1. Create a script SCRIPT=$(curl -s -X POST https://api.goodevening.tv/functions/v1/teleprompter-scripts \ -H "X-API-Key: ge_ak_YourKeyHere" \ -H "Content-Type: application/json" \ -d '{ "title": "Demo", "content": "Hello world, this is a test script." }') echo $SCRIPT # 2. Create a session SESSION=$(curl -s -X POST https://api.goodevening.tv/functions/v1/teleprompter-session \ -H "X-API-Key: ge_ak_YourKeyHere" \ -H "Content-Type: application/json" \ -d '{ "action": "create" }') ROOM=$(echo $SESSION | jq -r '.roomCode') echo "Room: $ROOM — open the QR URL on your prompter display" # 3. Start scrolling curl -X POST https://api.goodevening.tv/functions/v1/teleprompter-control \ -H "X-API-Key: ge_ak_YourKeyHere" \ -H "Content-Type: application/json" \ -d "{ \"roomCode\": \"$ROOM\", \"command\": \"play\" }" # 4. Change speed after 3 seconds sleep 3 curl -X POST https://api.goodevening.tv/functions/v1/teleprompter-control \ -H "X-API-Key: ge_ak_YourKeyHere" \ -H "Content-Type: application/json" \ -d "{ \"roomCode\": \"$ROOM\", \"command\": \"set_speed\", \"wpm\": 200 }"