Relay

Getting Started

Quick Start

Create a live video room, generate join tokens for participants, and have users connected in under five minutes.

1. Get an API key

After signing up, create an API key from your dashboard settings. API keys begin with relay_live_ for production and relay_test_ for test mode.

Keep your API key secret. Never expose it in client-side code or public repositories.

2. Create a hall

A hall is a managed video room. Create one with a POST request:

curl
1
2
3
4
5
6
7
8
9
curl -X POST https://api.relay.dev/v1/halls \
  -H "Authorization: Bearer relay_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "engineering-standup",
    "max_participants": 20,
    "record": true,
    "moderation": false
  }'

Response:

json
1
2
3
4
5
{
  "hall_id": "h_01j9x2kp3n...",
  "join_token": "eyJhbGciOiJIUzI1NiIs...",
  "created_at": "2025-04-05T10:00:00Z"
}

The join_token is a signed JWT for the host. Pass it to your frontend WebRTC client (e.g. LiveKit SDK) to connect.

3. Generate participant tokens

For each additional participant joining the room, call the join endpoint from your server:

curl
1
2
3
4
5
6
7
8
curl -X POST https://api.relay.dev/v1/halls/h_01j9x2kp3n.../join \
  -H "Authorization: Bearer relay_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "user_abc123",
    "display_name": "Alice",
    "role": "publisher"
  }'
json
1
2
3
4
{
  "join_token": "eyJhbGciOiJIUzI1NiIs...",
  "livekit_url": "wss://your-relay-media.relay.dev"
}
Always generate join tokens server-side. Never call the Relay API from your frontend — the API key must stay secret.

4. Connect on the frontend

Pass the join_token and livekit_url to the LiveKit client SDK in your frontend:

React (TypeScript)
1
2
3
4
5
6
7
8
9
import { LiveKitRoom, VideoConference } from "@livekit/components-react";

export function Room({ token, serverUrl }: { token: string; serverUrl: string }) {
  return (
    <LiveKitRoom token={token} serverUrl={serverUrl} connect>
      <VideoConference />
    </LiveKitRoom>
  );
}

5. Close the hall

When the session ends, close the hall. This stops any active recording and releases media server resources:

curl
1
2
curl -X DELETE https://api.relay.dev/v1/halls/h_01j9x2kp3n... \
  -H "Authorization: Bearer relay_live_..."

Returns 204 No Content on success.

Next steps

Halls API reference →Set up recording →Enable AI moderation →Receive webhook events →