Overview
LiveKit has built-in APIs that let you to manage rooms and update or moderate participants. These APIs are designed for use by your backend and are fully distributed across multiple nodes: any instance is capable of fulfilling requests about any room or participant.
Endpoints
Server APIs are built with Twirp, and differ from a traditional REST interface. Arguments are passed by POSTing a JSON body to an endpoint.
Each API is accessible via /twirp/livekit.<Service>/<MethodName>
- Room Service:
/twirp/livekit.RoomService/<MethodName> - Egress:
/twirp/livekit.Egress/<MethodName>
Authorization header
All endpoints require a signed access token. This token should be set via HTTP header:
Authorization: Bearer <token>
LiveKit's server sdks automatically include the above header.
Post body
Twirp expects a request to be an HTTP POST. The body of the request should be
a JSON object (application/json) containing parameters specific to that request. An empty {} body should be used for a request which takes no parameters.
For example, the following will list the room <room-name>:
curl -X POST <your-host>/twirp/livekit.RoomService/ListRooms \-H "Authorization: Bearer <token-with-roomList>" \-H 'Content-Type: application/json' \-d '{ "names": ["<room-name>"] }'
When passing in parameters, the server will accept either snake_case or camelCase for keys.
RoomService APIs
CreateRoom
Create a room with the specified settings. Requires roomCreate permission.
This method is optional; a room is created automatically when the first participant joins it.
Returns Room
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | yes | name of the room |
| empty_timeout | uint32 | number of seconds to keep the room open if no one joins | |
| max_participants | uint32 | limit number of participants that can be in the room | |
| metadata | string | initial metadata to assign to the room | |
| node_id | string | override node selection (note: for advanced users) |
ListRooms
List rooms that are active/open. Requires roomList permission.
Returns List<Room>
| Parameter | Type | Required | Description |
|---|---|---|---|
| names | List<string> | when passed in, only returns rooms matching one or more specified names |
DeleteRoom
Delete an existing room. Requires roomCreate permission.
DeleteRoom will forcibly disconnect all participants currently in the room.
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | name of the room |
ListParticipants
List participants in a room, Requires roomAdmin
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | name of the room |
Returns List<ParticipantInfo>
GetParticipant
Get information about a specific participant in a room, Requires roomAdmin
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | name of the room |
| identity | string | yes | identity of the participant |
Returns ParticipantInfo
RemoveParticipant
Remove a participant from a room. Requires roomAdmin
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | name of the room |
| identity | string | yes | identity of the participant |
MutePublishedTrack
Mute or unmute a participant's track. Requires roomAdmin
For privacy reasons, LiveKit server is configured by default to disallow the remote unmuting of tracks. To enable it, set enable_remote_unmute to true.
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | name of the room |
| identity | string | yes | |
| track_sid | string | yes | sid of the track to mute |
| muted | bool | yes | set to true to mute, false to unmute |
UpdateParticipant
Update information for a participant. Updating metadata will broadcast the change to all other participants in the room. Requires roomAdmin
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | |
| identity | string | yes | |
| metadata | string | user-provided payload, an empty value is equivalent to a no-op | |
| permission | ParticipantPermission | set to update the participant's permissions |
UpdateSubscriptions
Subscribe or unsubscribe a participant from one or more published tracks. Requires roomAdmin.
As an admin, you can subscribe a participant to a track even if they do not have canSubscribe permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | |
| identity | string | yes | |
| track_sids | List<string> | yes | list of sids of tracks |
| subscribe | bool | yes | set to true to subscribe and false to unsubscribe from tracks |
UpdateRoomMetadata
Update room metadata. A metadata update will be broadcast to all participants in the room. Requires roomAdmin
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | |
| metadata | string | yes | user-provided payload; opaque to LiveKit |
SendData
Send data messages to one or more participants. Sending a data message will trigger onDataReceived on connected clients.
| Parameter | Type | Required | Description |
|---|---|---|---|
| room | string | yes | |
| data | bytes | yes | |
| kind | enum | yes | reliable or lossy |
| destination_sids | List<[string]> | yes | list of participant sids to receive message, leave blank to send the message to everyone |
Egress APIs
See Egress API
Types
Room
| Field | Type | Description |
|---|---|---|
| sid | string | unique session ID |
| name | string | |
| empty_timeout | string | |
| max_participants | string | |
| creation_time | string | |
| turn_password | string | password that the embedded TURN server requires |
| metadata | string | user-specified metadata, opaque to LiveKit |
| num_participants | uint32 | number of participants currently in the room, excludes hidden participants |
| active_recording | bool | true if a participant with recorder permission is currently in the room |
ParticipantInfo
| Field | Type | Description |
|---|---|---|
| sid | string | server-generated identifier |
| identity | string | user-specified unique identifier for the participant |
| name | string | name given to the participant in access token (optional) |
| state | ParticipantInfo_State | connection state of the participant |
| tracks | List<TrackInfo> | tracks published by the participant |
| metadata | string | user-specified metadata for the participant |
| joined_at | int64 | timestamp when the participant joined room |
| permission | ParticipantPermission | permission given to the participant via access token |
| is_publisher | bool | true if the participant has published media or data |
TrackInfo
| Field | Type | Description |
|---|---|---|
| sid | string | server-generated identifier |
| type | TrackType | audio or video |
| source | TrackSource | source of the Track |
| name | string | name given at publish time (optional) |
| mime_type | string | mime type of codec used |
| muted | bool | true if track has been muted by the publisher |
| width | uint32 | original width of video (unset for audio) |
| height | uint32 | original height of video (unset for audio) |
| simulcast | bool | true if track is simulcasted |
| disable_dtx | bool | true if DTX is disabled |
| layers | List<VideoLayer> | simulcast or SVC layers in the track |
ParticipantPermission
| Field | Type | Description |
|---|---|---|
| can_subscribe | bool | allow the participant to subscribe to other tracks in the room |
| can_publish | bool | allow the participant to publish new tracks to the room |
| can_publish_data | bool | allow the participant to publish data to the room |
VideoLayer
Represents a single simulcast layer in a Track
| Field | Type | Description |
|---|---|---|
| quality | VideoQuality | high, medium, or low |
| width | uint32 | |
| height | uint32 |
ParticipantInfo_State
Enum, valid values:
- JOINING: 0
- JOINED: 1
- ACTIVE: 2
- DISCONNECTED: 3
TrackType
Enum, valid values:
- AUDIO: 0
- VIDEO: 1
TrackSource
Enum, valid values:
- UNKNOWN: 0
- CAMERA: 1
- MICROPHONE: 2
- SCREEN_SHARE: 3
- SCREEN_SHARE_AUDIO: 4
VideoQuality
Enum, valid values:
- LOW: 0
- MEDIUM: 1
- HIGH: 2
- OFF: 3
