Room Management

Learn how to create, retrieve, validate, list, deactivate, and end VideoSDK rooms and sessions from your server.

A room is the reusable resource identified by a roomId, while a session represents one live occurrence inside that room.

For the relationship between rooms and sessions, see Rooms, Sessions, Participants, and Streams.

Server-side operations generally fall into two categories:

• Live operations use a roomId and work with the room's active session.
• Historical operations use the sessions resource to access previous sessions and their participants.

Initialize the Server SDK​

All server-side operations on this page use the VideoSDK Server SDK or REST API.

When using a Server SDK, initialize the client with your API key and secret from the VideoSDK dashboard. The SDK uses these credentials to authenticate requests automatically.

When using REST, generate a management token yourself and include it in the Authorization header.

# A management token signed using your API key and secret,
# or a temporary token generated from the dashboard.
export VIDEOSDK_TOKEN="eyJhbGciOi..."

curl \
  -H "Authorization: $VIDEOSDK_TOKEN" \
  https://api.videosdk.live/v2/rooms

import { VideoSDK } from "@videosdk.live/server-sdk";

const client = new VideoSDK({
  apiKey: process.env.VIDEOSDK_API_KEY!,
  secret: process.env.VIDEOSDK_SECRET!,
});

client, err := videosdk.NewClient(
    videosdk.WithAPIKey(os.Getenv("VIDEOSDK_API_KEY")),
    videosdk.WithSecret(os.Getenv("VIDEOSDK_SECRET")),
)

if err != nil {
    log.Fatal(err)
}

ctx := context.Background()

use videosdk::Client;

let client = Client::builder()
    .api_key(std::env::var("VIDEOSDK_API_KEY")?)
    .secret(std::env::var("VIDEOSDK_SECRET")?)
    .build()?;

For installation and environment setup, see the Server SDK introduction.

If you are integrating directly over HTTP, see the REST API reference.

Create a room​

Create a room before participants join.

VideoSDK returns a roomId that clients can use to join the room.

curl -X POST https://api.videosdk.live/v2/rooms \
  -H "Authorization: $VIDEOSDK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "geoFence": "us002" }'

# { "roomId": "abcd-efgh-ijkl", ... }

const room = await client.rooms.create({
  geoFence: "us002",
});

room.roomId; // "abcd-efgh-ijkl"

room, err := client.Rooms.Create(ctx, videosdk.RoomCreateParams{
    GeoFence: videosdk.String(videosdk.RegionUS002),
})

let room = client.rooms().create(videosdk::RoomCreateParams {
    geo_fence: Some(videosdk::Region::US002),
    ..Default::default()
}).await?;

room.room_id; // "abcd-efgh-ijkl"

Room configuration options are optional.

If you provide a customRoomId that already exists, VideoSDK returns the existing room instead of creating another one. This makes it useful for mapping VideoSDK rooms to records in your own system.

List rooms​

Retrieve rooms associated with your VideoSDK account.

You can filter the list using query with an exact roomId or customRoomId.

curl "https://api.videosdk.live/v2/rooms?page=1&perPage=20" \
  -H "Authorization: $VIDEOSDK_TOKEN"

# {
#   "pageInfo": {
#     "currentPage": 1,
#     "lastPage": 5,
#     ...
#   },
#   "data": [
#     {
#       "roomId": "...",
#       "createdAt": "..."
#     }
#   ]
# }

# Use the `page` parameter to paginate manually over REST.

for await (const room of await client.rooms.list()) {
  console.log(room.roomId, room.createdAt);
}

for room, err := range client.Rooms.ListAutoPaging(
    ctx,
    videosdk.RoomListParams{},
) {
    if err != nil {
        return err
    }

    fmt.Println(room.RoomID, room.CreatedAt)
}

use futures_util::StreamExt;

let mut rooms = Box::pin(
    client
        .rooms()
        .list_stream(videosdk::RoomListParams::default())
);

while let Some(room) = rooms.next().await {
    let room = room?;
    println!("{} {:?}", room.room_id, room.created_at);
}

Get or validate a room​

Use get when you want to retrieve an existing room.

Use validate when you only need to determine whether a supplied room identifier is valid.

Both operations accept a roomId or customRoomId.

curl https://api.videosdk.live/v2/rooms/abcd-efgh-ijkl \
  -H "Authorization: $VIDEOSDK_TOKEN"

curl "https://api.videosdk.live/v2/rooms/validate/$USER_INPUT" \
  -H "Authorization: $VIDEOSDK_TOKEN"

const room = await client.rooms.get("abcd-efgh-ijkl");

const {
  valid,
  room: found,
} = await client.rooms.validate(userInput);

room, err := client.Rooms.Get(
    ctx,
    "abcd-efgh-ijkl",
)

result, err := client.Rooms.Validate(
    ctx,
    userInput,
)

if result.Valid {
    // result.Room is the resolved room
}

let room = client
    .rooms()
    .get("abcd-efgh-ijkl")
    .await?;

let result = client
    .rooms()
    .validate(user_input)
    .await?;

if result.valid {
    // result.room is the resolved room
}

Deactivate a room​

Deactivating a room permanently disables it. The room cannot be joined again.

If a session is currently active, VideoSDK disconnects the participants and ends that session as well.

Use the VideoSDK-generated roomId for this operation, not the customRoomId.

