Starting an event creates a session record on the backend tied to your visual. The returned eventId is used in all subsequent calls (join, end, usage).
Endpoint
POST /api/v1/runtime/events/start
Authorization: Bearer <accessToken> (from Authenticate)
Request body
{
"visualId": "vis_xxxxxxxxxxxxxxxx",
"runtimeMode": "LIVE"
}
| Field | Type | Required | Description |
|---|
visualId | string | ✓ | The ID of your visual (visible in the dashboard under your visual’s details) |
runtimeMode | string | — | "LIVE" for a real show, "DEMO" for testing. Defaults to "LIVE" |
If your Runtime Client credential is already scoped to a specific visual (set at creation time), the visualId in the request body can be omitted — it will be inferred from the token.
Response
{
"eventId": "evt_xxxxxxxxxxxxxxxx",
"status": "ACTIVE",
"runtimeMode": "LIVE",
"visualId": "vis_xxxxxxxxxxxxxxxx",
"concurrencyLimit": 5,
"activeEventsBeforeStart": 0,
"startedAt": "2026-04-29T20:00:00Z"
}
| Field | Description |
|---|
eventId | Store this — you’ll need it for join, end, and usage calls |
status | "ACTIVE" — the session is open |
concurrencyLimit | Max simultaneous active events allowed by your plan |
activeEventsBeforeStart | How many events were already running when this one started |
Error responses
| Status | Code | Meaning |
|---|
400 | VISUAL_ID_REQUIRED | visualId missing and not resolvable from token |
401 | INVALID_RUNTIME_CLIENT | Token invalid or expired |
403 | RUNTIME_CLIENT_NOT_AUTHORIZED | Token not authorized for this visual |
403 | CONCURRENCY_LIMIT_REACHED | Too many active events for your plan |
Blueprint flow
Store accessToken (from Authenticate)
↓
HTTP POST /runtime/events/start { visualId, runtimeMode: "LIVE" }
↓
Parse response → store eventId
↓
Show is running — use eventId for join/end/usage
