Video API

Real-time video rooms backed by Orbit Media (Devotel’s hosted SFU; forked from LiveKit OSS under Apache-2 License — see attribution). Two flavors:

Scheduled rooms (/api/v1/video/rooms-scheduled) — DB-backed, first-class rooms with a host, schedule, capacity, recording, and per-room guest invites. Use when you want the room to outlive a single session, surface in the inbox as a video conversation, or hand out shareable join links.
Ad-hoc rooms (/api/v1/video/rooms) — fire-and-forget Orbit Media rooms created directly against the Orbit Media room service. Use for “click to start a call” flows where the room ends when participants leave.

Base path: /api/v1/video Authentication: API key (X-API-Key) on every authenticated endpoint. The public guest-redeem endpoint (POST /video/invites/:inviteToken/redeem) takes the invite token itself as the credential and requires no API key. Role requirements: mutating endpoints (create, delete, end, recording start/stop, invite create/revoke, participant kick/mute, simulive configure/cancel) require owner, admin, or developer. Read endpoints (list, get) and POST /rooms-scheduled/:id/join are available to any authenticated tenant member; the join route silently downgrades role: "host" to participant for callers that lack the host-mint role. Orbit Media configuration: every endpoint returns 503 SERVICE_UNAVAILABLE if Orbit Media is not configured on the cluster, but the two flavors honour different variables:

Ad-hoc rooms (/video/rooms) accept the legacy DEVOTEL_LIVEKIT_URL / DEVOTEL_LIVEKIT_API_KEY as a fallback when DEVOTEL_ORBIT_MEDIA_URL / DEVOTEL_ORBIT_MEDIA_API_KEY are unset, so they stay in service on a cluster that still carries only the legacy vars.
Scheduled rooms (/video/rooms-scheduled, including join, end, recording, egress, and participant endpoints) require DEVOTEL_ORBIT_MEDIA_URL and DEVOTEL_ORBIT_MEDIA_API_KEY directly — there is no DEVOTEL_LIVEKIT_* fallback, so a cluster set up with only the legacy vars returns 503 on these endpoints.

Set DEVOTEL_ORBIT_MEDIA_URL and DEVOTEL_ORBIT_MEDIA_API_KEY to keep both flavors in service. The legacy DEVOTEL_LIVEKIT_* vars remain as deprecated ad-hoc-only fallbacks and will be removed in a future release; prefer DEVOTEL_ORBIT_MEDIA_* for all new and migrating deployments. Wire compatibility: Orbit Media speaks the same JWT-signed signaling protocol as the LiveKit OSS fork it descends from. The published @orbit/media-client browser SDK is the supported client. The upstream livekit-client SDK still works at the protocol level today but is not part of Orbit’s supported surface and may diverge.

Scheduled rooms

First-class video rooms backed by tenant_<id>.video_rooms. Each room creates a companion conversations row (channel='video') so the inbox renders it alongside other channels.

Recurring meetings. Pass an optional RFC 5545 RRULE body in recurrence_rule to turn a scheduled room into a recurring series — FREQ=DAILY/WEEKLY/MONTHLY/YEARLY with BYDAY, INTERVAL, COUNT, and UNTIL. When set, the .ics calendar attachment on guest invites carries the matching RRULE line so Gmail, Apple Mail, and Outlook render the full series. Omit the field for a single occurrence. Per-occurrence overrides (EXDATE, single-instance reschedule) and series-update cancel/re-send are not yet exposed.

Schedule a Room

POST /api/v1/video/rooms-scheduled Create a new scheduled video room. Tenant-isolated. Optionally pre-fills a start time, sets a recurrence rule, enables auto-recording, and caps capacity. Returns a host token immediately so the creator can join without a second round-trip.

name

string

required

Human-readable room title (1–200 chars). Surfaces in the inbox and join UIs.

scheduled_at

string

ISO-8601 timestamp with offset (e.g. 2026-05-10T14:00:00Z). Omit or null for “start now”.

recurrence_rule

string

Optional RFC 5545 RRULE body (value only — omit the RRULE: prefix), e.g. FREQ=WEEKLY;BYDAY=MO;COUNT=10. Makes the room a recurring series; the .ics attachment on guest invites carries the matching RRULE line. 8–512 characters. FREQ must be one of DAILY, WEEKLY, MONTHLY, YEARLY; INTERVAL (when present) must be ≥ 1; COUNT (when present) must be ≤ 520; UNTIL (when present) must be YYYYMMDD or YYYYMMDDThhmmssZ. Invalid values are rejected with 400. Omit for a single occurrence.

recording_enabled

boolean

default:"false"

When true, recording starts automatically the moment the first participant joins.

max_participants

integer

Hard cap on concurrent participants (2–300). Orbit Media rejects join attempts past this number. Omit to inherit your plan’s per-tier participant cap — there is no fixed default; an absent value resolves to the tenant’s tier ceiling. Supplying a value above your tier cap is rejected with VIDEO_PARTICIPANTS_CAP_EXCEEDED (400).

settings

object

Arbitrary key-value pairs persisted on the room row. Surfaces back on GET /:id.

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": "Onboarding call - Acme",
  "scheduled_at": "2026-05-10T14:00:00Z",
  "recording_enabled": true,
  "max_participants": 4
}'

Node.js

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

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

const room = await orbit.video.roomsScheduled.create({
  name: 'Onboarding call - Acme',
  scheduled_at: '2026-05-10T14:00:00Z',
  recording_enabled: true,
  max_participants: 4,
})
console.log(room.data.room_id, room.data.host_token)

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled", headers=headers, json={
  "name": "Onboarding call - Acme",
  "scheduled_at": "2026-05-10T14:00:00Z",
  "recording_enabled": True,
  "max_participants": 4
})
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": "Onboarding call - Acme",
  "scheduled_at": "2026-05-10T14:00:00Z",
  "recording_enabled": true,
  "max_participants": 4
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

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": "Onboarding call - Acme",
  "scheduled_at": "2026-05-10T14:00:00Z",
  "recording_enabled": true,
  "max_participants": 4
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
    "room_sid": "RM_AbCdEfGhIjKl",
    "host_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "ws_url": "wss://media.orbit.devotel.io"
  },
  "meta": {
    "request_id": "req_video_001",
    "timestamp": "2026-05-10T12:00:00Z"
  }
}

Error codes: 503 SERVICE_UNAVAILABLE (Orbit Media not configured), 400 (validation), 403 (caller lacks owner/admin/developer), 500 VIDEO_ROOM_CREATION_FAILED.

List Scheduled Rooms

GET /api/v1/video/rooms-scheduled Retrieve rooms scheduled by the current tenant. Filter by lifecycle status.

status

string

Filter by lifecycle: scheduled, live, ended. Omit for all statuses.

