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