Appearance
Rooms
Rooms, the participants in them, and acting on a live one.
List rooms, newest first
GET /v1/rooms
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit? | query | integer | 1–100. Default 20. |
cursor? | query | string | The nextCursor of the previous page. 1–512 characters. |
active? | query | string | true: rooms not yet ended. false: rooms that have ended. One of true, false. |
name? | query | string | 1–200 characters. |
createdAfter? | query | string (date-time) | Created at or after this instant. |
createdBefore? | query | string (date-time) | Created before this instant. |
Response 200 — A page of rooms.
| Field | Type | Description |
|---|---|---|
data | Room[] | |
nextCursor | string | null | The cursor for the next page; null on the last. |
Errors
| Status | Code |
|---|---|
| 400 | validation_failed, token_ttl_too_long |
| 401 | unauthenticated, token_expired, token_replayed, token_not_yet_valid |
| 403 | permission_denied, app_suspended, quota_exhausted |
| 429 | rate_limited |
| 500 | internal |
Create a room before anyone joins it
POST /v1/rooms
A room is otherwise created by the first join whose token carries roomCreate. Creating it here fixes its mode and metadata first. A room nobody joins ends empty after emptyTimeoutSec. Runs on a signaling node.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Request body application/json
| Field | Type | Description |
|---|---|---|
name? | string | Unique among live rooms; the sid when absent. 1–200 characters. |
mode? | string | Fixed for the room's life. p2p is two seats. One of p2p, sfu. Default "sfu". |
maxParticipants? | integer | 50 unless given; a p2p room is 2. 2–100. |
emptyTimeoutSec? | integer | How long the room lives empty, before anyone joins and after the last leaves. 1–86400. Default 60. |
departureTimeoutSec? | integer | How long a dropped participant keeps its seat; 20 s in sfu, 60 s in p2p, unless given. 1–600. |
metadata? | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
recordingPolicy? | string | on_demand: recorded when POST /v1/rooms/{sid}/recordings asks. always: recorded from the first join, and again on a new media server if the room moves. The application's setting when absent, else off; a p2p room cannot be recorded, so anything but off is refused there. One of off, on_demand, always. |
recordingRequiresConsent? | boolean | Record a participant only once its client acknowledged the recording, which its user chooses to. The application's setting when absent, else false. |
Response 201 — The room, as created.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^RM_[0-9a-f]{20}$. |
name | string | Unique among the tenant's live rooms; the sid when none was given. |
mode | string | Fixed for the room's life. p2p is two seats. One of p2p, sfu. |
maxParticipants | integer | |
emptyTimeoutSec | integer | |
departureTimeoutSec | integer | |
recordingPolicy | string | Whether and when a room may be recorded; fixed at the room's creation. One of off, on_demand, always. |
recordingRequiresConsent | boolean | A participant is recorded only once it acknowledged the recording. |
metadata | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
numParticipants | integer | Seats not yet left. |
createdAt | string (date-time) | |
startedAt | string (date-time) | null | |
endedAt | string (date-time) | null | |
endReason | string | null | One of empty, api, max_duration, node_failure, quota. |
participants? | Participant[] | On a read of one room only. |
Errors
Read one room, with the participants in it now and their live tracks
GET /v1/rooms/{sid}
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string |
Response 200 — The room.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^RM_[0-9a-f]{20}$. |
name | string | Unique among the tenant's live rooms; the sid when none was given. |
mode | string | Fixed for the room's life. p2p is two seats. One of p2p, sfu. |
maxParticipants | integer | |
emptyTimeoutSec | integer | |
departureTimeoutSec | integer | |
recordingPolicy | string | Whether and when a room may be recorded; fixed at the room's creation. One of off, on_demand, always. |
recordingRequiresConsent | boolean | A participant is recorded only once it acknowledged the recording. |
metadata | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
numParticipants | integer | Seats not yet left. |
createdAt | string (date-time) | |
startedAt | string (date-time) | null | |
endedAt | string (date-time) | null | |
endReason | string | null | One of empty, api, max_duration, node_failure, quota. |
participants | Participant[] | On a read of one room only. |
Errors
End a room now
DELETE /v1/rooms/{sid}
Everyone in it leaves as server_evict and stays connected to be reachable; a call over the room ends with it. Ending a room that has already ended is not an error.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string |
Response 204 — The room has ended.
Errors
List a room's participants, in the order they joined
GET /v1/rooms/{sid}/participants
Hidden participants are listed, with hidden true.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string | |
limit? | query | integer | 1–100. Default 20. |
cursor? | query | string | The nextCursor of the previous page. 1–512 characters. |
state? | query | string | live (the default): seats not yet left. all: every joining, with ended tracks. One of live, all. |
Response 200 — A page of participants.
| Field | Type | Description |
|---|---|---|
data | Participant[] | |
nextCursor | string | null | The cursor for the next page; null on the last. |
Errors
Change a live participant's grants or metadata, or mute its tracks
PATCH /v1/rooms/{sid}/participants/{identity}
The tenant's backend may do what a roomAdmin may, on anyone. grants replaces the participant's grants whole, narrowed by the application's grant ceiling as a minted token's are; hidden and room stay what they were when the seat was taken. At least one of grants, metadata or mutedTracks is required.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string | |
identity | path | string | The tenant's opaque identity string, URL-encoded. 1–200 characters. |
Request body application/json
| Field | Type | Description |
|---|---|---|
grants? | Grants | What a participant may do. Every name is one the model has; any other is refused rather than ignored. |
metadata? | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
mutedTracks? | string[] | Track sids to mute, in sfu rooms. A muted track stays muted until its publisher unmutes it. At most 16 items. |
Response 200 — The participant, as it now stands.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^PT_[0-9a-f]{20}$. |
identity | string | |
ref | string | null | The token's ref. |
name | string | null | |
kind | string | One of standard, agent, egress, bridge. |
state | string | One of joining, active, disconnected, left. |
hidden | boolean | |
grants | Grants | What a participant may do. Every name is one the model has; any other is refused rather than ignored. |
metadata | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
joinedAt | string (date-time) | |
leftAt | string (date-time) | null | |
disconnectReason | string | null | One of client_leave, server_evict, timeout, transport_failure, duplicate_identity, quota. |
tracks | Track[] |
Errors
Evict a participant
DELETE /v1/rooms/{sid}/participants/{identity}
Out of the room now, and its socket closed on whichever node holds it.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string | |
identity | path | string | The tenant's opaque identity string, URL-encoded. 1–200 characters. |
Response 204 — Evicted.
Errors
Send a data message into a room from the server
POST /v1/rooms/{sid}/data
How a tenant's backend puts a system message into a call. It arrives with an empty from_identity. The platform never reads the payload.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string |
Request body application/json
| Field | Type | Description |
|---|---|---|
payload | string | At most 15 360 bytes once decoded. |
topic? | string | At most 100 characters. |
to? | string[] | Identities. Absent or empty — everyone in the room. At most 200 items. |
reliable? | boolean | Default true. |
Response 200 — Sent.
| Field | Type | Description |
|---|---|---|
recipients | integer | How many seats it was sent to. |
Errors