Runtime API Overview

How your visual authenticates and manages live event sessions via the xRLive backend

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:

Credential	What it is	Where you get it
clientId + clientSecret	Long-lived credentials tied to your visual	Dashboard → Creator → Runtime Clients
accessToken	Short-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

Page	What it covers
Authenticate	Exchange clientId + clientSecret for an access token
Start Event	Open a live session for your visual
Join Event	Register an attendee and get their event token
End Event	Close the session when the show ends
Record Usage	Push custom metrics during the event