Skip to main content
The Runtime API is a set of HTTP endpoints your visual calls from inside Unreal Engine during a live show. It handles the full event lifecycle — opening a session, letting the audience join, recording metrics, and closing it cleanly.

​
When you need it

Use the Runtime API if your visual does any of the following:
  • Starts and ends a named audience session (so the backend tracks it)
  • Lets audience members join the session and receive an attendee token
  • Records custom usage metrics per event (e.g. participant count, round completions)
  • Uses the xRLive audience interaction features that depend on a live event ID
If your visual is purely visual (no audience, no session tracking), you don’t need the Runtime API.

​
How it works

Your visual (Unreal Engine)
    │
    ├─ 1. POST /runtime/clients/token      ← exchange clientId+clientSecret for a Bearer token
    │       └─ returns: accessToken (short-lived)
    │
    ├─ 2. POST /runtime/events/start       ← open a session for this visual
    │       └─ returns: eventId, status, startedAt
    │
    ├─ 3. POST /runtime/events/{id}/join   ← audience member joins (one call per attendee)
    │       └─ returns: eventToken (attendee-scoped)
    │
    ├─ 4. POST /runtime/events/{id}/usage  ← record metrics during the show (optional)
    │
    └─ 5. POST /runtime/events/{id}/end/client  ← close the session

​
Base URL

https://api.xrlive.app/api/v1
All Runtime API requests use this base URL. Your visual makes standard HTTP calls — use xRLive’s HTTP Blueprint nodes or Unreal’s built-in HTTP module.

​
Authentication

The Runtime API uses a two-credential system:
CredentialWhat it isWhere you get it
clientId + clientSecretLong-lived credentials tied to your visualDashboard → Creator → Runtime Clients
accessTokenShort-lived Bearer token (~1 hour)Exchanged at runtime via /runtime/clients/token
Your visual stores the clientId and clientSecret (embed them in your visual config or a data asset). On each show, exchange them for a fresh accessToken, then use that token for all subsequent calls.
Never hardcode clientSecret in a Blueprint string literal that could be visible in the editor. Store it in a config data asset or an environment variable and read it at runtime.

​
Credential management

You create and manage Runtime Client credentials in the xRLive dashboard. → Dashboard → Creator → Runtime Clients

​
Pages in this section

PageWhat it covers
AuthenticateExchange clientId + clientSecret for an access token
Start EventOpen a live session for your visual
Join EventRegister an attendee and get their event token
End EventClose the session when the show ends
Record UsagePush custom metrics during the event