Rooms

Programmatically create, list, inspect, and end rooms — and remove participants from them. Every room you manage is scoped to your project: you only ever see and act on your own rooms.

Authentication & scoping

All Rooms endpoints require your secret key as a Bearer token. Secret keys must only be used server-side.

Authorization: Bearer sk_live_...

The room name you send is automatically namespaced to your project internally (as p_<projectId>__<name>), but every response returns your original display name with that prefix stripped. Listing only ever returns rooms in your own project, and named operations are confined to your namespace — there is no way to see or affect another project's rooms.

Create a room

Pre-create a room (optionally configuring limits and metadata) before anyone joins. Rooms are also created on demand when the first participant connects with a token, so this call is optional.

Request body

Example request

curl https://api.relay.welbuiltai.tech/v1/rooms \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-room",
    "maxParticipants": 50,
    "emptyTimeout": 600,
    "metadata": "{\"topic\":\"standup\"}"
  }'

Response

A 201 Created response returns the room object:

{
  "room": "my-room",
  "sid": "RM_xxxxxxxxxxxx",
  "numParticipants": 0,
  "maxParticipants": 50,
  "creationTime": 1718800000,
  "metadata": "{\"topic\":\"standup\"}"
}

List active rooms

Returns every active room in your project.

curl https://api.relay.welbuiltai.tech/v1/rooms \
  -H "Authorization: Bearer sk_live_..."

A 200 OK response wraps the rooms in a rooms array (each entry has the same shape as the create response):

{
  "rooms": [
    {
      "room": "my-room",
      "sid": "RM_xxxxxxxxxxxx",
      "numParticipants": 3,
      "maxParticipants": 50,
      "creationTime": 1718800000,
      "metadata": ""
    }
  ]
}

Inspect a room

Returns a single room plus the list of participants currently connected. Responds 404 not_found if the room does not exist in your project.

curl https://api.relay.welbuiltai.tech/v1/rooms/my-room \
  -H "Authorization: Bearer sk_live_..."

A 200 OK response includes a participants array alongside the room fields:

{
  "room": "my-room",
  "sid": "RM_xxxxxxxxxxxx",
  "numParticipants": 1,
  "maxParticipants": 50,
  "creationTime": 1718800000,
  "metadata": "",
  "participants": [
    {
      "identity": "user-123",
      "name": "Ada Lovelace",
      "state": 2,
      "joinedAt": 1718800050,
      "tracks": 2
    }
  ]
}

Participant fields

End a room

Ends the room and disconnects everyone in it. This is idempotent — deleting a room that no longer exists still succeeds.

curl -X DELETE https://api.relay.welbuiltai.tech/v1/rooms/my-room \
  -H "Authorization: Bearer sk_live_..."

{
  "ended": true
}

Remove a participant

Forcibly disconnects a single participant (by their identity) from a room. Responds 404 not_found if the participant is not in the room.

curl -X DELETE \
  https://api.relay.welbuiltai.tech/v1/rooms/my-room/participants/user-123 \
  -H "Authorization: Bearer sk_live_..."

{
  "removed": true
}

Errors

• 401 unauthorized — the API key is missing, invalid, or revoked.
• 422 validation_error / invalid_request — the request body or a path parameter (room name) failed validation.
• 404 not_found — the room (on inspect) or participant (on remove) does not exist in your project.
• 502 livekit_error — the upstream realtime service returned an error.

{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "Room not found"
  }
}