Room management | LiveKit Documentation

Overview

A Room is a container object representing a LiveKit session. An app, for example an AI agent, a web client, or a mobile app, etc., connects to LiveKit via a room. Any number of participants can join a room and publish audio, video, or data to the room.

Each participant in a room receives updates about changes to other participants in the same room. For example, when a participant adds, removes, or modifies the state (for example, mute) of a track, other participants are notified of this change. This is a powerful mechanism for synchronizing state and fundamental to building any realtime experience.

A room can be created manually via server API, or automatically, when the first participant joins it. Once the last participant leaves a room, it closes after a short delay.

Initialize LiveKitAPI

Room management is handled through the room service on LiveKitAPI, the single entry point to every LiveKit server API. Create it with your API key and secret, or a pre-signed access token for client-side use where the API secret must not be exposed. In most cases, when omitted, the host and credentials fall back to the LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, and LIVEKIT_TOKEN environment variables. Fallback support varies by SDK, so see the tab for your language.

import { LiveKitAPI } from 'livekit-server-sdk';

const api = new LiveKitAPI({
  host: 'https://my.livekit.host',
  apiKey: 'api-key',
  secret: 'secret',
});

uv add livekit-api

from livekit import api

# Reads LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET from the environment.
async with api.LiveKitAPI() as lkapi:
    ...  # use lkapi.room, lkapi.sip, etc.

require 'livekit'

lkapi = LiveKit::LiveKitAPI.new('https://my.livekit.host',
                                api_key: 'api-key', api_secret: 'secret')

import (
  lksdk "github.com/livekit/server-sdk-go/v2"
  "github.com/livekit/protocol/livekit"
)

api, err := lksdk.NewLiveKitAPI(lksdk.WithURL("https://my.livekit.host"),
  lksdk.WithAPIKey("api-key", "secret"))

import io.livekit.server.LiveKitAPI

// createClient reads LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET from
// the environment when omitted. For a pre-signed token (LIVEKIT_TOKEN), use
// LiveKitAPI.createClientWithToken instead.
val api = LiveKitAPI.createClient("https://my.livekit.host", "api-key", "secret")

use livekit_api::services::LiveKitApi;

// The Rust SDK reads only LIVEKIT_API_KEY and LIVEKIT_API_SECRET from the
// environment (via LiveKitApi::new). The host is always explicit, and there's
// no LIVEKIT_TOKEN fallback.
let api = LiveKitApi::with_api_key("https://my.livekit.host", "api-key", "secret");

Create a room

lk room create --empty-timeout 600 myroom

const room = await api.room.createRoom({
  name: 'myroom',
  emptyTimeout: 10 * 60, // 10 minutes
  maxParticipants: 20,
});

from livekit.api import CreateRoomRequest

room = await lkapi.room.create_room(CreateRoomRequest(
  name="myroom",
  empty_timeout=10 * 60,
  max_participants=20,
))

room = lkapi.room.create_room('myroom', empty_timeout: 10 * 60, max_participants: 20)

room, err := api.Room().CreateRoom(context.Background(), &livekit.CreateRoomRequest{
  Name:            "myroom",
  EmptyTimeout:    10 * 60, // 10 minutes
  MaxParticipants: 20,
})

val room = api.room.createRoom(
    name = "myroom",
    emptyTimeout = 10 * 60, // 10 minutes
    maxParticipants = 20,
).execute().body()

use livekit_api::services::room::CreateRoomOptions;

let room = api.room().create_room("myroom", CreateRoomOptions {
    empty_timeout: 10 * 60, // 10 minutes
    max_participants: 20,
    ..Default::default()
}).await?;

List rooms

lk room list

const rooms = await api.room.listRooms();

from livekit.api import ListRoomsRequest

rooms = await lkapi.room.list_rooms(ListRoomsRequest())

rooms = lkapi.room.list_rooms

rooms, err := api.Room().ListRooms(context.Background(), &livekit.ListRoomsRequest{})

val rooms = api.room.listRooms().execute().body()

let rooms = api.room().list_rooms(vec![]).await?;

Delete a room

Deleting a room causes all Participants to be disconnected.

lk room delete myroom

await api.room.deleteRoom('myroom');

from livekit.api import DeleteRoomRequest

await lkapi.room.delete_room(DeleteRoomRequest(room="myroom"))

lkapi.room.delete_room(room: 'myroom')

_, err := api.Room().DeleteRoom(context.Background(), &livekit.DeleteRoomRequest{
  Room: "myroom",
})

api.room.deleteRoom("myroom").execute()

api.room().delete_room("myroom").await?;

Handling errors

A failed server API call surfaces a ServerError carrying the error code, message, and any server-provided metadata. In Node.js, Python, and Ruby it's thrown; in Go, Kotlin, and Rust it's returned (Kotlin decodes it from the response).

import { ServerError } from 'livekit-server-sdk';

try {
  await api.room.createRoom({ name: 'myroom' });
} catch (e) {
  if (e instanceof ServerError) {
    console.error(e.code, e.message);
  }
}

from livekit import api

try:
    await lkapi.room.create_room(api.CreateRoomRequest(name="myroom"))
except api.ServerError as e:
    print(e.code, e.message)

begin
  lkapi.room.create_room('myroom')
rescue LiveKit::ServerError => e
  puts "#{e.code}: #{e.message}"
end

import "errors"

_, err := api.Room().CreateRoom(context.Background(), &livekit.CreateRoomRequest{Name: "myroom"})
var serverErr lksdk.ServerError
if errors.As(err, &serverErr) {
  fmt.Println(serverErr.Code(), serverErr.Msg())
}

import io.livekit.server.ServerError

val response = api.room.createRoom(name = "myroom").execute()
if (!response.isSuccessful) {
    val error = ServerError.from(response)
    println("${error?.code}: ${error?.message}")
}