limit

integer

default:"100"

Results to return (1–500).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled?status=live&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const rooms = await orbit.video.roomsScheduled.list({ status: 'live', limit: 50 })
console.log(rooms.data)

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",
                 headers=headers, params={"status": "live", "limit": 50})
print(r.json())

package main

import (
	"net/http"
	"os"
)

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

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled?status=live&limit=50');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": [
    {
      "id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
      "name": "Onboarding call - Acme",
      "room_sid": "RM_AbCdEfGhIjKl",
      "host_user_id": "user_2x7Q...",
      "status": "live",
      "scheduled_at": "2026-05-10T14:00:00Z",
      "started_at": "2026-05-10T14:00:12Z",
      "ended_at": null,
      "recording_enabled": true,
      "recording_url": null,
      "max_participants": 4,
      "settings": { "conversation_id": "conversation_kPdE..." },
      "created_at": "2026-05-09T22:14:00Z",
      "updated_at": "2026-05-10T14:00:12Z"
    }
  ],
  "meta": { "request_id": "req_video_002", "timestamp": "2026-05-10T14:01:00Z" }
}

Error codes: 503 SERVICE_UNAVAILABLE, 400 (invalid query), 500 VIDEO_ROOM_LIST_FAILED.

Get a Scheduled Room

GET /api/v1/video/rooms-scheduled/{id} Fetch a single room plus the live participant roster.

string

required

Room UUID returned from POST /rooms-scheduled.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const detail = await orbit.video.roomsScheduled.get('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002')
console.log(detail.data.room, detail.data.participants)

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/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "room": {
      "id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
      "name": "Onboarding call - Acme",
      "room_sid": "RM_AbCdEfGhIjKl",
      "status": "live",
      "scheduled_at": "2026-05-10T14:00:00Z",
      "started_at": "2026-05-10T14:00:12Z",
      "ended_at": null,
      "recording_enabled": true,
      "max_participants": 4
    },
    "participants": [
      {
        "identity": "user_2x7Q...",
        "display_name": "Jane Doe",
        "role": "host",
        "joined_at": "2026-05-10T14:00:12Z",
        "left_at": null
      }
    ]
  },
  "meta": { "request_id": "req_video_003", "timestamp": "2026-05-10T14:02:00Z" }
}

Error codes: 503 SERVICE_UNAVAILABLE, 400 (id not a UUID), 404 NOT_FOUND, 500 VIDEO_ROOM_FETCH_FAILED.

Join a Scheduled Room

POST /api/v1/video/rooms-scheduled/{id}/join Generate a per-participant Orbit Media access token. The resulting JWT is short-lived and scoped to one room + identity.

identity

string

required

Unique participant identity (1–200 chars). Used as the Orbit Media participant id. Reusing the same identity in the same room kicks the prior session.

display_name

string

Friendly name shown to other participants.

role

string

default:"participant"

participant or host. Server-side guard: callers that are not owner / admin / developer are silently downgraded to participant.

user_id

string

Optional UUID of an Orbit user this participant represents. Defaults to the calling user.

contact_id

string

Optional UUID of a contact the participant represents (CRM linkage).

ttl_seconds

integer

Token TTL in seconds (60–86400). Defaults to the service-configured value.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/join" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "identity": "user_42",
  "display_name": "Jane Doe",
  "role": "host"
}'

Node.js

