Manage video rooms over REST

Videovideo room lifecycle management

Create a room for each meeting with a member cap and a join window. List and update your rooms over REST, and delete a room when the meeting is over.

Also called room per meeting, scheduled video rooms, conference room CRUD

rest

The claim

create-a-video-room-and-join-from-the-browser makes one room and joins it. This recipe is the rest of a room’s life. The vendored REST spec, tools/openapi/rest.json, is the authority.

Why it holds

POST /api/fabric/resources/conference_rooms requires name and enable_room_previews. max_members is 0 to 300. join_from and join_until bound when joining works, remove_at empties the room at a time, and remove_after_seconds_elapsed (0 to 200000) removes each participant that long after they joined.
GET on the collection lists rooms, GET .../{id} reads one, and GET /api/fabric/resources/conference_room/{id}/addresses gives the address the browser dials.
PUT .../{id} updates a room and requires enable_room_previews and sync_audio_video on every call, so the recipe reads the room first and sends its current values with the change. The read can return sync_audio_video as null and the update does not accept null, so an unset flag is sent as false.
DELETE .../{id} answers 204.

The SDKs wrap the five as client.fabric.conference_rooms in Python and client.fabric.conferenceRooms in TypeScript. The helpers refuse a cap or a removal delay outside the spec’s bounds before any request, because the platform would answer 422.

How it works

def create_room(name, max_members=None, join_from=None, join_until=None, remove_at=None):
    body = {"name": name, "display_name": name, "enable_room_previews": False}
    if max_members is not None:
        body["max_members"] = _bounded("max_members", max_members, MAX_MEMBERS)
    ...
    return client.fabric.conference_rooms.create(**body)

def update_room(room_id, **changes):
    current = get_room(room_id)["conference_room"]
    body = {"enable_room_previews": current["enable_room_previews"],
            "sync_audio_video": current["sync_audio_video"], **changes}
    return client.fabric.conference_rooms.update(room_id, **body)   # a PUT

What the platform receives for a room that opens at 08:50, locks at 09:30 and empties at 10:00:

POST /api/fabric/resources/conference_rooms
{"name": "standup-0900", "display_name": "standup-0900", "enable_room_previews": false,
 "max_members": 12, "join_from": "2026-11-03T08:50:00Z",
 "join_until": "2026-11-03T09:30:00Z", "remove_at": "2026-11-03T10:00:00Z"}

The response carries the room’s id, which the other four calls take. Its address is /public/<name>, and the addresses call confirms it.

Limitations

The verifier proves the requests, not the room. The spec says joining before join_from “will result in failure to join”; what a browser sees at that moment is live behaviour. What happens to participants when a room is deleted while they are in it is not documented, so use remove_at to end a session. Who was in a room and when is the room sessions API, /api/video/room_sessions, which this recipe does not touch.

What to change first

Pass record_on_start=True to create_room so every session of the room is recorded, then read the recordings with record-a-video-room.

Where this sits

Before this

Create a video room and join from the browser

Record a video room Add a phone caller to a video room

python/app.py

"""Manage video rooms over REST.

A video room is a Fabric Conference Room resource, and one REST family creates,
lists, reads, updates and deletes it: /api/fabric/resources/conference_rooms.
A room per meeting is a create with a member cap and a join window. A meeting
that is over is a delete. The SDK wraps the calls as
client.fabric.conference_rooms.

Written against signalwire-sdk 3.0.1 (RestClient.fabric) and the vendored REST
spec, tools/openapi/rest.json.

    python app.py create standup-0900 --members 12 --opens 2026-11-03T08:50:00Z
    python app.py list
    python app.py show <room_id>
    python app.py update <room_id> --members 20
    python app.py delete <room_id>
"""
import argparse
import json
import os

from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

client = RestClient()

# The spec's bounds: max_members is 0 to 300, remove_after_seconds_elapsed is
# 0 to 200000. Outside them the platform answers 422, so the helpers refuse
# the value before any request is made.
MAX_MEMBERS = 300
MAX_REMOVE_AFTER = 200_000


def _bounded(key, value, top):
    value = int(value)
    if not 0 <= value <= top:
        raise ValueError(f"{key} must be between 0 and {top}, not {value}")
    return value


