Synento docs
Guides

Session management guide

Create, manage, and control live streaming sessions.

View as Markdown

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

FieldRequiredDefaultDescription
nameNo"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 immediately

Lifecycle timestamps

FieldSet whenValue
created_atSession created via APIISO 8601 timestamp
started_atFirst participant joinsISO 8601 timestamp
ended_atLast participant leavesISO 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

ParameterTypeDefaultDescription
user_idstringrequired 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
replaybooleanfalseIf true, the token is for a replay stream instead of a live call
from_tsnumber (epoch ms)0Replay only. Where to start; 0 means the beginning. Use a time between the manifest's start_ts and end_ts
speednumber1.0Replay only. Playback speed multiplier; any positive number
focusstring""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 public

Deleting 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_UNAVAILABLE and 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_LIMIT with 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"]
  }
}

On this page