const token = await orbit.video.roomsScheduled.join('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002', {
  identity: 'user_42',
  display_name: 'Jane Doe',
  role: 'host',
})
console.log(token.data.token, token.data.ws_url)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/join",
                  headers=headers, json={
                    "identity": "user_42",
                    "display_name": "Jane Doe",
                    "role": "host"
                  })
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/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/join",
		bytes.NewBuffer([]byte(`{"identity":"user_42","display_name":"Jane Doe","role":"host"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/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, '{"identity":"user_42","display_name":"Jane Doe","role":"host"}');
echo curl_exec($ch);

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "livekit_access_token",
    "ws_url": "wss://media.orbit.devotel.io",
    "livekit_url": "wss://media.orbit.devotel.io",
    "room_sid": "RM_AbCdEfGhIjKl",
    "participant_tier": "host",
    "lobby_downgraded": false,
    "permissions": {
      "can_publish": true,
      "can_subscribe": true,
      "can_publish_data": true,
      "hidden": false,
      "room_admin": true
    },
    "expires_at": "2026-05-10T15:05:00Z",
    "expires_in_seconds": 3600
  },
  "meta": { "request_id": "req_video_004", "timestamp": "2026-05-10T14:05:00Z" }
}

token is a media-server access JWT — feed it to the supported @orbit/media-client browser SDK (or the upstream livekit-client SDK pointed at the livekit_url from this response — NOT at livekit.cloud, which was retired 2026-05-19), not an HTTP Authorization header. token_type (livekit_access_token) and livekit_url are protocol-level names inherited from the LiveKit OSS fork Orbit Media descends from — livekit_url is the front-end-facing media-server WebSocket URL (an orbit-media host, never a livekit.cloud one); consume it and fall back to the legacy ws_url alias if absent. participant_tier and permissions are the EFFECTIVE grant after any host→participant downgrade and waiting-room clamp — check permissions.can_publish before showing a publish control. lobby_downgraded is true when an armed waiting room forced this join to receive-only viewer; show a “waiting for host to admit you” state instead of a publish button. Re-mint the token before expires_at (expires_in_seconds from issue) to avoid failing mid-session.

Error codes: 503 SERVICE_UNAVAILABLE, 400 (validation), 404 (room not found), 500 VIDEO_ROOM_JOIN_FAILED.

End a Scheduled Room

POST /api/v1/video/rooms-scheduled/{id}/end Terminate the room immediately. All participants are disconnected and the room transitions to ended. Recording (if active) is stopped and flushed.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/end" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.video.roomsScheduled.end('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/end", headers=headers)
print(r.status_code)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/end", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/end');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Error codes: 503 SERVICE_UNAVAILABLE, 400 (id not a UUID), 403 (caller lacks owner/admin/developer), 404 (room not found), 500 VIDEO_ROOM_END_FAILED.

Start Recording

POST /api/v1/video/rooms-scheduled/{id}/recording/start Begin an Orbit Media egress recording on the room. Returns the egress id to track via the Orbit Media webhook lifecycle. If recording_enabled was set at creation time the recording auto-starts and this call is a no-op.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/recording/start" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const egress = await orbit.video.roomsScheduled.recording.start('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002')
console.log(egress.data.egress_id)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/recording/start", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/recording/start", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/recording/start');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "egress_id": "EG_QrStUvWxYz"
  },
  "meta": { "request_id": "req_video_005", "timestamp": "2026-05-10T14:06:00Z" }
}

Error codes: 503 SERVICE_UNAVAILABLE, 403 (caller lacks owner/admin/developer), 404 (room not found), 500 VIDEO_RECORDING_START_FAILED.

Stop Recording

POST /api/v1/video/rooms-scheduled/{id}/recording/stop End the Orbit Media egress. The recording is finalised and the resulting URL (MP4 / HLS depending on egress settings) is written back to the room row asynchronously via the Orbit Media webhook.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/recording/stop" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.video.roomsScheduled.recording.stop('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/recording/stop", headers=headers)
print(r.status_code)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/recording/stop", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/recording/stop');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Error codes: 503 SERVICE_UNAVAILABLE, 403, 404 (room not found), 500 VIDEO_RECORDING_STOP_FAILED.

Guest invites

Issue tokenised join links to people outside your tenant. The invite token IS the credential — anyone who holds it can redeem it (subject to expires_at + max_uses) without an Orbit account.

Create an Invite

POST /api/v1/video/rooms-scheduled/{id}/invites Mint a guest-redeemable invite for a scheduled room. The returned invite_token is what you embed in a shareable URL.

participant_name

string

Optional name pre-filled for the guest in the redeem flow (1–120 chars).

expires_in_hours

integer

Invite TTL in hours (1–168). Defaults to a service-configured value (typically 24).

max_uses

integer

Cap on the number of redemptions (1–500). Omit or null for unlimited.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "participant_name": "Acme Customer",
  "expires_in_hours": 24,
  "max_uses": 5
}'

Node.js

const invite = await orbit.video.roomsScheduled.invites.create('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002', {
  participant_name: 'Acme Customer',
  expires_in_hours: 24,
  max_uses: 5,
})
console.log(invite.data.invite_token)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites",
                  headers=headers, json={
                    "participant_name": "Acme Customer",
                    "expires_in_hours": 24,
                    "max_uses": 5
                  })
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/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites",
		bytes.NewBuffer([]byte(`{"participant_name":"Acme Customer","expires_in_hours":24,"max_uses":5}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites');
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, '{"participant_name":"Acme Customer","expires_in_hours":24,"max_uses":5}');
echo curl_exec($ch);

{
  "data": {
    "id": "5b3c7f01-2e44-49ab-bce0-7d0a8c9f0b14",
    "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
    "invite_token": "p9Z-vQrX_3kT2hN1m4yL5wB6aE7s8C9d",
    "participant_name": "Acme Customer",
    "expires_at": "2026-05-11T22:00:00Z",
    "revoked_at": null,
    "max_uses": 5,
    "uses_count": 0,
    "created_at": "2026-05-10T22:00:00Z"
  },
  "meta": { "request_id": "req_video_006", "timestamp": "2026-05-10T22:00:00Z" }
}

Error codes: 503 SERVICE_UNAVAILABLE, 400 (validation), 403, 404 (room not found), 500 VIDEO_INVITE_CREATE_FAILED. Rate-limited per the authenticated-write bucket.

List Invites

GET /api/v1/video/rooms-scheduled/{id}/invites Retrieve every invite issued for a room.

include_expired

boolean

default:"false"

When true, also returns invites past expires_at.

limit

integer

default:"100"

Results to return (1–500).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites?include_expired=true" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const invites = await orbit.video.roomsScheduled.invites.list('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002', {
  include_expired: true,
})
console.log(invites.data)

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/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites",
                 headers=headers, params={"include_expired": "true"})
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites?include_expired=true", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites?include_expired=true');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": [
    {
      "id": "5b3c7f01-2e44-49ab-bce0-7d0a8c9f0b14",
      "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
      "invite_token": "p9Z-vQrX_3kT2hN1m4yL5wB6aE7s8C9d",
      "participant_name": "Acme Customer",
      "expires_at": "2026-05-11T22:00:00Z",
      "revoked_at": null,
      "max_uses": 5,
      "uses_count": 1,
      "created_at": "2026-05-10T22:00:00Z"
    }
  ],
  "meta": { "request_id": "req_video_007", "timestamp": "2026-05-10T22:30:00Z" }
}

Error codes: 503 SERVICE_UNAVAILABLE, 400 (invalid query), 404 (room not found), 500 VIDEO_INVITE_LIST_FAILED. Rate-limited per the authenticated-read bucket.

Revoke an Invite

DELETE /api/v1/video/rooms-scheduled/{id}/invites/{inviteId} Permanently revoke an invite. Subsequent redeem attempts return 404.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites/5b3c7f01-2e44-49ab-bce0-7d0a8c9f0b14" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.video.roomsScheduled.invites.revoke(
  '8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002',
  '5b3c7f01-2e44-49ab-bce0-7d0a8c9f0b14',
)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.delete("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites/5b3c7f01-2e44-49ab-bce0-7d0a8c9f0b14",
                    headers=headers)
print(r.status_code)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites/5b3c7f01-2e44-49ab-bce0-7d0a8c9f0b14", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/invites/5b3c7f01-2e44-49ab-bce0-7d0a8c9f0b14');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Error codes: 503 SERVICE_UNAVAILABLE, 400 (id / inviteId not UUIDs), 403, 404 (invite not found), 500 VIDEO_INVITE_REVOKE_FAILED. Rate-limited per the authenticated-write bucket.

Redeem an Invite (public)

POST /api/v1/video/invites/{inviteToken}/redeem No authentication. Guest-facing endpoint. Exchanges an invite token for a short-lived Orbit Media JWT scoped to one room. Rate-limited per IP (30 requests / minute).

inviteToken

string

required

The opaque invite token returned by POST /rooms-scheduled/{id}/invites. 24–64 characters, [A-Za-z0-9_-]+.

display_name

string

required

Friendly name shown to other participants (1–120 chars).

identity

string

Optional URL-safe identity ([A-Za-z0-9_:-]+, 1–120 chars). If omitted, the service mints one.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/invites/p9Z-vQrX_3kT2hN1m4yL5wB6aE7s8C9d/redeem" \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "Acme Customer" }'

Node.js

// Public endpoint — no API key. Call directly via fetch.
const res = await fetch('https://api.orbit.devotel.io/api/v1/video/invites/p9Z-vQrX_3kT2hN1m4yL5wB6aE7s8C9d/redeem', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ display_name: 'Acme Customer' }),
})
const json = await res.json()
console.log(json.data.token, json.data.livekit_url)

Python

import requests
r = requests.post("https://api.orbit.devotel.io/api/v1/video/invites/p9Z-vQrX_3kT2hN1m4yL5wB6aE7s8C9d/redeem",
                  json={"display_name": "Acme Customer"})
print(r.json())

package main

