> ## Documentation Index
> Fetch the complete documentation index at: https://xrlive.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  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.
</Warning>

## Credential management

You create and manage Runtime Client credentials in the xRLive dashboard.

→ [Dashboard → Creator → Runtime Clients](/dashboard/creator/runtime-clients)

## Pages in this section

| Page                                          | What it covers                                       |
| --------------------------------------------- | ---------------------------------------------------- |
| [Authenticate](/sdk/runtime-api/authenticate) | Exchange clientId + clientSecret for an access token |
| [Start Event](/sdk/runtime-api/start-event)   | Open a live session for your visual                  |
| [Join Event](/sdk/runtime-api/join-event)     | Register an attendee and get their event token       |
| [End Event](/sdk/runtime-api/end-event)       | Close the session when the show ends                 |
| [Record Usage](/sdk/runtime-api/record-usage) | Push custom metrics during the event                 |