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.
Implementation details
We provide server sdks that make it easy to use these APIs. If you prefer to implement your own client, read on.
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.
When creating a room, it's possible to configure automatic recording of the room or individually published tracks. See Auto Egress docs.
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) | |
| egress | RoomEgress | set the room to be recorded or streamed |
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_identities | List<[string]> | yes | list of participant identities 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 | uint32 | number of seconds the room will remain open if no one joins |
| departure_timeout | uint32 | number of seconds the room will remain open after the last participant leaves |
| max_participants | uint32 | maximum number of participants that can be in the room (0 = no limit) |
| creation_time | int64 | unix timestamp (seconds since epoch) when this room was created |
| 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 |
RoomEgress
Used to specify Auto Egress settings when creating a room.
| Field | Type | Description |
|---|---|---|
| room | RoomCompositeEgressRequest | set to start a Room Composite Egress when participant joins, same parameters as StartCompositeEgress API |
| tracks | AutoTrackEgress | set to export each published track automatically |
AutoTrackEgress
| Field | Type | Description |
|---|---|---|
| filepath | string | template to use for file name. see Egress filenames |
| disable_manifest | bool | when set to true, disables uploading of JSON manifests |
| s3 | S3Upload | set when uploading to S3 |
| gcp | GCPUpload | set when uploading to Google Cloud Storage |
| azure | AzureBlobUpload | set when uploading to Azure Blob Storage |
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