def create_room(name, max_members=None, join_from=None, join_until=None,
                remove_at=None, remove_after_seconds_elapsed=None, **options):
    """A room per meeting.

    `max_members` caps the room. `join_from` and `join_until` bound when joining
    works, `remove_at` empties the room at a time, and
    `remove_after_seconds_elapsed` removes each participant that long after
    they joined. Times are ISO 8601 with a zone. `enable_room_previews` is the
    one other field the create requires.
    """
    body = {"name": name,
            "display_name": options.pop("display_name", name),
            "enable_room_previews": options.pop("enable_room_previews", False)}
    body.update(options)
    if max_members is not None:
        body["max_members"] = _bounded("max_members", max_members, MAX_MEMBERS)
    for key, value in (("join_from", join_from), ("join_until", join_until),
                       ("remove_at", remove_at)):
        if value:
            body[key] = value
    if remove_after_seconds_elapsed is not None:
        body["remove_after_seconds_elapsed"] = _bounded(
            "remove_after_seconds_elapsed", remove_after_seconds_elapsed,
            MAX_REMOVE_AFTER)
    return client.fabric.conference_rooms.create(**body)


def list_rooms():
    """Every conference room in the project."""
    return client.fabric.conference_rooms.list()


def get_room(room_id):
    return client.fabric.conference_rooms.get(room_id)


def addresses_of(room_id):
    """The addresses a room answers at; the browser dials one of these."""
    return client.fabric.conference_rooms.list_addresses(room_id)


def update_room(room_id, **changes):
    """The update is a PUT, and the spec requires `enable_room_previews` and
    `sync_audio_video` on every PUT. An update that changes neither has to
    carry them anyway, so read the room first and send its current values.
    The response schema lets `sync_audio_video` come back null; the request
    schema does not take null, so an unset flag is sent as False."""
    current = get_room(room_id)["conference_room"]
    body = {"enable_room_previews": current.get("enable_room_previews") is True,
            "sync_audio_video": current.get("sync_audio_video") is True}
    if "max_members" in changes:
        changes["max_members"] = _bounded("max_members", changes["max_members"],
                                          MAX_MEMBERS)
    body.update(changes)
    return client.fabric.conference_rooms.update(room_id, **body)


def delete_room(room_id):
    """A DELETE by id. The platform answers 204 with no body."""
    client.fabric.conference_rooms.delete(room_id)
    return {"deleted": room_id}


def main(argv=None):
    p = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    sub = p.add_subparsers(dest="cmd", required=True)
    c = sub.add_parser("create")
    c.add_argument("name")
    c.add_argument("--members", type=int)
    c.add_argument("--opens", help="join_from, ISO 8601")
    c.add_argument("--closes", help="join_until, ISO 8601")
    c.add_argument("--ends", help="remove_at, ISO 8601")
    sub.add_parser("list")
    sub.add_parser("show").add_argument("room_id")
    u = sub.add_parser("update")
    u.add_argument("room_id")
    u.add_argument("--members", type=int)
    u.add_argument("--display-name")
    sub.add_parser("delete").add_argument("room_id")
    a = p.parse_args(argv)

    if a.cmd == "create":
        out = create_room(a.name, max_members=a.members, join_from=a.opens,
                          join_until=a.closes, remove_at=a.ends)
    elif a.cmd == "list":
        out = list_rooms()
    elif a.cmd == "show":
        out = {"room": get_room(a.room_id), "addresses": addresses_of(a.room_id)}
    elif a.cmd == "update":
        changes = {}
        if a.members is not None:
            changes["max_members"] = a.members
        if a.display_name:
            changes["display_name"] = a.display_name
        out = update_room(a.room_id, **changes)
    else:
        out = delete_room(a.room_id)
    print(json.dumps(out, indent=2))


if __name__ == "__main__":
    main()

/**
 * Manage video rooms over REST.
 *
 * A video room is a Fabric Conference Room resource, and one REST family
 * creates, lists, reads, updates and deletes it:
 * /api/fabric/resources/conference_rooms. A room per meeting is a create with
 * a member cap and a join window. A meeting that is over is a delete. The SDK
 * wraps the calls as client.fabric.conferenceRooms.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient.fabric).
 *
 *     npm start create standup-0900 12 2026-11-03T08:50:00Z 2026-11-03T09:30:00Z
 *     npm start list
 *     npm start show <room_id>
 *     npm start update <room_id> 20
 *     npm start delete <room_id>
 */