import (
	"bytes"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/invites/p9Z-vQrX_3kT2hN1m4yL5wB6aE7s8C9d/redeem",
		bytes.NewBuffer([]byte(`{"display_name":"Acme Customer"}`)))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/invites/p9Z-vQrX_3kT2hN1m4yL5wB6aE7s8C9d/redeem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"display_name":"Acme Customer"}');
echo curl_exec($ch);

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "ws_url": "wss://media.orbit.devotel.io",
    "livekit_url": "wss://media.orbit.devotel.io",
    "room_sid": "RM_AbCdEfGhIjKl",
    "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
    "room_name": "Onboarding call - Acme",
    "identity": "guest_8f2a01b7",
    "display_name": "Acme Customer",
    "expires_at": "2026-05-10T15:00:00Z"
  },
  "meta": { "request_id": "req_video_008", "timestamp": "2026-05-10T14:00:00Z" }
}

ws_url and livekit_url both carry the same media-server WebSocket URL. Consume livekit_url — it is the front-end-facing key. ws_url is a legacy alias preserved for clients written against the earlier surface; read livekit_url and fall back to ws_url if it is absent.

Error codes: 400 (validation, including malformed token), 404 (invite not found / revoked / expired / max-uses exhausted), 429 (per-IP rate-limit), 500 VIDEO_INVITE_REDEEM_FAILED.

Host admin controls

Force-disconnect or force-mute participants in a live scheduled room.

Kick a Participant

POST /api/v1/video/rooms-scheduled/{id}/participants/{identity}/kick Immediately disconnect a participant from the room. Their Orbit Media session is terminated; they can rejoin only with a fresh token.

identity

string

required

The Orbit Media identity to kick (matches the identity passed at join time).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/participants/guest_8f2a01b7/kick" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.video.roomsScheduled.participants.kick(
  '8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002',
  'guest_8f2a01b7',
)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/participants/guest_8f2a01b7/kick",
                  headers=headers)
print(r.status_code)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/participants/guest_8f2a01b7/kick", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/participants/guest_8f2a01b7/kick');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Error codes: 503 SERVICE_UNAVAILABLE, 400 (id not a UUID), 403, 404 (participant or room not found), 500 VIDEO_PARTICIPANT_KICK_FAILED. Rate-limited per the authenticated-write bucket.

Mute a Participant

POST /api/v1/video/rooms-scheduled/{id}/participants/{identity}/mute Force-mute a participant’s audio or video track. The participant can unmute themselves; this is a host-driven hard mute, not a permanent block.

kind

string

default:"audio"

audio or video. Selects which track to mute.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/participants/guest_8f2a01b7/mute" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "audio" }'

Node.js

await orbit.video.roomsScheduled.participants.mute(
  '8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002',
  'guest_8f2a01b7',
  { kind: 'audio' },
)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/participants/guest_8f2a01b7/mute",
                  headers=headers, json={"kind": "audio"})
