Server APIs

Use LiveKit's built-in APIs to manage rooms and participants in your backend.

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

ParameterTypeRequiredDescription
namestringyesname of the room
empty_timeoutuint32number of seconds to keep the room open if no one joins
max_participantsuint32limit number of participants that can be in the room
metadatastringinitial metadata to assign to the room
node_idstringoverride node selection (note: for advanced users)
egressRoomEgressset the room to be recorded or streamed

ListRooms

List rooms that are active/open. Requires roomList permission.

Returns List<Room>

ParameterTypeRequiredDescription
namesList<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.

ParameterTypeRequiredDescription
roomstringyesname of the room

ListParticipants

List participants in a room, Requires roomAdmin

ParameterTypeRequiredDescription
roomstringyesname of the room

Returns List<ParticipantInfo>

GetParticipant

Get information about a specific participant in a room, Requires roomAdmin

ParameterTypeRequiredDescription
roomstringyesname of the room
identitystringyesidentity of the participant

Returns ParticipantInfo

RemoveParticipant

Remove a participant from a room. Requires roomAdmin

ParameterTypeRequiredDescription
roomstringyesname of the room
identitystringyesidentity 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.

ParameterTypeRequiredDescription
roomstringyesname of the room
identitystringyes
track_sidstringyessid of the track to mute
mutedboolyesset 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

ParameterTypeRequiredDescription
roomstringyes
identitystringyes
metadatastringuser-provided payload, an empty value is equivalent to a no-op
permissionParticipantPermissionset 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.

ParameterTypeRequiredDescription
roomstringyes
identitystringyes
track_sidsList<string>yeslist of sids of tracks
subscribeboolyesset 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

ParameterTypeRequiredDescription
roomstringyes
metadatastringyesuser-provided payload; opaque to LiveKit

SendData

Send data messages to one or more participants. Sending a data message will trigger onDataReceived on connected clients.

ParameterTypeRequiredDescription
roomstringyes
databytesyes
kindenumyesreliable or lossy
destination_identitiesList<[string]>yeslist of participant identities to receive message, leave blank to send the message to everyone

Egress APIs

See Egress API

Types

Room

FieldTypeDescription
sidstringunique session ID
namestring
empty_timeoutstring
max_participantsstring
creation_timestring
turn_passwordstringpassword that the embedded TURN server requires
metadatastringuser-specified metadata, opaque to LiveKit
num_participantsuint32number of participants currently in the room, excludes hidden participants
active_recordingbooltrue if a participant with recorder permission is currently in the room

ParticipantInfo

FieldTypeDescription
sidstringserver-generated identifier
identitystringuser-specified unique identifier for the participant
namestringname given to the participant in access token (optional)
stateParticipantInfo_Stateconnection state of the participant
tracksList<TrackInfo>tracks published by the participant
metadatastringuser-specified metadata for the participant
joined_atint64timestamp when the participant joined room
permissionParticipantPermissionpermission given to the participant via access token
is_publisherbooltrue if the participant has published media or data

TrackInfo

FieldTypeDescription
sidstringserver-generated identifier
typeTrackTypeaudio or video
sourceTrackSourcesource of the Track
namestringname given at publish time (optional)
mime_typestringmime type of codec used
mutedbooltrue if track has been muted by the publisher
widthuint32original width of video (unset for audio)
heightuint32original height of video (unset for audio)
simulcastbooltrue if track is simulcasted
disable_dtxbooltrue if DTX is disabled
layersList<VideoLayer>simulcast or SVC layers in the track

ParticipantPermission

FieldTypeDescription
can_subscribeboolallow the participant to subscribe to other tracks in the room
can_publishboolallow the participant to publish new tracks to the room
can_publish_databoolallow the participant to publish data to the room

VideoLayer

Represents a single simulcast layer in a Track

FieldTypeDescription
qualityVideoQualityhigh, medium, or low
widthuint32
heightuint32

RoomEgress

Used to specify Auto Egress settings when creating a room.

FieldTypeDescription
roomRoomCompositeEgressRequestset to start a Room Composite Egress when participant joins, same parameters as StartCompositeEgress API
tracksAutoTrackEgressset to export each published track automatically

AutoTrackEgress

FieldTypeDescription
filepathstringtemplate to use for file name. see Egress filenames
disable_manifestboolwhen set to true, disables uploading of JSON manifests
s3S3Uploadset when uploading to S3
gcpGCPUploadset when uploading to Google Cloud Storage
azureAzureBlobUploadset 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