Live Video API

Preview

REST · WebRTC · HLS

Live Video API

Two complementary products in one API: interactive WebRTC rooms for conversations, and live streaming for one-to-many broadcasts — RTMP/SRT in, HLS out, with recording, DVR, and webhooks.

Interactive rooms

Multi-party WebRTC sessions with capacity, metadata, and optional cloud recording.

Live streaming

One-to-many broadcast with RTMP/SRT ingest and adaptive HLS / LL-HLS playback.

Short-lived join tokens

Issue scoped client tokens (host, participant, viewer) without exposing REST credentials.

Regional media edge

Connect participants and ingest to the nearest region across Africa and beyond.

Recording & DVR

Room composites, stream VOD archives, and optional live DVR windows for viewers.

Lifecycle webhooks

Room join/leave, stream live/ended, and recording.ready events in real time.

Room join

<800ms

Token → media (p95)

Room size

Participants max

Stream viewers

100k+

CDN fan-out

LL-HLS latency

3–8s

Glass-to-glass target

Authentication

All REST requests use HTTP Basic Auth with your dashboard Base64 token: Authorization: Basic <token>. Auth guide →

Two credential types

REST Basic Auth — dashboard Base64 token for server-side room management only. Never ship this to browsers or mobile apps.
Client join tokens — short-lived JWTs from POST /v1/video/rooms/:roomId/tokens used by the Web SDK / native clients to enter a room.

How it works

Your backend creates a room with POST /v1/video/rooms using Basic Auth.
Your backend issues a join token per user with a role (host, participant, or viewer) and a TTL.
Your client loads the Sendexa Video Web SDK (or native SDK) with the room ID and join token — never your REST secret.
Participants publish/subscribe media through the regional SFU. Optional cloud recording composites the session when the room ends.
Webhooks notify your backend of room lifecycle, joins/leaves, and recording readiness.

text

Browser / App                 Your Backend                 Sendexa
     |                              |                          |
     |  request session             |                          |
     |----------------------------->|  POST /v1/video/rooms    |
     |                              |------------------------->|
     |                              |  roomId, region          |
     |                              |<-------------------------|
     |                              |  POST .../tokens         |
     |                              |------------------------->|
     |  roomId + join token         |  token, expiresAt        |
     |<-----------------------------|                          |
     |  SDK connect(roomId, token)  |                          |
     |-------------------------------------------------------->|
     |  WebRTC media (SFU)          |                          |
     |<=======================================================>|
     |                              |  webhooks (lifecycle)    |
     |                              |<-------------------------|

Quick start

Create a room and mint a host token in two requests. Base URL: https://api.sendexa.co

Bash

# 1. Create a room
curl -X POST 'https://api.sendexa.co/v1/video/rooms' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN' \
  -d '{
    "name": "Support Session #1042",
    "maxParticipants": 4,
    "record": true,
    "metadata": { "ticketId": "TKT-1042" }
  }'

# 2. Issue a host join token (replace ROOM_ID)
curl -X POST 'https://api.sendexa.co/v1/video/rooms/ROOM_ID/tokens' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN' \
  -d '{
    "identity": "agent-ada",
    "role": "host",
    "ttl": 3600
  }'

Example create-room response

JSON

{
  "success": true,
  "code": "VIDEO_ROOM_CREATED",
  "message": "Video room created successfully.",
  "requestId": "REQ-1782001000001",
  "timestamp": "2026-07-12T10:15:00.000Z",
  "data": {
    "roomId": "rm_8f3a2c1b0e9d",
    "name": "Support Session #1042",
    "status": "ready",
    "maxParticipants": 4,
    "participantCount": 0,
    "record": true,
    "region": "af-west",
    "metadata": { "ticketId": "TKT-1042" },
    "createdAt": "2026-07-12T10:15:00.000Z",
    "emptyTimeoutSeconds": 300
  }
}

Next: full getting-started guide including Web SDK embed and media constraints.

API endpoints

POST

/v1/video/rooms

Create Room

Interactive multi-party WebRTC session.

View docs

POST

/v1/video/rooms/:id/tokens

Issue Token

Mint host / participant / viewer join tokens.

Live broadcast with RTMP/SRT ingest + HLS out.

CDN playback URLs, embed player, signed access.

View docs

POST

Ingest

RTMP · SRT

OBS, FFmpeg, encoder profiles, room simulcast.

Room + stream lifecycle and recording events.

View docs

Participant roles

Role	Publish	Subscribe	Room control
host	Camera, mic, screen	All tracks	Mute others, end room (client API)
participant	Camera, mic, screen	All tracks	Self only
viewer	None	All tracks	None

Media regions

Rooms are pinned to a media region at creation time (auto-selected from client IP heuristics or set explicitly when supported). Participants connect to the SFU in that region for optimal RTT.

af-west

Africa West

Accra / Lagos edge

af-south

Africa South

Johannesburg

eu-west

Europe West

London / Frankfurt

us-east

US East

Virginia

Common use cases

Telehealth & support

1:1 or small-group consults with recording for compliance. Use host for clinicians and participant for patients.

Live classes & webinars

One host, many viewers. Raise capacity, keep most clients on viewer tokens to reduce uplink load.

Interviews & KYC video

Short-lived rooms with strict TTL tokens and webhook-driven archival when video.recording.ready fires.

Room statuses

Status	Meaning	Typical next step
ready	Room provisioned; waiting for first participant	Issue tokens and connect clients
active	At least one participant connected	Session in progress; monitor webhooks
ended	Session closed via /end or empty timeout	Await recording.ready if record=true
deleted	Room resource removed via DELETE	Create a new room for a new session

Common error codes

HTTP	Code	Cause
400	`INVALID_ROOM_PARAMS`	maxParticipants out of range or invalid metadata
401	`UNAUTHORIZED`	Missing or invalid Basic Auth on REST calls
403	`VIDEO_NOT_ENABLED`	Live Video not enabled on this business account
404	`ROOM_NOT_FOUND`	roomId does not exist or was deleted
409	`ROOM_ALREADY_ENDED`	Cannot mint tokens or join an ended room
429	`RATE_LIMIT_EXCEEDED`	Too many room/token requests — back off and retry

Best practices

Always create rooms and tokens server-side; only join tokens leave your backend.
Use unique identity values per user (e.g. user ID) so presence and webhooks stay attributable.
Prefer short token TTLs (15–60 minutes) and re-issue rather than long-lived tokens.
Subscribe to webhooks instead of polling GET /v1/video/rooms/:roomId for participant changes.
Call POST .../end when the business session is over so recording can finalize and billing stops.
Store roomId and optional metadata keys (ticket, appointment ID) for reconciliation.

Getting started

Room → token → Web SDK

POST

/v1/video/rooms

Webhooks

Lifecycle & recording