Video

Worked room lifecycle: create → token → record → fetch

The run-through every video integration does first: create a room, mint a join token for a participant, record the session, then read the session’s signed playback URL once the room has ended. All requests use your API key (X-API-Key) against https://api.orbit.devotel.io.

1. Create the room

POST /api/v1/video/rooms

Room names must be URL-safe (letters, digits, _, -, 3–200 characters). The response returns the SFU room name plus a host token and the WebSocket URL the host client connects to. Request

{
  "name": "weekly-standup",
  "max_participants": 25
}

{
  "data": {
    "room_name": "tenant_1a2b3c4d_5e6f_7081_weekly-standup",
    "display_name": "weekly-standup",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.host.jwt",
    "url": "wss://media.orbit.devotel.io"
  },
  "meta": {
    "request_id": "req_create_room",
    "timestamp": "2026-08-24T09:15:00.000Z"
  }
}

room_name carries a server-side tenant prefix; display_name is the label you supplied. Feed the returned token and url to a LiveKit client SDK to pick up audio and video — token is a LiveKit access JWT, not an HTTP bearer token. The scheduled-room surface (recurrence, registration, simulive, webinar layouts) is a sibling surface under POST /api/v1/video/rooms-scheduled — its create call also mints the orbit-media egress when recording_enabled: true, so skip step 3 for those rooms.

2. Mint a participant access token

POST /api/v1/video/rooms/{name}/token

One call per participant. participant_name is the identity stamped on the token; can_publish defaults to false (receive-only) and only an owner or admin caller can set it to true. Minting a token under someone else’s identity additionally requires impersonation_reason and an owner or admin role, or the request is rejected with a four-hundred status. Request

{
  "participant_name": "ada@example.com",
  "can_publish": true,
  "participant_tier": "panelist"
}

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.participant.jwt",
    "url": "wss://media.orbit.devotel.io"
  },
  "meta": {
    "request_id": "req_mint_token",
    "timestamp": "2026-08-24T09:16:00.000Z"
  }
}

participant_tier is the finer-grained control: viewer (receive-only), panelist (publishes audio/video), host, and hidden_supervisor. When supplied it overrides can_publish; host and hidden_supervisor require the owner or admin role. When omitted, the legacy can_publish boolean controls the grant exactly as before.

3. Record the session

Recording is started by the host from inside the room (or automatically at room creation for scheduled rooms created with recording_enabled: true), and completed recordings are attached to the room’s session history by the recording webhook. There is no second API call to make here — once the room ends, the recording finalizes asynchronously. Listen for the video.recording.completed webhook event (see Webhook events) or poll GET /api/v1/video/sessions until the session row appears with a non-null recording_url.

4. Fetch the recording asset

GET /api/v1/video/sessions/{id}

Each ended room produces one session row. Fetch it by id — the response carries recording_url as a time-limited signed HTTPS URL ready for a <video> element or download, plus recording_url_expires_at so you know when to re-fetch. A session whose recording has not finalized yet returns recording_url: null.

{
  "data": {
    "id": "vs_2b3c4d5e6f70819a",
    "room_id": "vr_1a2b3c4d5e6f7081",
    "room_name": "weekly-standup",
    "started_at": "2026-08-24T09:16:12.000Z",
    "ended_at": "2026-08-24T09:44:51.000Z",
    "duration_seconds": 1719,
    "max_participants": 25,
    "total_join_events": 7,
    "recording_url": "https://storage.googleapis.com/orbit-recordings-eu/recordings/tenant_1a2b3c4d/vs_2b3c4d5e6f70819a.mp4?X-Goog-Signature=…",
    "recording_url_expires_at": 1787565900000,
    "recording_id": "rec_9f8e7d6c5b4a3162",
    "metadata": {},
    "created_at": "2026-08-24T09:16:12.000Z",
    "updated_at": "2026-08-24T09:45:02.000Z"
  },
  "meta": {
    "request_id": "req_get_session",
    "timestamp": "2026-08-24T09:46:00.000Z"
  }
}

recording_id is the unified-recordings primary key — use it with the Recordings API to mint a time-limited guest share link for a non-account viewer, or to pull the stored transcript. Treat both recording_url and its signature as opaque and re-fetch the session when recording_url_expires_at passes rather than re-signing it yourself.

Response envelopes

Every endpoint on this page answers in one of two envelope shapes, so one error handler covers all four steps above. Success — data carries the payload (a single object, or an array on list endpoints such as GET /api/v1/video/sessions), and meta carries request_id plus timestamp. List endpoints add a pagination block under meta:

{
  "meta": {
    "request_id": "req_list_sessions",
    "timestamp": "2026-08-24T09:46:00.000Z",
    "pagination": {
      "cursor": "eyJs…",
      "has_more": true,
      "total": null
    }
  }
}

While meta.pagination.has_more is true, pass meta.pagination.cursor back as the cursor query parameter to fetch the next page — the cursor is opaque; keep the same filters across pages and stop when has_more comes back false. Error — failures answer with { error, meta }, where error carries code, status, and message. Validation failures return 422; token privilege violations return 403 in this same shape:

403

{
  "error": {
    "code": "PARTICIPANT_TIER_NOT_PERMITTED",
    "status": 403,
    "message": "Minting a participant token with this tier requires the owner or admin role."
  },
  "meta": {
    "request_id": "req_mint_token",
    "timestamp": "2026-08-24T09:16:00.000Z"
  }
}

Handle PARTICIPANT_TIER_NOT_PERMITTED and IMPERSONATION_NOT_PERMITTED before the generic error path — both mean the caller’s role cannot mint the requested token, and retrying without changing the request will fail the same way.

API Reference

All Endpoints

Worked room lifecycle: create → token → record → fetch

1. Create the room

2. Mint a participant access token

3. Record the session

4. Fetch the recording asset

Response envelopes

​Worked room lifecycle: create → token → record → fetch

​1. Create the room

​2. Mint a participant access token

​3. Record the session

​4. Fetch the recording asset

​Response envelopes

Worked room lifecycle: create → token → record → fetch

1. Create the room

2. Mint a participant access token

3. Record the session

4. Fetch the recording asset

Response envelopes