print(r.status_code)

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/participants/guest_8f2a01b7/mute",
		bytes.NewBuffer([]byte(`{"kind":"audio"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/participants/guest_8f2a01b7/mute');
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, '{"kind":"audio"}');
echo curl_exec($ch);

Error codes: 503 SERVICE_UNAVAILABLE, 400 (validation, including kind not in ), 403, 404 (participant or room not found), 500 VIDEO_PARTICIPANT_MUTE_FAILED. Rate-limited per the authenticated-write bucket.

Simulive broadcast

Schedule a pre-recorded video to play out to an audience as if it were live — “simulive” (a.k.a. premiere / played-as-live), the standard webinar-platform capability behind Zoom Webinars, Livestorm, and ON24 premieres. Point at an already-uploaded recording, set a start time, and every viewer’s player seeks to the SAME wall-clock-synced position of the file — nobody starts from zero on join. This is a facet of an existing scheduled room, not a separate resource: there’s no simulive id — the config lives on the room itself (settings.simulive), and every response is scoped by the room’s id. Role requirements: GET /simulive and GET /simulive/playout are available to any authenticated tenant member with the video:read scope (video:write works as a superset). PUT /simulive and POST /simulive/cancel require owner, admin, or developer plus the video:write scope. These endpoints read/write the room row directly and never call out to Orbit Media, so — unlike the endpoints above — they do not return 503 SERVICE_UNAVAILABLE when Orbit Media is unconfigured.

Get Simulive Config

GET /api/v1/video/rooms-scheduled/{id}/simulive Fetch the room’s simulive configuration together with the live-computed playout (position, broadcast_state). Rate limit: 120 requests/minute per tenant (auth-read bucket).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/simulive" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const simulive = await orbit.video.roomsScheduled.simulive.get('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002')
console.log(simulive.data.config.status, simulive.data.playout.broadcast_state)

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/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/simulive", headers=headers)
print(r.json())

{
  "data": {
    "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
    "room_status": "scheduled",
    "config": {
      "status": "scheduled",
      "title": "Q3 product premiere",
      "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
      "source_recording_id": "rec_8f2a01b7",
      "duration_seconds": 2400,
      "scheduled_start_at": "2026-07-20T17:00:00Z",
      "loop": false,
      "chat_enabled": true,
      "qa_enabled": true,
      "created_at": "2026-07-15T09:00:00.000Z",
      "updated_at": "2026-07-15T09:00:00.000Z",
      "canceled_at": null
    },
    "playout": {
      "broadcast_state": "upcoming",
      "is_live": false,
      "position_seconds": 0,
      "duration_seconds": 2400,
      "seconds_until_start": 41400,
      "seconds_remaining": null,
      "loop": false,
      "loop_iteration": 0,
      "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
      "title": "Q3 product premiere",
      "scheduled_start_at": "2026-07-20T17:00:00Z",
      "chat_enabled": true,
      "qa_enabled": true,
      "server_time": "2026-07-20T05:30:00.000Z"
    }
  },
  "meta": { "request_id": "req_video_simulive_001", "timestamp": "2026-07-20T05:30:00Z" }
}

Error codes: 422 VALIDATION_ERROR (id not a UUID), 404 NOT_FOUND, 500 VIDEO_SIMULIVE_GET_FAILED.

Configure a Simulive Broadcast

PUT /api/v1/video/rooms-scheduled/{id}/simulive Create or update the room’s simulive config. Every field is optional so you can build the config up incrementally (upload the recording, then set the schedule); set status: "scheduled" once source_url, duration_seconds, and scheduled_start_at are all in place — the request is rejected until they are. This is a full merge over the existing config (unset fields keep their current value), not a full replacement.

status

string

draft or scheduled. Moving to scheduled requires source_url, a positive duration_seconds, and scheduled_start_at to already be set (in this request or a prior one) — otherwise the request is rejected and status stays unchanged. Moving to draft or scheduled clears a prior cancellation.

title

string

Optional broadcast title shown to viewers (up to 200 chars). null clears it.

source_url

string

Playable URL (HLS .m3u8 or MP4) of the pre-recorded asset a broadcast player dereferences client-side. Must be http(s). null clears it.

source_recording_id

string

Optional provenance pointer back to the unified recording behind source_url (up to 128 chars). null clears it.

duration_seconds

number

Total length of the source recording, in seconds (greater than 0, up to 86400 — 24 hours). Drives the playhead math — set it to the recording’s actual runtime. null clears it.

scheduled_start_at

string

ISO-8601 wall-clock time the playout begins. null clears it.

loop

boolean

default:"false"

When true, playout restarts from 0 instead of ending once duration_seconds elapses.

chat_enabled

boolean

default:"true"

Whether live chat is layered over the broadcast.

qa_enabled

boolean

default:"true"

Whether live Q&A is layered over the broadcast.

Rate limit: 60 requests/minute per tenant (auth-write bucket).

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/simulive" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "scheduled",
  "title": "Q3 product premiere",
  "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
  "duration_seconds": 2400,
  "scheduled_start_at": "2026-07-20T17:00:00Z"
}'

Node.js

const simulive = await orbit.video.roomsScheduled.simulive.update('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002', {
  status: 'scheduled',
  title: 'Q3 product premiere',
  source_url: 'https://cdn.example.com/recordings/q3-premiere.m3u8',
  duration_seconds: 2400,
  scheduled_start_at: '2026-07-20T17:00:00Z',
})
console.log(simulive.data.config.status)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.put("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/simulive",
                 headers=headers, json={
                   "status": "scheduled",
                   "title": "Q3 product premiere",
                   "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
                   "duration_seconds": 2400,
                   "scheduled_start_at": "2026-07-20T17:00:00Z"
                 })
print(r.json())

{
  "data": {
    "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
    "config": {
      "status": "scheduled",
      "title": "Q3 product premiere",
      "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
      "source_recording_id": null,
      "duration_seconds": 2400,
      "scheduled_start_at": "2026-07-20T17:00:00Z",
      "loop": false,
      "chat_enabled": true,
      "qa_enabled": true,
      "created_at": "2026-07-20T05:30:00.000Z",
      "updated_at": "2026-07-20T05:30:00.000Z",
      "canceled_at": null
    },
    "playout": {
      "broadcast_state": "upcoming",
      "is_live": false,
      "position_seconds": 0,
      "duration_seconds": 2400,
      "seconds_until_start": 41400,
      "seconds_remaining": null,
      "loop": false,
      "loop_iteration": 0,
      "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
      "title": "Q3 product premiere",
      "scheduled_start_at": "2026-07-20T17:00:00Z",
      "chat_enabled": true,
      "qa_enabled": true,
      "server_time": "2026-07-20T05:30:00.000Z"
    }
  },
  "meta": { "request_id": "req_video_simulive_002", "timestamp": "2026-07-20T05:30:00Z" }
}

Error codes: 422 VALIDATION_ERROR (field-level, e.g. id not a UUID, source_url not http(s), duration_seconds out of range), 400 VIDEO_SIMULIVE_INVALID (business rule, e.g. requesting status: "scheduled" while source_url / duration_seconds / scheduled_start_at are still missing — the message lists exactly which), 403 (caller lacks owner/admin/developer or video:write), 404 NOT_FOUND (room not found), 500 VIDEO_SIMULIVE_UPDATE_FAILED. Rate-limited per the authenticated-write bucket.

Cancel a Simulive Broadcast

POST /api/v1/video/rooms-scheduled/{id}/simulive/cancel Cancel a scheduled (or draft) simulive broadcast. Idempotent — canceling an already-canceled broadcast is a no-op that preserves the original canceled_at. To resume broadcasting on the same room, PUT /simulive with status: "draft" or "scheduled", which clears the cancellation. Rate limit: 60 requests/minute per tenant (auth-write bucket).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/simulive/cancel" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.video.roomsScheduled.simulive.cancel('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/simulive/cancel", headers=headers)
print(r.json())

{
  "data": {
    "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
    "config": {
      "status": "canceled",
      "title": "Q3 product premiere",
      "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
      "source_recording_id": null,
      "duration_seconds": 2400,
      "scheduled_start_at": "2026-07-20T17:00:00Z",
      "loop": false,
      "chat_enabled": true,
      "qa_enabled": true,
      "created_at": "2026-07-20T05:30:00.000Z",
      "updated_at": "2026-07-20T06:00:00.000Z",
      "canceled_at": "2026-07-20T06:00:00.000Z"
    },
    "playout": {
      "broadcast_state": "canceled",
      "is_live": false,
      "position_seconds": 0,
      "duration_seconds": 2400,
      "seconds_until_start": null,
      "seconds_remaining": null,
      "loop": false,
      "loop_iteration": 0,
      "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
      "title": "Q3 product premiere",
      "scheduled_start_at": "2026-07-20T17:00:00Z",
      "chat_enabled": true,
      "qa_enabled": true,
      "server_time": "2026-07-20T06:00:00.000Z"
    }
  },
  "meta": { "request_id": "req_video_simulive_003", "timestamp": "2026-07-20T06:00:00Z" }
}

Error codes: 422 VALIDATION_ERROR (id not a UUID), 403 (caller lacks owner/admin/developer or video:write), 404 NOT_FOUND (room not found), 500 VIDEO_SIMULIVE_CANCEL_FAILED. Rate-limited per the authenticated-write bucket.

Get Simulive Playout

GET /api/v1/video/rooms-scheduled/{id}/simulive/playout The lightweight, poll-friendly playhead a broadcast player hits repeatedly to stay wall-clock-synced with every other viewer — no audit trail, minimal payload (no room_status / config, just room_id and playout).

Polling contract. There is no push/websocket channel for playout — a player polls this endpoint (every 5–15 seconds is a reasonable default) and seeks its <video> element to playout.position_seconds of playout.source_url. Branch on broadcast_state: show a countdown using seconds_until_start while upcoming; play from position_seconds and keep polling while live; stop and show an ended state once ended; hide the player entirely on canceled or not_configured. When loop is true, watch loop_iteration to detect a wraparound instead of treating a drop in position_seconds as a seek backwards.

Rate limit: 120 requests/minute per tenant (auth-read bucket).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/simulive/playout" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const { data } = await orbit.video.roomsScheduled.simulive.playout('8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002')
videoEl.currentTime = data.playout.position_seconds

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/8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002/simulive/playout", headers=headers)
print(r.json())

{
  "data": {
    "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
    "playout": {
      "broadcast_state": "live",
      "is_live": true,
      "position_seconds": 184.201,
      "duration_seconds": 2400,
      "seconds_until_start": null,
      "seconds_remaining": 2215.799,
      "loop": false,
      "loop_iteration": 0,
      "source_url": "https://cdn.example.com/recordings/q3-premiere.m3u8",
      "title": "Q3 product premiere",
      "scheduled_start_at": "2026-07-20T17:00:00Z",
      "chat_enabled": true,
      "qa_enabled": true,
      "server_time": "2026-07-20T17:03:04.201Z"
    }
  },
  "meta": { "request_id": "req_video_simulive_004", "timestamp": "2026-07-20T17:03:04Z" }
}

Error codes: 422 VALIDATION_ERROR (id not a UUID), 404 NOT_FOUND (room not found), 500 VIDEO_SIMULIVE_PLAYOUT_FAILED.

Ad-hoc rooms

Fire-and-forget Orbit Media rooms. No DB row, no inbox conversation, no recording. Use when the room only needs to live for one session and disappear when participants leave. Room names are tenant-prefixed on the Orbit Media side (invariant #TI-P0-3) so collisions across tenants are impossible.

Create an Ad-hoc Room

POST /api/v1/video/rooms Create an Orbit Media room and receive a host token in the same response.

name

string

required

URL-safe room name (3–200 chars, [a-zA-Z0-9_-]+). Tenant prefix is prepended internally; display_name echoes the un-prefixed name.

max_participants

integer

Hard cap on concurrent participants (2–300).

metadata

object

Arbitrary key-value pairs forwarded to Orbit Media.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "quick-sync",
  "max_participants": 8
}'

Node.js

const room = await orbit.video.rooms.create({
  name: 'quick-sync',
  max_participants: 8,
})
console.log(room.data.room_name, room.data.token)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms", headers=headers, json={
  "name": "quick-sync",
  "max_participants": 8
})
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",
		bytes.NewBuffer([]byte(`{"name":"quick-sync","max_participants":8}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms');
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, '{"name":"quick-sync","max_participants":8}');
echo curl_exec($ch);

{
  "data": {
    "room_name": "tenant_abc1234_quick-sync",
    "display_name": "quick-sync",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "url": "wss://media.orbit.devotel.io"
  },
  "meta": { "request_id": "req_video_009", "timestamp": "2026-05-10T14:00:00Z" }
}

The wire-level room_name keeps the tenant_<id>_ prefix; pass that to Orbit Media. The dashboard uses display_name for rendering.

Error codes: 503 SERVICE_UNAVAILABLE, 400 (validation, including non-URL-safe name), 403, 500 VIDEO_ROOM_CREATION_FAILED.

List Ad-hoc Rooms

GET /api/v1/video/rooms List active Orbit Media rooms owned by the current tenant. Cursor-paginated by room name.

cursor

string

Room name to resume from. Returned in the previous page’s pagination.next_cursor.

limit

integer

default:"25"

Results per page (max 200).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms?limit=20" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const rooms = await orbit.video.rooms.list({ limit: 20 })
console.log(rooms.data, rooms.pagination)

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", headers=headers, params={"limit": 20})
print(r.json())

package main

import (
	"net/http"
	"os"
)

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

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms?limit=20');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": [
    {
      "name": "tenant_abc1234_quick-sync",
      "display_name": "quick-sync",
      "num_participants": 2,
      "max_participants": 8,
      "creation_time": "2026-05-10T14:00:00Z",
      "metadata": ""
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false,
    "total": 1
  },
  "meta": { "request_id": "req_video_010", "timestamp": "2026-05-10T14:05:00Z" }
}

