Session management guide
Create, manage, and control live streaming sessions.
Every stream is attached to exactly one session. Create the session, mint a connection token for each participant, and join from the browser.
Creating a session
curl -X POST https://api.synento.com/v1/projects/{projectId}/sessions \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"name": "Team Standup"}'Response:
{ "data": {
"id": "9b1c4e7a2d3f4a8b9c0d1e2f3a4b5c6d",
"project_id": "5e0f3c1a9d8b4e2f8a7c6b5d4e3f2a1b",
"name": "Team Standup",
"created_by": "api",
"is_public": false,
"started_at": null, // set when the first participant joins
"ended_at": null, // set when the last participant leaves
"created_at": "2026-01-15T10:30:00.000Z"
}, "error": null }Session and project ids are 32 hexadecimal characters. POST /v1/sessions
(no project in the path) does the same thing for the API key's own project.
Options
| Field | Required | Default | Description |
|---|---|---|---|
name | No | "unnamed" | Display name for the session |
Session lifecycle
Created → Waiting for participants...
↓ (first join)
Started — Active streaming, recording begins
↓ (participant leaves)
Still Started (other participants remain)...
↓ (last participant leaves)
Ended — Recording complete, replay available immediatelyLifecycle timestamps
| Field | Set when | Value |
|---|---|---|
created_at | Session created via API | ISO 8601 timestamp |
started_at | First participant joins | ISO 8601 timestamp |
ended_at | Last participant leaves | ISO 8601 timestamp |
An ended session is not locked: if people join it again (after everyone
refreshed, say), the call continues into the same recording. started_at
keeps the first start; ended_at goes back to null while the call is live
again and is set afresh when the last participant leaves, so the two always
span the whole recording.
ended_at - started_at is how long the session ran. It is not what you are
billed for: usage is metered in participant-minutes, each participant's own
connected time, so a four-person call for ten minutes is 40.
Listing sessions
Retrieve all sessions for a project:
curl https://api.synento.com/v1/sessions \
-H "Authorization: Bearer sk_live_xxxxx"Returns sessions sorted by created_at, newest first: up to 500 by default.
Page with ?limit= and ?offset=. The SDK calls the same endpoint (first page
only):
const sessions = await synento.listSessions();
// [{ id, projectId, name, createdBy, isPublic, startedAt, endedAt, createdAt }, ...]Getting session details
Fetch a single session:
curl https://api.synento.com/v1/projects/{projectId}/sessions/{sessionId} \
-H "Authorization: Bearer sk_live_xxxxx"Connection tokens
Every participant needs a connection token to join or replay.
For live streaming
curl -X POST https://api.synento.com/v1/sessions/{sessionId}/connection \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"user_id": "alice"}'For replay mode
curl -X POST https://api.synento.com/v1/sessions/{sessionId}/connection \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"user_id": "viewer", "replay": true, "from_ts": 0, "speed": 1.0}'Token connection parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
user_id | string | required over HTTP (the SDK sends "anonymous" if you omit it) | Participant identifier: 1–64 letters, digits, - or _. The WebSocket must connect with the same id |
replay | boolean | false | If true, the token is for a replay stream instead of a live call |
from_ts | number (epoch ms) | 0 | Replay only. Where to start; 0 means the beginning. Use a time between the manifest's start_ts and end_ts |
speed | number | 1.0 | Replay only. Playback speed multiplier; any positive number |
focus | string | "" | Replay only. A participant's user_id to replay alone; empty (or an unknown id) replays everyone |
A live token is refused with 403 PLAN_LIMIT when the call or the account is
full (see below); a replay token is refused the same way once a Free account
has used its replay allowance.
Token response
{ "data": {
"access_token": "eyJhbGc...", // a JWT
"expires_in": 3600, // seconds the token can be used to connect
"session": "9b1c4e7a2d3f4a8b9c0d1e2f3a4b5c6d"
}, "error": null }The token is checked when a WebSocket connects, not afterwards: a call that is already connected is not cut off when its token expires. Mint a fresh token for each new connection.
Hand the browser the token together with the WebSocket URL from
resolveWsUrl. @synento/client sends the token as a WebSocket subprotocol,
so it never appears in a URL:
const wsUrl = synento.resolveWsUrl({ sessionId, userId: "alice" });
// → wss://api.synento.com/ws?session=9b1c…&user_id=alice
return { wsUrl, token: token.accessToken };See Getting started for the full server route and
browser code. A replay token connects to the same URL with &replay=true
added; the server then streams the recording back over the binary wire
protocol at the chosen speed. Neither SDK plays that stream yet, so for replay
in your app use the playback API or the MP4 export described in
Recordings & Replay.
Session visibility management
Sessions are private by default: their playback, manifest and export routes
need your API key, or an expiring replay link
(Access Control). Making a session public opens its
playback, timeline and manifest at /v1/public/sessions/{sessionId}/... to
anyone who has the session id, without authentication, and lists it at
GET /v1/public/sessions?project_id={projectId}.
Toggle public/private
# Make this session publicly accessible (no auth needed for replay)
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"is_public": true}'
# Revert to private
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"is_public": false}'Response: { "data": { "id": "…", "is_public": true }, "error": null }.
Public replay still counts against your plan's replay allowance, since each viewer reads the recording afresh.
Setting via SDK
await synento.setSessionVisibility(sessionId, true); // make publicDeleting a session
curl -X DELETE https://api.synento.com/v1/sessions/{sessionId} \
-H "Authorization: Bearer sk_live_xxxxx"await synento.deleteSession(sessionId);This disconnects anyone still in the call and erases the recording, its MP4 exports and its replay links. It cannot be undone. Usage the session already accrued still counts toward the billing period.
Billing and session limits
New session creation is checked against billing limits:
- Free plan: 10,000 participant-minutes per billing period and 25 GiB of recordings held, across the organisation
- Past the allowance with no active subscription, new sessions are refused with
503 SERVICE_UNAVAILABLEand a message naming what ran out - Pay-as-you-go: no monthly fee; the same 10,000 participant-minutes free, then $0.003 each, and recordings stored free for their first 30 days
- Call size: up to 4 people per call on Free (and 8 in calls at once across
the organisation), up to 16 on pay-as-you-go. Minting a live connection token past
either limit returns
403 PLAN_LIMITwith a message naming the limit.
Check current limits before creating sessions:
curl https://api.synento.com/v1/billing/limits \
-H "Authorization: Bearer sk_live_xxxxx"const limits = await synento.getBillingLimits();
if (limits.isBlocked) {
console.error(limits.statusMessage); // says what ran out
}Common patterns
Create session, get token, connect (all in one flow)
// On your server:
const session = await synento.createSession({ name: "Team Meeting" });
const token = await synento.createConnectionToken(session.id, { userId: "alice" });
const wsUrl = synento.resolveWsUrl({ sessionId: session.id, userId: "alice" });
// Send { wsUrl, token: token.accessToken } to the browser, where
// @synento/client joins the call with them (see Getting Started).Check every ended session recorded media
const sessions = await synento.listSessions();
for (const session of sessions) {
if (!session.endedAt) continue;
const manifest = await synento.getSessionManifest(session.id);
// Only tracks that hold media are listed, and only participants with one.
for (const p of manifest.participants) {
console.log(session.id, p.user_id, p.tracks.map((t) => t.kind)); // e.g. ["cam", "mic"]
}
}