Relay

Core API

Halls

A hall is a managed video room. Relay provisions the media server, handles signalling, and optionally starts recording — you get a join_token back in one API call.

Create a hall

POST/v1/halls

Creates a new hall and returns a host join token.

Request body

namestringrequired

Human-readable name for the hall. Displayed in the dashboard.

max_participantsinteger

Maximum number of simultaneous participants. Defaults to 50. Capped by your plan limit.

recordboolean

Start recording immediately when the hall opens. Requires S3 credentials configured in Settings. Defaults to false.

moderationboolean

Enable AI content moderation (Google Video Intelligence). Growth plan and above only. Defaults to false.

metadataobject

Arbitrary key-value pairs attached to the hall. Included in webhook payloads.

curl — create a hall
1
2
3
4
5
6
7
8
9
10
curl -X POST https://api.relay.dev/v1/halls \
  -H "Authorization: Bearer relay_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-demo-room",
    "max_participants": 10,
    "record": true,
    "moderation": false,
    "metadata": { "customer_id": "cust_abc" }
  }'

Response

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

The join_token is a signed JWT for the host participant. Pass it to your frontend WebRTC client.

List halls

GET/v1/halls

Returns up to 100 halls ordered by creation time (newest first).

Query parameters

status"active" | "closed"

Filter by hall status. Omit to return all halls.

curl — list active halls
1
2
curl "https://api.relay.dev/v1/halls?status=active" \
  -H "Authorization: Bearer relay_live_..."
json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
  {
    "hall_id": "h_01j9x2kp3n...",
    "name": "product-demo-room",
    "status": "active",
    "max_participants": 10,
    "record": true,
    "moderation": false,
    "participant_count": 3,
    "metadata": { "customer_id": "cust_abc" },
    "created_at": "2025-04-05T10:00:00.000Z",
    "closed_at": null
  }
]

Get a hall

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

Close a hall

DELETE/v1/halls/:hall_id

Closes the hall, stops any active recording, and disconnects all participants. Returns 204 No Content.

curl
1
2
curl -X DELETE https://api.relay.dev/v1/halls/h_01j9x2kp3n... \
  -H "Authorization: Bearer relay_live_..."
Closing a hall is idempotent — calling it on an already-closed hall returns 204 without error.

The hall object

hall_idstring

Unique hall identifier. Prefix: h_

namestring

Human-readable name.

status"active" | "closed"

Current state of the hall.

max_participantsinteger

Participant cap for this hall.

recordboolean

Whether recording is enabled.

moderationboolean

Whether AI moderation is active.

participant_countinteger

Current connected participants (live halls only).

metadataobject

Developer-defined key-value pairs.

created_atdatetime

ISO 8601 creation timestamp.

closed_atdatetime | null

ISO 8601 close timestamp, or null if still active.