Start Event

Open a live session for your visual on the xRLive backend

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

Auth: 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