Video

Worked video room samples

The chain a video integration runs end to end: create a scheduled room, mint a participant access token, list the live participants once the room is open, and read the session record (recording) after the room ends. Every request carries your API key (X-API-Key) against https://api.orbit.devotel.io. Successful responses return { data, meta }; failures return Devotel Orbit’s { error, meta } shape — one handler covers both.

1. Create the room

POST /api/v1/video/rooms-scheduled

Creates a scheduled video room. name is 1–200 characters; setting scheduled_at to a future ISO 8601 time parks the room in scheduled status until first join; omit it to go live now. Gate a live or scheduled room behind recurrence, captions, recording, and a per-tier participant cap — inspect the full body in the operation list above. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "weekly-standup",
  "max_participants": 25,
  "max_duration_minutes": 60
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "weekly-standup",
  "max_participants": 25,
  "max_duration_minutes": 60
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled", headers=headers, json={
  "name": "weekly-standup",
  "max_participants": 25,
  "max_duration_minutes": 60
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled", bytes.NewBuffer([]byte(`{
  "name": "weekly-standup",
  "max_participants": 25,
  "max_duration_minutes": 60
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "name": "weekly-standup",
  "max_participants": 25,
  "max_duration_minutes": 60
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "name": "weekly-standup",
  "max_participants": 25,
  "max_duration_minutes": 60
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "room_id": "3f2b1c9a-9d2e-4f10-8c6a-7b21d44e1a90",
    "room_sid": "RM_4a7c9f2b3e1d48a0b6c5d2e8f1a3b7c9",
    "host_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.host.jwt",
    "ws_url": "wss://media.orbit.devotel.io",
    "composite_egress_id": null,
    "track_egress_id": null,
    "recording_storage": null
  },
  "meta": {
    "request_id": "req_create_room",
    "timestamp": "2026-09-03T09:15:00.000Z"
  }
}

room_id is the UUID you pass to the join (token-mint) and lifecycle calls — persist it. host_token is a LiveKit access JWT for the creator’s own first join; ws_url is the SFU WebSocket endpoint the client SDK connects to (those two are the join URLs — there is no separate url to construct). Egress ids and the storage descriptor populate only when you create the room with recording enabled; null here means recording was not started on create. If scheduled_at was in the future the room stays scheduled until the first participant joins; if it was omitted the room is live now, so composite_egress_id would carry a real id when recording_enabled: true. Cap violations return 400 VIDEO_PARTICIPANTS_CAP_EXCEEDED before any of this happens.

2. Mint the participant token

POST /api/v1/video/rooms-scheduled/{id}/join

One call per participant. identity is who the token is minted for (defaults to your own user id); role is host or participant; participant_tier (viewer / panelist / host / hidden_supervisor) overrides the role-derived grant. Minting under another user’s identity additionally requires an impersonation_reason and the owner or admin role. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}/join" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "identity": "user_abc123",
  "role": "participant",
  "participant_tier": "panelist"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}/join', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "identity": "user_abc123",
  "role": "participant",
  "participant_tier": "panelist"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}/join", headers=headers, json={
  "identity": "user_abc123",
  "role": "participant",
  "participant_tier": "panelist"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}/join", bytes.NewBuffer([]byte(`{
  "identity": "user_abc123",
  "role": "participant",
  "participant_tier": "panelist"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}/join')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "identity": "user_abc123",
  "role": "participant",
  "participant_tier": "panelist"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}/join');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "identity": "user_abc123",
  "role": "participant",
  "participant_tier": "panelist"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.participant.jwt",
    "token_type": "livekit_access_token",
    "ws_url": "wss://media.orbit.devotel.io",
    "livekit_url": "wss://media.orbit.devotel.io",
    "room_sid": "RM_4a7c9f2b3e1d48a0b6c5d2e8f1a3b7c9",
    "participant_tier": "panelist",
    "lobby_downgraded": false,
    "permissions": {
      "can_publish": true,
      "can_subscribe": true,
      "can_publish_data": true,
      "hidden": false,
      "room_admin": false
    },
    "expires_at": "2026-09-03T10:15:00.000Z",
    "expires_in_seconds": 3600
  },
  "meta": {
    "request_id": "req_mint_token",
    "timestamp": "2026-09-03T09:15:00.000Z"
  }
}

Feed token and ws_url to a LiveKit client SDK — the JWT is not an HTTP bearer. expires_at / expires_in_seconds tell your client when to re-mint before the leg drops mid-session. participant_tier and permissions reflect the EFFECTIVE grant: an armed waiting-room lobby downgrades the token to receive-only (lobby_downgraded: true), and the participant/host role downgrade also narrows what the tier schema accepts. See guides/video-room-access-tokens for the token-claim semantics end to end.