Error codes: 503 SERVICE_UNAVAILABLE, 400 INVALID_CURSOR, 500 VIDEO_ROOM_LIST_FAILED.

Get an Ad-hoc Room

GET /api/v1/video/rooms/{name} Fetch a specific ad-hoc room with its live participant roster. Pass either the prefixed wire name or the bare display name.

name

string

required

Room name (with or without the tenant_<id>_ prefix).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms/quick-sync" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const detail = await orbit.video.rooms.get('quick-sync')
console.log(detail.data.participants)

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/quick-sync", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

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

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms/quick-sync');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "name": "tenant_abc1234_quick-sync",
    "display_name": "quick-sync",
    "num_participants": 2,
    "max_participants": 8,
    "creation_time": "2026-05-10T14:00:00Z",
    "metadata": "",
    "participants": [
      {
        "identity": "user_42",
        "name": "Jane Doe",
        "joined_at": "2026-05-10T14:00:30Z",
        "is_publishing": true
      }
    ]
  },
  "meta": { "request_id": "req_video_011", "timestamp": "2026-05-10T14:02:00Z" }
}

Error codes: 503 SERVICE_UNAVAILABLE, 404 NOT_FOUND, 500 VIDEO_ROOM_DETAILS_FAILED.

Delete an Ad-hoc Room

DELETE /api/v1/video/rooms/{name} Close the Orbit Media room and disconnect every participant.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/video/rooms/quick-sync" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.video.rooms.delete('quick-sync')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.delete("https://api.orbit.devotel.io/api/v1/video/rooms/quick-sync", headers=headers)
print(r.status_code)

package main

import (
	"net/http"
	"os"
)

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

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms/quick-sync');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Error codes: 503 SERVICE_UNAVAILABLE, 403 (caller lacks owner/admin/developer), 500 VIDEO_ROOM_CLOSE_FAILED.

Issue a Participant Token

POST /api/v1/video/rooms/{name}/token Generate a per-participant Orbit Media join token for an ad-hoc room. Use this when the host needs to invite someone else into the room they created.

participant_name

string

required

Friendly participant name (1–200 chars). Also used as the Orbit Media identity.

metadata

object

Arbitrary key-value pairs attached to the Orbit Media participant.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms/quick-sync/token" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "participant_name": "Jane Doe" }'

Node.js

