LiveKit LogoDocs

Server / Room Management

Server APIs

On this page

OverviewEndpointsAuthorization headerPost bodyRoomService APIsCreateRoomListRoomsDeleteRoomListParticipantsGetParticipantRemoveParticipantMutePublishedTrackUpdateParticipantUpdateSubscriptionsUpdateRoomMetadataSendDataEgress APIsTypesRoomParticipantInfoTrackInfoParticipantPermissionVideoLayerParticipantInfo_StateTrackTypeTrackSourceVideoQuality

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

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)

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_sidsList<[string]>yeslist of participant sids 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

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

Previous

Chevron IconClient: Handling Events
LiveKit logo

Product

SFU

SDKs

Performance

Deployment