3. Read participants and the session record

List the live roster once the room is open, then pull the ended session to read its recording.

GET /api/v1/video/rooms-scheduled/{id}

Returns room (the scheduled-room row, with settings.ingresses stripped for non-admin callers) plus the current participants list.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{id}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "room": {
      "id": "3f2b1c9a-9d2e-4f10-8c6a-7b21d44e1a90",
      "name": "weekly-standup",
      "status": "live",
      "max_participants": 25,
      "recording_url": null,
      "recording_url_expires_at": null
    },
    "participants": [
      {
        "identity": "user_abc123",
        "name": "Ada",
        "joined_at": "2026-09-03T09:16:12.000Z",
        "is_publishing": true
      }
    ]
  },
  "meta": {
    "request_id": "req_read_room",
    "timestamp": "2026-09-03T09:16:12.000Z"
  }
}

After the room ends, one session row per ended room carries the recording:

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

{
  "data": {
    "id": "vs_2b3c4d5e6f70819a",
    "room_id": "3f2b1c9a-9d2e-4f10-8c6a-7b21d44e1a90",
    "room_name": "weekly-standup",
    "started_at": "2026-09-03T09:16:12.000Z",
    "ended_at": "2026-09-03T09:44:51.000Z",
    "duration_seconds": 1719,
    "max_participants": 25,
    "total_join_events": 7,
    "recording_url": "https://storage.googleapis.com/orbit-recordings-eu/recordings/vs_2b3c4d5e6f70819a.mp4?X-Goog-Signature=sample",
    "recording_url_expires_at": 1787565900000,
    "recording_id": "rec_9f8e7d6c5b4a3162"
  },
  "meta": {
    "request_id": "req_get_session",
    "timestamp": "2026-09-03T09:46:00.000Z"
  }
}

recording_url is a time-limited signed HTTPS URL ready for a <video> element or download; recording_url_expires_at is when to re-fetch the session rather than re-signing the URL yourself. A session whose recording has not finalized yet returns recording_url: null. recording_id is the unified-recordings primary key you use with the Recordings API to mint a guest share link. Poll until it appears, or listen for the video.recording.completed webhook event.

4. Errors

Failures answer { error, meta }. error carries code, status, and message; meta.request_id + timestamp mirror every request. 404 — room expired or unknown. Fetching (GET /rooms-scheduled/{id}) or minting against a room past its expiry hits NOT_FOUND before any SFU work runs. Expiry is the max_duration_minutes TTL you set on create (or the platform default on the room row), so re-create the room rather than retrying the token call.

404

{
  "error": {
    "code": "NOT_FOUND",
    "status": 404,
    "message": "Video room not found"
  },
  "meta": {
    "request_id": "req_read_room",
    "timestamp": "2026-09-03T09:46:00.000Z"
  }
}

429 — concurrent-room cap. A tenant’s concurrent-room cap throttles bursts of room-creation (POST /rooms-scheduled) and token-mint (POST /:id/join) calls. The two write calls are rate-limited per tenant; the fix is to drain ended rooms (list /sessions and skip live ones) before opening more, not to retry the same POST in a loop.

429

{
  "error": {
    "code": "RATE_LIMITED",
    "status": 429,
    "message": "Too many concurrent rooms. Close ended rooms before creating new ones."
  },
  "meta": {
    "request_id": "req_create_room",
    "timestamp": "2026-09-03T09:15:00.000Z"
  }
}

Two more envelope codes worth special-casing before the generic handler: 403 PARTICIPANT_TIER_NOT_PERMITTED (the caller’s role cannot mint the requested participant_tier) and 403 IMPERSONATION_NOT_PERMITTED / 400 IMPERSONATION_REASON_REQUIRED on the token-mint path — both mean re-minting without changing the request will fail again the same way. For the embedded-UI version of this same chain (the operator-facing Meetings dashboard that posts to these same endpoints), see guides/video-meetings. For token claims, scopes, and the lobby-downgrade semantics in depth, see guides/video-room-access-tokens.

API Reference

All Endpoints

Worked video room samples

1. Create the room

2. Mint the participant token

3. Read participants and the session record

4. Errors

​Worked video room samples

​1. Create the room

​2. Mint the participant token

​3. Read participants and the session record

​4. Errors

Worked video room samples

1. Create the room

2. Mint the participant token

3. Read participants and the session record

4. Errors