curl -X POST https://api.videosdk.live/v2/rooms/deactivate \
  -H "Authorization: $VIDEOSDK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "roomId": "abcd-efgh-ijkl" }'

await client.rooms.end("abcd-efgh-ijkl");

room, err := client.Rooms.End(
    ctx,
    "abcd-efgh-ijkl",
)

let room = client
    .rooms()
    .end("abcd-efgh-ijkl")
    .await?;

Room object​

Room operations such as create, get, list, validate, and end return room information. The end operation is the one that deactivates a room.

Manage sessions​

A room can be reused across multiple calls. Each individual live occurrence is stored as a separate session.

Use the sessions resource when you need to:

• Retrieve previous calls for a room.
• Inspect when a session started or ended.
• Access participant history.
• End the currently active session without disabling the room.

List sessions​

List sessions and optionally filter them by:

• roomId
• customRoomId
• userId
• startDate
• endDate
• status

startDate and endDate use epoch milliseconds.

The supported status values are ongoing and ended.

curl "https://api.videosdk.live/v2/sessions?roomId=$ROOM_ID&page=1&perPage=20" \
  -H "Authorization: $VIDEOSDK_TOKEN"

# {
#   "pageInfo": { ... },
#   "data": [
#     {
#       "id": "...",
#       "start": "...",
#       "end": "...",
#       "status": "ended"
#     }
#   ]
# }

const sessions = await client.sessions.list({
  roomId,
  status: "ended",
});

for await (const session of sessions) {
  console.log(
    session.id,
    session.start,
    session.end
  );
}

for session, err := range client.Sessions.ListAutoPaging(
    ctx,
    videosdk.SessionListParams{
        RoomID: videosdk.String(roomID),
        Status: videosdk.Ptr(videosdk.SessionEnded),
    },
) {
    if err != nil {
        return err
    }

    fmt.Println(
        session.ID,
        session.Start,
        session.End,
    )
}

use futures_util::StreamExt;

let mut sessions = Box::pin(
    client.sessions().list_stream(
        videosdk::SessionListParams {
            room_id: Some(room_id.clone()),
            status: Some(
                videosdk::SessionStatus::ENDED
            ),
            ..Default::default()
        },
    ),
);

while let Some(session) = sessions.next().await {
    let session = session?;
    println!(
        "{} {} {:?}",
        session.id,
        session.start,
        session.end
    );
}

Get a session​

Retrieve a specific session using its unique session ID.

curl https://api.videosdk.live/v2/sessions/session_abc123 \
  -H "Authorization: $VIDEOSDK_TOKEN"

const session = await client.sessions.get(
  "session_abc123"
);

session, err := client.Sessions.Get(
    ctx,
    "session_abc123",
)

let session = client
    .sessions()
    .get("session_abc123")
    .await?;

End a session​

End the current live session without disabling the room.

Participants are disconnected from the active session, but the roomId remains valid and can be reused for a future session.

Provide a roomId or meetingId. You can also provide a sessionId to target a specific session and use force when you need to end it while participants are still connected.

curl -X POST https://api.videosdk.live/v2/sessions/end \
  -H "Authorization: $VIDEOSDK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "roomId": "'"$ROOM_ID"'" }'

# Add "sessionId" to target a specific session.

await client.sessions.end({
  roomId,
  force: true,
});

session, err := client.Sessions.End(
    ctx,
    videosdk.SessionEndParams{
        RoomID: videosdk.String(roomID),
        Force:  videosdk.Bool(true),
    },
)

client.sessions().end(
    videosdk::SessionEndParams {
        room_id: Some(room_id.clone()),
        force: Some(true),
        ..Default::default()
    },
).await?;

Session object​

A session contains information about one live occurrence of a room.

For session statistics and participant-level quality information, see the Sessions reference.

Handle server-side errors​

Server SDK errors provide information that your application can use for logging, retries, and error handling.

Errors can include:

• message - human-readable description.
• code - machine-readable error code.
• requestId - identifier you can provide to VideoSDK support.
• httpStatus - corresponding HTTP status when available.

Network failures and timeouts may not contain an httpStatus.

curl -i https://api.videosdk.live/v2/rooms/does-not-exist \
  -H "Authorization: $VIDEOSDK_TOKEN"

# HTTP/1.1 404 Not Found
# x-request-id: req_...
#
# {
#   "message": "Room not found",
#   "code": "ROOM_NOT_FOUND"
# }

import {
  VideoSDKError,
  RoomNotFoundError,
} from "@videosdk.live/server-sdk";

try {
  await client.rooms.get("does-not-exist");
} catch (err) {
  if (err instanceof RoomNotFoundError) {
    // room doesn't exist
  } else if (err instanceof VideoSDKError) {
    console.error(
      err.httpStatus,
      err.code,
      err.message,
      err.requestId
    );
  }
}

_, err := client.Rooms.Get(
    ctx,
    "does-not-exist",
)

switch {
case videosdk.IsNotFound(err):
    // room doesn't exist

case videosdk.IsRateLimit(err):
    // back off
}

match client
    .rooms()
    .get("does-not-exist")
    .await
{
    Ok(_room) => {}

    Err(err) if err.is_not_found() => {
        // room doesn't exist
    }

    Err(err) if err.is_rate_limit() => {
        // back off
    }

    Err(err) => eprintln!("{err}"),
}

For the complete set of Server SDK errors and error categories, see Error handling.

Next steps​