Server / Room Management

Server APIs

On this page

Overview

Endpoints

Authorization header

Post body

RoomService APIs

CreateRoom

ListRooms

DeleteRoom

ListParticipants

GetParticipant

RemoveParticipant

MutePublishedTrack

UpdateParticipant

UpdateSubscriptions

UpdateRoomMetadata

SendData

Egress APIs

Types

Room

ParticipantInfo

TrackInfo

ParticipantPermission

VideoLayer

ParticipantInfo_State

TrackType

TrackSource

VideoQuality

Overview

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.

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

Endpoints

LiveKit APIs are built with Twirp, and differ from a traditional REST interface. Arguments are passed via POSTing JSON body to the endpoints.

Each API is accessible via /twirp/livekit.<Service>/<MethodName>

  • Room Service: /twirp/livekit.RoomService/<MethodName>
  • Egress: /twirp/livekit.Egress/<MethodName>

Authorization header

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.

Post body

Twirp expects each request to be a HTTP POST. The body of the request should be a JSON object (application/json) containing parameters specific to each request. For requests that takes no parameters, an empty {} body should be used.

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

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.

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 a room
metadatastringinitial metadata to assign to room
node_idstringoverride node selection, for advanced users

ListRooms

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

Returns List<Room>

ParameterTypeRequiredDescription
namesList<string>when passed in, only returns room with matching names

DeleteRoom

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

ParameterTypeRequiredDescription
roomstringyesname of the room

ListParticipants

Lists participants in a room, Requires roomAdmin

ParameterTypeRequiredDescription
roomstringyesname of the room

Returns List<ParticipantInfo>

GetParticipant

Gets information on a specific participant, Requires roomAdmin

ParameterTypeRequiredDescription
roomstringyesname of the room
identitystringyesidentity of the participant

Returns ParticipantInfo

RemoveParticipant

Removes a participant from room. Requires roomAdmin

ParameterTypeRequiredDescription
roomstringyesname of the room
identitystringyesidentity of the participant

MutePublishedTrack

Mute/unmute a participant's track. Requires roomAdmin

Due to privacy, server is configured to disallow remote unmute of tracks. To enable unmute from server API, 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 participant metadata, will cause updates to be broadcasted to everyone in the room. Requires roomAdmin

ParameterTypeRequiredDescription
roomstringyes
identitystringyes
metadatastringmetadata to update. skipping updates if left empty
permissionParticipantPermissionset to update the participant's permissions

UpdateSubscriptions

Subscribes or unsubscribe a participant from 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, false to unsubscribe from tracks

UpdateRoomMetadata

Update room level metadata. Requires roomAdmin

This API allows you to attach user-defined metadata to a room. Changes to metadata will be broadcasted to all participants in the room.

ParameterTypeRequiredDescription
roomstringyes
metadatastringyesuser-provided payload; opaque to LiveKit

SendData

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

ParameterTypeRequiredDescription
roomstringyes
databytesyes
kindenumyesreliable or lossy
destination_sidsList<[string]>yeslist of participant sids to send to, sends to everyone when left blank

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 would require
metadatastringuser-specified metadata, opaque to LiveKit
num_participantsuint32number of participants currently in room, excludes hidden participants
active_recordingbooltrue if a participant with recorder permission is currently in the room

ParticipantInfo

FieldTypeDescription
sidstringserver generated identifier
identitystringclient provided identity
namestringname given to the participant in access token (optional)
stateParticipantInfo_Stateconnection state of this participant
tracksList<TrackInfo>tracks published by participant
metadatastringuser-specified metadata for the participant
joined_atint64timestamp when participant joined room
permissionParticipantPermissionpermission given to the participant from access token
is_publisherbooltrue if 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 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

VideoLayer

Represents a single simulcast layer in a Track

FieldTypeDescription
qualityVideoQualityhigh, medium, or low
widthuint32
heightuint32

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