Skip to main content

Server APIs

LiveKit has built-in APIs that lets you to manage rooms, update and moderate participants. These APIs are designed to be used by your backend.

Room APIs are built on top of Twirp, and differ from a traditional REST interface. Arguments are passed via POSTing JSON body to the endpoints. The APIs are available at /twirp/livekit.RoomService/<MethodName>. For example, ListRooms would be /twirp/livekit.RoomService/ListRooms

Room APIs are fully distributed across multiple nodes. Each instance is capable of fulfilling requests about any room or participant.

APIs

All of the APIs require a signed access token. The token should be set in HTTP headers as

Authorization: Bearer <token>

Our server sdks will include the authentication header automatically.

CreateRoom

Creates a room with settings. Requires roomCreate permission. This method is optional; rooms are created automatically when clients connect to them for the first time.

ParameterTypeDescription
namestringname 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 a room

Returns Room

ListRooms

List rooms that are active on the server. Requires roomList permission.

Returns List<Room>

DeleteRoom

Deletes an existing room by name or id. Requires roomCreate permission. DeleteRoom will disconnect all participants that are currently in the room.

ParameterTypeDescription
roomstringname of the room

ListParticipants

Lists participants in a room, Requires roomAdmin

ParameterTypeDescription
roomstringname of the room

Returns List<ParticipantInfo>

GetParticipant

Gets information on a specific participant, Requires roomAdmin

ParameterTypeDescription
roomstringname of the room
identitystringidentity of the participant

Returns ParticipantInfo

RemoveParticipant

Removes a participant from room. Requires roomAdmin

ParameterTypeDescription
roomstringname of the room
identitystringidentity of the participant

MutePublishedTrack

Mute/unmute a participant's track, Requires roomAdmin

ParameterTypeDescription
roomstringname of the room
identitystring
track_sidstringsid of the track to mute
mutedboolset to true to mute, false to unmute

UpdateParticipant

Update participant metadata, will cause updates to be broadcasted to everyone in the room. Requires roomAdmin

ParameterTypeDescription
roomstring
identitystring
metadatastringmetadata to update. skipping updates if left empty
permissionParticipantPermissionset to update the participant's permissions

UpdateSubscriptions

Subscribes or unsubscribe a participant from tracks

ParameterTypeDescription
roomstring
identitystring
track_sidsList<[string]>list of sids of tracks
subscribeboolset to true to subscribe, false to unsubscribe from tracks

SendData

Sends data messages to participants, triggering onDataReceived event on clients.

ParameterTypeDescription
roomstring
databytes
kindenumreliable or lossy
destination_sidsList<[string]>list of participant sids to send to, sends to everyone when left blank

Types

Room

FieldType
sidstring
namestring
empty_timeoutstring
max_participantsstring
creation_timestring
turn_passwordstring

ParticipantInfo

FieldTypeDescription
sidstringserver generated identifier
identitystringclient provided identity
stateTrackInfo_State
tracksList<TrackInfo>tracks published by participant
metadatastring
joined_atint64timestamp when participant joined room

TrackInfo

FieldTypeDescription
sidstringserver generated identifier
typeTrackTypeaudio or video
namestringname given at publish time
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

ParticipantPermission

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