import "dotenv/config";
import { RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();

// The spec's bounds: max_members is 0 to 300, remove_after_seconds_elapsed is
// 0 to 200000. Outside them the platform answers 422, so the helpers refuse
// the value before any request is made.
export const MAX_MEMBERS = 300;
export const MAX_REMOVE_AFTER = 200_000;

export interface RoomPlan {
  name: string;
  display_name?: string;
  enable_room_previews?: boolean;
  max_members?: number;
  join_from?: string;
  join_until?: string;
  remove_at?: string;
  remove_after_seconds_elapsed?: number;
  [option: string]: unknown;
}

type Room = Record<string, unknown>;

function bounded(key: string, value: number, top: number): number {
  if (!Number.isInteger(value) || value < 0 || value > top) {
    throw new Error(`${key} must be between 0 and ${top}, not ${value}`);
  }
  return value;
}

/**
 * A room per meeting. `max_members` caps the room, `join_from` and
 * `join_until` bound when joining works, `remove_at` empties the room at a
 * time, and `remove_after_seconds_elapsed` removes each participant that long
 * after they joined. Times are ISO 8601 with a zone. `enable_room_previews`
 * is the one other field the create requires.
 */
export async function createRoom(plan: RoomPlan): Promise<Room> {
  const { max_members, remove_after_seconds_elapsed, ...rest } = plan;
  const body: Room = {
    ...rest,
    display_name: plan.display_name ?? plan.name,
    enable_room_previews: plan.enable_room_previews ?? false,
  };
  if (max_members !== undefined) {
    body["max_members"] = bounded("max_members", max_members, MAX_MEMBERS);
  }
  if (remove_after_seconds_elapsed !== undefined) {
    body["remove_after_seconds_elapsed"] = bounded(
      "remove_after_seconds_elapsed", remove_after_seconds_elapsed, MAX_REMOVE_AFTER);
  }
  return client.fabric.conferenceRooms.create(body);
}

/** Every conference room in the project. */
export async function listRooms(): Promise<Room> {
  return client.fabric.conferenceRooms.list();
}

export async function getRoom(roomId: string): Promise<Room> {
  return client.fabric.conferenceRooms.get(roomId);
}

/** The addresses a room answers at; the browser dials one of these. */
export async function addressesOf(roomId: string): Promise<Room> {
  return client.fabric.conferenceRooms.listAddresses(roomId);
}

/**
 * The update is a PUT, and the spec requires `enable_room_previews` and
 * `sync_audio_video` on every PUT. An update that changes neither has to
 * carry them anyway, so read the room first and send its current values. The
 * response schema lets sync_audio_video come back null; the request schema
 * does not take null, so an unset flag is sent as false.
 */
export async function updateRoom(roomId: string, changes: Room): Promise<Room> {
  const current = (await getRoom(roomId))["conference_room"] as Room;
  const body: Room = {
    enable_room_previews: current["enable_room_previews"] === true,
    sync_audio_video: current["sync_audio_video"] === true,
    ...changes,
  };
  if (typeof changes["max_members"] === "number") {
    body["max_members"] = bounded("max_members", changes["max_members"], MAX_MEMBERS);
  }
  return client.fabric.conferenceRooms.update(roomId, body);
}

/** A DELETE by id. The platform answers 204 with no body. */
export async function deleteRoom(roomId: string): Promise<{ deleted: string }> {
  await client.fabric.conferenceRooms.delete(roomId);
  return { deleted: roomId };
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, a, b, c, d] = process.argv.slice(2);
  let out: unknown;
  if (cmd === "create" && a) {
    out = await createRoom({ name: a, max_members: b ? Number(b) : undefined,
                             join_from: c, join_until: d });
  } else if (cmd === "list") {
    out = await listRooms();
  } else if (cmd === "show" && a) {
    out = { room: await getRoom(a), addresses: await addressesOf(a) };
  } else if (cmd === "update" && a && b) {
    out = await updateRoom(a, { max_members: Number(b) });
  } else if (cmd === "delete" && a) {
    out = await deleteRoom(a);
  } else {
    console.error("usage: see the comment at the top of index.ts");
    process.exit(2);
  }
  console.log(JSON.stringify(out, null, 2));
}

Run it

cd python && pip install -r requirements.txt
cp ../.env.example .env
python app.py create standup-0900 --members 12 --opens 2026-11-03T08:50:00Z \
    --closes 2026-11-03T09:30:00Z --ends 2026-11-03T10:00:00Z
python app.py list
python app.py update <room_id> --members 20
python app.py delete <room_id>

The TypeScript surface takes the same commands, on Node 20.18.1 or newer:

cd typescript && npm ci && cp ../.env.example .env
npm start create standup-0900 12 2026-11-03T08:50:00Z 2026-11-03T09:30:00Z

Verify it

python verify.py          # from the recipe folder, not python/

With the HTTP layer recorded, the verifier asserts:

the helpers make the nine documented requests in order: POST, GET the collection, GET one, GET its addresses, GET then PUT twice, DELETE
the create body is exactly name, display_name, enable_room_previews, the cap and the three times, and every key is documented
the spec requires name and enable_room_previews on a create, and the three times are date-time fields
the bounds the helpers refuse at equal the spec’s minimum and maximum for max_members and remove_after_seconds_elapsed
the PUT carries the two fields the spec requires on every update, read back from the room, plus the change
the read schema lets sync_audio_video be null and the update schema does not, and a room read back with it null is updated with false
a cap above the maximum raises before any request
the TypeScript surface sends the same nine requests with the same bodies, reads the 204, and refuses the same cap

Report an issue