const token = await orbit.video.rooms.token('quick-sync', { participant_name: 'Jane Doe' })
console.log(token.data.token, token.data.url)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/rooms/quick-sync/token",
                  headers=headers, json={"participant_name": "Jane Doe"})
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/quick-sync/token",
		bytes.NewBuffer([]byte(`{"participant_name":"Jane Doe"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms/quick-sync/token');
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, '{"participant_name":"Jane Doe"}');
echo curl_exec($ch);

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "url": "wss://media.orbit.devotel.io"
  },
  "meta": { "request_id": "req_video_012", "timestamp": "2026-05-10T14:01:00Z" }
}

Error codes: 503 SERVICE_UNAVAILABLE, 400 (validation), 403, 500 TOKEN_GENERATION_FAILED.

Room templates

Save a room’s setup once — participant cap, recording and egress defaults, media policy, E2EE, region, and the waiting-room lobby — as a named, reusable room template (“meeting template”), then spin up consistently-configured rooms from it. Templates are tenant-scoped and stored as a non-secret config preset; recording-storage credentials and consent receipts are never persisted on a template. Reads (list, get) require the video:read scope (video:write works as a superset). Writes (create, update, delete, instantiate) require the owner, admin, or developer role plus the video:write scope. Each tenant may keep up to 100 templates. The template config is a bag of optional knobs that map 1:1 to the identically-named Schedule a Room fields: max_participants, max_duration_minutes, recording_enabled, recording_format, recording_output, simulcast, spatial_layers, max_bitrate_kbps, video_codec, svc_scalability_mode, e2ee, e2ee_key_provider, virtual_background, noise_suppression, spatial_audio, audio_only, captions_required, region, waiting_room, and waiting_room_auto_promote. An empty config ({}) is a valid “all defaults” template. Unknown keys are rejected, and svc_scalability_mode is only valid with a vp9 or av1 video_codec.

List Room Templates

GET /api/v1/video/room-templates Returns the tenant’s saved templates. Requires the video:read scope. Rate limit: 120 requests/minute per tenant (auth-read bucket).

curl -X GET "https://api.orbit.devotel.io/api/v1/video/room-templates" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "templates": [
      {
        "id": "vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002",
        "name": "Sales demo",
        "description": "Recorded demo with a lobby",
        "config": {
          "max_participants": 25,
          "recording_enabled": true,
          "recording_format": "composite",
          "waiting_room": true,
          "region": "eu"
        },
        "created_at": "2026-07-06T10:00:00.000Z",
        "updated_at": "2026-07-06T10:00:00.000Z",
        "created_by": "user_2ab..."
      }
    ],
    "total": 1
  },
  "meta": { "request_id": "req_video_rt_001", "timestamp": "2026-07-06T10:05:00Z" }
}

Get a Room Template

GET /api/v1/video/room-templates/{id} Fetch a single template by its vrtpl_-prefixed id. Requires the video:read scope. A missing id returns 404 NOT_FOUND.

curl -X GET "https://api.orbit.devotel.io/api/v1/video/room-templates/vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Save a Room Template

POST /api/v1/video/room-templates Create a new template. Owner/admin/developer only. Names must be unique within the tenant (case-insensitive).

name

string

required

Label shown in the template picker (1–120 characters). Unique within the tenant (case-insensitive).

description

string

Optional operator description (up to 500 characters).

config

object

required

The reusable, non-secret room-config preset (see the knob list above). May be an empty object for an “all defaults” template.

Rate limit: 60 requests/minute per tenant (auth-write bucket).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/room-templates" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales demo",
    "description": "Recorded demo with a lobby",
    "config": {
      "max_participants": 25,
      "recording_enabled": true,
      "recording_format": "composite",
      "waiting_room": true,
      "region": "eu"
    }
  }'

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/video/room-templates", headers=headers, json={
    "name": "Sales demo",
    "description": "Recorded demo with a lobby",
    "config": {"max_participants": 25, "recording_enabled": True, "recording_format": "composite", "waiting_room": True, "region": "eu"},
})
print(r.json())

package main

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

func main() {
	body := []byte(`{"name":"Sales demo","config":{"max_participants":25,"recording_enabled":true}}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/video/room-templates", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/room-templates');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY'), 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"Sales demo","config":{"max_participants":25,"recording_enabled":true}}');
echo curl_exec($ch);

{
  "data": {
    "template": {
      "id": "vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002",
      "name": "Sales demo",
      "description": "Recorded demo with a lobby",
      "config": { "max_participants": 25, "recording_enabled": true, "recording_format": "composite", "waiting_room": true, "region": "eu" },
      "created_at": "2026-07-06T10:00:00.000Z",
      "updated_at": "2026-07-06T10:00:00.000Z",
      "created_by": "user_2ab..."
    }
  },
  "meta": { "request_id": "req_video_rt_002", "timestamp": "2026-07-06T10:00:00Z" }
}

Error codes: 400 VIDEO_ROOM_TEMPLATE_INVALID (duplicate name or template cap reached), 422 VALIDATION_ERROR, 403, 500 VIDEO_ROOM_TEMPLATE_CREATE_FAILED.

Update a Room Template

PATCH /api/v1/video/room-templates/{id} Partial update. Supply at least one of name, description, or config; description: null clears the description. config is a full replacement of the stored preset (validated in whole), not a deep-merge — send the complete config you want, not just the changed knobs. Owner/admin/developer only.

curl -X PATCH "https://api.orbit.devotel.io/api/v1/video/room-templates/vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "max_participants": 50, "recording_enabled": true, "recording_format": "both" } }'

Error codes: 400 (invalid field or name collision), 404 NOT_FOUND, 422 VALIDATION_ERROR (no updatable field supplied), 403, 500 VIDEO_ROOM_TEMPLATE_UPDATE_FAILED.

Delete a Room Template

DELETE /api/v1/video/room-templates/{id} Remove a template. A missing id returns 404 NOT_FOUND, so a delete never silently no-ops a mistyped id. Owner/admin/developer only.

curl -X DELETE "https://api.orbit.devotel.io/api/v1/video/room-templates/vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": { "deleted": "vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002" },
  "meta": { "request_id": "req_video_rt_003", "timestamp": "2026-07-06T11:00:00Z" }
}

Create a Room from a Template

POST /api/v1/video/room-templates/{id}/instantiate Create a live (or scheduled) room from a saved template. The template’s stored config is applied to the room-create path with the same per-tier participant-cap gate, required-captions guard, media/E2EE/region knobs, waiting-room lobby, recording-consent gate and auto-start, inbox backlink, and audit trail as Schedule a Room. Owner/admin/developer only.

name

string

required

Label for the new room (1–200 characters). Per-instance — it does not change the template.

scheduled_at

string

Optional ISO 8601 date-time to schedule the room for. Omit or send null to create it live now.

Consent-receipt id threaded into the recording-consent gate when the template auto-starts a recording in a two-party-consent jurisdiction.

Rate limit: 60 requests/minute per tenant (auth-write bucket).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/video/room-templates/vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002/instantiate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme demo — Tuesday" }'

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post(
    "https://api.orbit.devotel.io/api/v1/video/room-templates/vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002/instantiate",
    headers=headers, json={"name": "Acme demo — Tuesday"})
print(r.json())

{
  "data": {
    "room_id": "8e7c9a02-3e94-4f4f-b2a8-91d6b9b3a002",
    "room_sid": "RM_abc123",
    "host_token": "eyJhbGciOi...",
    "ws_url": "wss://media.orbit.devotel.io",
    "template_id": "vrtpl_8e7c9a023e944f4fb2a891d6b9b3a002",
    "composite_egress_id": null,
    "track_egress_id": null
  },
  "meta": { "request_id": "req_video_rt_004", "timestamp": "2026-07-06T12:00:00Z" }
}

Error codes: 400 VIDEO_PARTICIPANTS_CAP_EXCEEDED (template max_participants above your plan cap), 404 NOT_FOUND, 422 VALIDATION_ERROR / RECORDING_CONSENT_REQUIRED, 503 SERVICE_UNAVAILABLE (video service not configured) or 503 VIDEO_CAPTIONS_NOT_CONFIGURED (template requires live captions the deployment lacks), 500 VIDEO_ROOM_TEMPLATE_INSTANTIATE_FAILED.

Room usage analytics

Operator-facing aggregate of how your organization is using video rooms: sessions over time, average and peak concurrent participants, total room-minutes, recording success rate, and join failures. Read-only, tenant-scoped. This is the room-level usage report — distinct from per-recording chapter themes and per-call connection quality.

Get Room Usage

GET /api/v1/video/rooms-analytics/usage Returns a window summary plus a daily time series aggregated from realized room sessions. One bucket per UTC day. Requires the video:read scope (video:write works as a superset).

from

string

Start of the window, ISO 8601 (e.g. 2026-06-01T00:00:00Z). Defaults to 30 days before to.

string

End of the window, ISO 8601. Defaults to now. Must be later than from or the request returns 400 INVALID_WINDOW.

The daily series is capped at 366 buckets (a full leap year). A longer window still returns a summary covering the entire range, but the daily array is truncated to the first 366 days. The summary window anchors on each session’s start time, falling back to its creation time, so rooms that were created but never connected still appear in the totals as join failures.

Rate limit: 120 requests/minute per tenant (auth-read bucket).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/video/rooms-analytics/usage?from=2026-06-01T00:00:00Z&to=2026-06-28T00:00:00Z" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const usage = await orbit.video.roomsAnalytics.usage({
  from: '2026-06-01T00:00:00Z',
  to: '2026-06-28T00:00:00Z',
})
console.log(usage.data.summary, usage.data.daily)

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-analytics/usage",
                 headers=headers, params={"from": "2026-06-01T00:00:00Z", "to": "2026-06-28T00:00:00Z"})
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/video/rooms-analytics/usage?from=2026-06-01T00:00:00Z&to=2026-06-28T00:00:00Z", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/video/rooms-analytics/usage?from=2026-06-01T00:00:00Z&to=2026-06-28T00:00:00Z');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "window": {
      "from": "2026-06-01T00:00:00.000Z",
      "to": "2026-06-28T00:00:00.000Z"
    },
    "summary": {
      "total_sessions": 184,
      "total_room_seconds": 712800,
      "total_room_minutes": 11880,
      "avg_peak_participants": 3.4,
      "max_peak_participants": 22,
      "total_join_events": 612,
      "recordings_started": 41,
      "recordings_succeeded": 39,
      "recording_success_rate": 0.95,
      "join_failures": 6,
      "error_sessions": 2
    },
    "daily": [
      {
        "date": "2026-06-01",
        "sessions": 7,
        "room_minutes": 432,
        "avg_peak_participants": 3.1,
        "max_peak_participants": 9
      },
      {
        "date": "2026-06-02",
        "sessions": 11,
        "room_minutes": 690,
        "avg_peak_participants": 4.0,
        "max_peak_participants": 14
      }
    ]
  },
  "meta": { "request_id": "req_video_013", "timestamp": "2026-06-28T09:00:00Z" }
}

Response fields

window — the resolved from/to (ISO 8601) after defaults are applied.
summary.total_sessions — realized room sessions in the window.
summary.total_room_seconds / total_room_minutes — total room wall-clock across all sessions.
summary.avg_peak_participants — average of each session’s peak concurrent participants (sessions that never connected are excluded so empty rooms don’t drag it down).
summary.max_peak_participants — busiest single moment in the window.
summary.total_join_events — count of participant join events (a rejoin counts twice).
summary.recordings_started / recordings_succeeded — recordings attempted vs landed.
summary.recording_success_rate — recordings_succeeded / recordings_started, 0–1, or null when no recording was attempted.
summary.join_failures — sessions where the room was created but no participant ever connected.
summary.error_sessions — sessions that terminated with an error.
daily[] — one bucket per UTC day with date (YYYY-MM-DD), sessions, room_minutes, avg_peak_participants, and max_peak_participants.

Error codes: 400 VALIDATION_ERROR (malformed from/to), 400 INVALID_WINDOW (from later than to), 403 (missing video:read scope), 500 VIDEO_ROOM_USAGE_ANALYTICS_FAILED.

Inbound webhook

Orbit Media posts room and recording lifecycle events to POST /api/v1/video/webhook. The endpoint is platform-managed — you don’t call it directly. Events received here drive started_at / ended_at / recording_url updates on video_rooms and the matching inbox-conversation status transitions. Orbit Media signs each delivery with a JWT minted from the API secret; Orbit validates the signature via the SFU’s WebhookReceiver (carried over from the LiveKit OSS fork) before processing.

​Video API

​Scheduled rooms

​Schedule a Room

​List Scheduled Rooms

​Get a Scheduled Room

​Join a Scheduled Room

​End a Scheduled Room

​Start Recording

​Stop Recording

​Guest invites

​Create an Invite

​List Invites

​Revoke an Invite

​Redeem an Invite (public)

​Host admin controls

​Kick a Participant

​Mute a Participant

​Simulive broadcast

​Get Simulive Config

​Configure a Simulive Broadcast

​Cancel a Simulive Broadcast

​Get Simulive Playout

​Ad-hoc rooms

​Create an Ad-hoc Room

​List Ad-hoc Rooms

​Get an Ad-hoc Room

​Delete an Ad-hoc Room

​Issue a Participant Token

​Room templates

​List Room Templates

​Get a Room Template

​Save a Room Template

​Update a Room Template

​Delete a Room Template

​Create a Room from a Template

​Room usage analytics

​Get Room Usage

​Inbound webhook

​See also

Video API

Scheduled rooms

Schedule a Room

List Scheduled Rooms

Get a Scheduled Room

Join a Scheduled Room

End a Scheduled Room

Start Recording

Stop Recording

Guest invites

Create an Invite

List Invites

Revoke an Invite

Redeem an Invite (public)

Host admin controls

Kick a Participant

Mute a Participant

Simulive broadcast

Get Simulive Config

Configure a Simulive Broadcast

Cancel a Simulive Broadcast

Get Simulive Playout

Ad-hoc rooms

Create an Ad-hoc Room

List Ad-hoc Rooms

Get an Ad-hoc Room

Delete an Ad-hoc Room

Issue a Participant Token

Room templates

List Room Templates

Get a Room Template

Save a Room Template

Update a Room Template

Delete a Room Template

Create a Room from a Template

Room usage analytics

Get Room Usage

Inbound webhook

See also