API Reference
Complete endpoint documentation for the Synento server API. Base URL: https://api.synento.com
Complete endpoint documentation for the Synento server API. The same routes are described machine-readably at synento.com/openapi.json.
Base URL: https://api.synento.com in production, http://localhost:8080 when
running the server locally.
Authentication
Endpoints take one of these credentials, and each endpoint below says which:
- API key —
Authorization: Bearer sk_live_xxxxxorX-API-Key: sk_live_xxxxx(direct API, CLI, and server-side integrations) - Dashboard login session —
synento_sessionHTTP-only cookie set byPOST /v1/auth/login(used by the Synento dashboard)
An API key belongs to one project. Session routes act only on that project's sessions; the management routes (projects, keys, webhooks, members, billing) act for the key's whole organisation. Keep it on your server.
Two narrower credentials exist for agents:
- Restricted key —
Authorization: Bearer rk_live_xxxxx. One project, and accepted only byPOST /v1/sessions,POST /v1/projects/{projectId}/sessions,POST /v1/sessions/{sessionId}/connection(live and replay) andGET /v1/sessions/{sessionId}/manifest. Every other route refuses it with403 FORBIDDENand a message naming the project secret key. This is what an agent writes into your app's environment. Manage them withGET/POST /v1/restricted-keysandDELETE /v1/restricted-keys/{keyId}. - Agent token (
sat_…) and OAuth access tokens — accepted only by the MCP endpoint at/mcp, never by the REST API. See Connect your agent. Agent tokens, connected OAuth clients and the agent audit log are managed from a signed-in session:/v1/agent-tokens,/v1/oauth/grants,/v1/agent-activity.
Rate limits
- With an API key (
sk_live_…orrk_live_…): 1,000 requests a minute per key. That covers minting a connection token for every person joining a busy hour of calls. - Without a key (public reads, sign-in, dashboard requests): 100 requests a minute per client address.
- Sign-up and account email (
POST /v1/auth/register,/v1/auth/resend-verification,/v1/auth/forgot-password): additionally 10 an hour per client address.
Past the limit, requests get 429 with a retry-after header until the
window rolls over; nothing is blocked for longer. WebSocket connections
(/ws) and /health are not rate limited.
Response Format
All JSON responses use a standard envelope:
{ "data": { ... }, "error": null } // Success
{ "data": null, "error": { "code": "...", "message": "...", "status": 404 } } // ErrorEvery error is sent with a non-2xx HTTP status, and error.status repeats it,
so treat any status of 400 or above as a failure and show error.message.
Error codes: BAD_REQUEST (400), UNAUTHORIZED (401), FORBIDDEN (403 — also
a restricted key on a route that needs the project secret key), PLAN_LIMIT
(403 — a plan allowance or limit was reached), NOT_FOUND (404), CONFLICT
(409), RATE_LIMITED (429), SERVER_ERROR (500), SERVICE_UNAVAILABLE (503 —
includes "usage limits exceeded" when a Free organisation is past its
allowance).
Successful creates answer 200 unless a different status is shown below.
Idempotency
POST /v1/sessions, POST /v1/projects/{projectId}/sessions,
POST /v1/sessions/{sessionId}/replay-links and
PUT /v1/projects/{projectId}/retention accept an Idempotency-Key header. A
repeat with the same key and credential returns the first successful response
instead of acting again; failed requests are not cached and can be retried.
Pagination
List endpoints that page take limit and offset query parameters. limit is
capped at 500.
Health
Get Health Status
| Method | GET |
| Path | /health |
| Auth | None (public) |
Response: plain text ok.
Get Readiness
| Method | GET |
| Path | /ready |
| Auth | None (public) |
Response: { "data": { "ready": true, "checks": { "database": "ok", "s2": "ok" } }, "error": null }, or 503 when a check fails.
Projects
List Projects
| Method | GET |
| Path | /v1/projects |
| Auth | API key or dashboard login session (organisation-wide) |
With an API key, the response header X-Synento-Authenticated-Project-Id names
the key's own project.
Response:
{ "data": [
{ "id": "...", "name": "My App", "org_id": "...", "environment": "dev", "created_at": "..." }
], "error": null }Create Project
| Method | POST |
| Path | /v1/projects |
| Auth | API key or dashboard login session |
Request body:
{ "name": "My App", "environment": "production" }environment is optional and stored as dev (the default), staging or
prod; development and production are accepted as spellings of dev and
prod. A Free organisation can hold up to 3 projects (403 FORBIDDEN past that).
Response:
{ "data": { "id": "...", "name": "My App", "org_id": "...", "environment": "prod", "created_at": "..." }, "error": null }A new project has no API key. Your existing key cannot create sessions in it;
mint one for it with POST /v1/projects/{projectId}/api-keys.
Update Project
| Method | PATCH |
| Path | /v1/projects/:projectId |
| Auth | API key or dashboard login session (same organisation) |
Request body: { "name": "Renamed", "environment": "staging" } — name is required, environment optional. Response: the updated project.
Delete Project
| Method | DELETE |
| Path | /v1/projects/:projectId |
| Auth | API key, or dashboard login session with the owner or admin role |
Erases every session and recording in the project. An organisation keeps at
least one project (409 CONFLICT for the last one). Response: { "deleted": true, "id": "..." }.
Recording retention
| Method | GET or PUT |
| Path | /v1/projects/:projectId/retention |
| Auth | API key or dashboard login session (same organisation) |
How long recordings are kept, in days. Free accounts can set 1–7. Pay-as-you-go can set 1–90. New projects start at 7 on Free and 30 on pay-as-you-go.
PUT request body:
{ "retention_days": 7 }GET response:
{ "data": { "project_id": "...", "retention_days": 7, "max_retention_days": 7, "plan": "free" }, "error": null }Project Analytics
| Method | GET |
| Path | /v1/projects/:projectId/analytics/session-insights and /v1/projects/:projectId/analytics/participant-metrics |
| Auth | API key or dashboard login session (same organisation) |
session-insights returns totalSessions, averageDurationMinutes,
peakConcurrentParticipants, byStatus (notStarted, running, ended) and
recentTrend (sessions per day for the last 7 days). participant-metrics
returns totalStreamingMinutes, averageConcurrentParticipants,
recordedSessions and totalSessions.
Session Management
Session ids, like project ids, are 32 hexadecimal characters.
Create Session
| Method | POST |
| Path | /v1/sessions (the key's own project) or /v1/projects/:projectId/sessions |
| Auth | API key or restricted key. The project must be the key's own project (403 otherwise). |
Request body (optional; the name defaults to unnamed):
{ "name": "Morning Standup" }Response:
{ "data": {
"id": "...", "project_id": "...", "name": "Morning Standup",
"created_by": "api", "is_public": false,
"started_at": null, "ended_at": null, "created_at": "..."
}, "error": null }started_at is set when the first participant joins and ended_at when the
session ends. Recording needs no flag: the session is recorded from the first
frame.
Billing: a Free organisation past its allowance cannot create sessions
(503 SERVICE_UNAVAILABLE, "Usage limits exceeded…").
Get Session
| Method | GET |
| Path | /v1/sessions/:sessionId or /v1/projects/:projectId/sessions/:sessionId |
| Auth | API key (the session's project) |
Response: a single session object in the envelope, the same fields as
Create Session: id, project_id, name, created_by,
is_public, started_at, ended_at, created_at. 404 if not found, 403
if it belongs to another project.
List Sessions
| Method | GET |
| Path | /v1/sessions |
| Auth | API key or dashboard login session |
With an API key, returns the key's project's sessions; pass ?project_id= for
another project in the same organisation. A dashboard session without
project_id gets the whole organisation's. Sorted by created_at, newest
first. Paged with limit (default 500) and offset.
Response:
{ "data": [
{ "id": "...", "project_id": "...", "name": "Session 1", "is_public": false, ... },
{ "id": "...", "project_id": "...", "name": "Session 2", "is_public": false, ... }
], "error": null }List Recordings
| Method | GET |
| Path | /v1/recordings |
| Auth | API key or dashboard login session |
Sessions that have ended, newest first, each with duration_ms. Same
project_id, limit (default 100) and offset parameters as List Sessions.
Delete Session
| Method | DELETE |
| Path | /v1/sessions/:sessionId |
| Auth | API key, or dashboard login session with the owner or admin role |
Erases the session and its recording: recorded streams, exported MP4s and
replay links. Usage it accrued still counts toward the billing period. Cannot
be undone. Response: { "deleted": true, "id": "...", ... }.
Set Session Visibility
| Method | PUT |
| Path | /v1/sessions/:sessionId/visibility |
| Auth | API key (the session's project) |
Request body:
{ "is_public": true } // or false to make privateResponse:
{ "data": { "id": "...", "is_public": true }, "error": null }Get Connection Token (Session)
| Method | POST |
| Path | /v1/sessions/:sessionId/connection |
| Auth | API key or restricted key (the session's project) |
Request body:
{ "user_id": "alice",
"replay": false, // omit or false for live; true for replay mode
"from_ts": 0, // replay only: start time, epoch ms (whole number, 0 or more)
"speed": 1.0, // replay only: speed multiplier, 0.25 to 16
"focus": "" // replay only: participant to focus on
}user_id is required: 1–64 letters, digits, - or _.
Response:
{ "data": {
"access_token": "...", // JWT
"expires_in": 3600, // seconds until expiry (one hour by default)
"session": "..." // session ID
}, "error": null }A live join past the plan's call size or concurrent-participant limit is
refused here with 403 PLAN_LIMIT, as is a live token for an organisation
past its Free allowance or suspended for non-payment, and a replay token once
the replay allowance is used. The same checks run again when the socket
connects, and calls already running are closed with 4002 if the
organisation becomes blocked.
Live Streaming (WebSocket)
Connect via WebSocket
| Method | GET (upgrade) |
| Path | /ws?session={sessionId}&user_id=alice (add &replay=true for a replay token) |
| Auth | Connection token from the /connection endpoint |
Send the token as a WebSocket subprotocol, alongside synento.v1:
Sec-WebSocket-Protocol: synento.v1, synento.token.{accessToken}The query parameter &access_token={token} is also accepted, but puts the
token in URLs and access logs.
The token must have been minted for the same session, the same user_id and
the same mode (live or replay). A refused connection is closed with code
1008 just after it opens, not failed at the handshake. Plan limits close
with 4001 (call full), 4002 (account concurrent-participant limit) or
4003 (replay allowance used).
Messages are binary, not JSON. Each starts with a one-byte message type;
media payloads are self-describing (EVC1 video frames, Opus or PCM audio) and
the server relays them without parsing them. Unless you are implementing a
client from scratch, use @synento/client, which handles
framing, codec negotiation, decoding, backpressure and reconnection.
Replay & Playback
Timestamps in this section (from_ts, start_ts, end_ts, minTs, maxTs)
are absolute, in epoch milliseconds. To read a session from the start, use the
timeline's minTs (or the manifest's start_ts) as from_ts: from_ts=0
reads a window that ends 30 seconds after 1970 and comes back empty.
Reading playback windows counts toward the plan's replay allowance; past it,
they are refused with 403 PLAN_LIMIT.
Get Session Manifest
| Method | GET |
| Path | /v1/sessions/:sessionId/manifest |
| Auth | API key, restricted key, or dashboard login session |
Returns the layout-agnostic reconstruction contract: participants, separated track index (cam/mic/screen), time bounds, stream paths, and capabilities (separated-tracks, event-timeline, configurable-layouts, plus director-track and captions when present).
Only tracks that hold recorded data are listed, so this is how to check that a
participant's camera and microphone actually reached Synento. A session nobody
has sent media to has participants: [] and null for epoch, start_ts
and end_ts. Timestamps are Unix milliseconds.
{ "data": {
"version": 1,
"session_id": "...",
"epoch": 1699876000000,
"start_ts": 1699876000000,
"end_ts": 1699876300000,
"participants": [
{ "user_id": "alice", "tracks": [
{ "kind": "cam", "stream_id": "a/.../media/alice/cam", "start_ts": 1699876001000, "end_ts": 1699876299000 }
]}
],
"streams": { "events": "a/.../events", "chat": "a/.../chat", "director": "a/.../director" },
"capabilities": ["separated-tracks", "event-timeline", "configurable-layouts"]
}, "error": null }Public sessions: GET /v1/public/sessions/:sessionId/manifest.
Get Playback Timeline (Metadata)
| Method | GET |
| Path | /v1/sessions/:sessionId/playback/timeline |
| Auth | API key or dashboard login session |
Returns compact timeline metadata without loading event data:
{ "data": {
"participantCount": 2,
"streamIds": ["a/.../events", "a/.../director", "a/.../meta", "a/.../chat", "a/.../media/alice/cam", "..."],
"totalEventsEstimated": 15420,
"minTs": 1699876000000,
"maxTs": 1699876300000,
"participantMinutes": 9.6
}, "error": null }minTs and maxTs are null for a session with nothing recorded.
participantMinutes sums each participant's camera and microphone span: what
what an MP4 export of the session counts against the plan's export allowance.
Get Playback Window (Windowed Stream Reading)
| Method | GET |
| Path | /v1/sessions/:sessionId/playback?from_ts={ms}&window_size=30000 |
| Auth | API key or dashboard login session |
Query parameters:
from_ts— start of the window, epoch milliseconds (start at the timeline'sminTs)window_size— length of the window in ms (optional, default 30000, at most 60000; read longer spans as consecutive windows)
Response:
{ "data": {
"start_ts": 1699876000000,
"end_ts": 1699876030000,
"window_size_ms": 30000,
"events": [
{ "timestamp": 1699876000040, "stream_id": "a/.../media/alice/cam",
"body_base64": "<base64-payload>" }
],
"streams": [
{ "stream_id": "a/.../media/alice/cam", "event_count": 900 }
]
}, "error": null }To read the next window, call again with from_ts set to this response's
end_ts; stop once you pass the timeline's maxTs.
Playback windows include events from all separated media tracks, the events timeline, director track, and chat. Media payloads are raw track bytes (WebCodecs EVC1 frames; older recordings hold JPEG/WebP images); timeline events are JSON in the envelope { v, type, ts, actor, data }.
Get Session Timeline
| Method | GET |
| Path | /v1/sessions/:sessionId/timeline |
| Auth | API key or dashboard login session |
Returns who joined and left the session, and when:
{
"data": {
"start": 1791558000000,
"end": 1791558900000,
"participants": ["alice", "bob"],
"events": [{ "timestamp": 1791558000000, "type": "join", "user_id": "alice" }]
},
"error": null
}type is join or leave. start and end are epoch milliseconds (0 for a session with no events).
Public Playback (Unauthenticated)
| Method | GET |
| Path | /v1/public/sessions/:sessionId/playback, /v1/public/sessions/:sessionId/playback/timeline, /v1/public/sessions/:sessionId/manifest |
| Auth | None — public sessions only (is_public = true); others answer 404 |
Same parameters and response shapes as the authenticated endpoints above.
Replay via Expiring Link
| Method | GET |
| Path | /v1/public/sessions/:sessionId/replay?token={linkToken}&from_ts={ms}&window_size=30000 |
| Auth | None — a replay link token for this session (or, without a token, a public session) |
Reads a playback window using an expiring replay link token. Same response
shape as playback. An unknown or expired token answers 404.
Export (MP4)
Export is asynchronous. Enqueue a job, poll status, then download the completed MP4.
Enqueue Session Export
| Method | GET |
| Path | /v1/sessions/:sessionId/export |
| Auth | API key or dashboard login session |
Query parameters (optional):
| Parameter | Values | Default |
|---|---|---|
layout | grid, presenter | grid |
orientation | landscape (1280×720), vertical (720×1280) | landscape |
focus | Participant user id (for presenter layout) | first participant |
Response (202):
{ "data": { "job_id": "550e8400-e29b-41d4-a716-446655440000" }, "error": null }Asking again for an identical export returns the existing job with
"reused": true and does not count against the plan's export allowance.
The allowance is counted in exported participant-minutes: each participant's
camera and microphone span, as the playback timeline's participantMinutes
reports it, counted once the export has rendered (a failed export counts
nothing). Both plans include 300 per billing period; past that, pay-as-you-go is
billed $0.004 per exported participant-minute.
Errors: 404 when the session has no recorded participants, 403 PLAN_LIMIT
when the plan's export minutes for the billing period are used and it cannot
bill for more (Free), and
503 SERVICE_UNAVAILABLE when a Free organisation is past its usage allowance.
Poll Export Job Status
| Method | GET |
| Path | /v1/exports/:jobId |
| Auth | API key or dashboard login session |
Response:
{ "data": {
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"room_id": "...",
"progress_pct": 100,
"download_url": "/v1/exports/550e8400-e29b-41d4-a716-446655440000/download"
}, "error": null }Status values: queued, processing, completed, failed (with an error
message). room_id is the session ID. download_url is a path on the API host.
Download Export MP4
| Method | GET |
| Path | /v1/exports/:jobId/download |
| Auth | API key or dashboard login session |
Response: binary MP4 (video/mp4) when the job is completed; 404 otherwise.
Delete Export
| Method | DELETE |
| Path | /v1/exports/:jobId |
| Auth | API key or dashboard login session |
Deletes the export's MP4 from storage. Afterwards the export answers 404 on
every export route (deleting it again included), and a new export request for
the session renders a fresh file. A deleted export still counts against the
period's export allowance, and its minutes stay billed if they were past it. No webhook
fires.
Response:
{ "data": { "deleted": true, "job_id": "550e8400-e29b-41d4-a716-446655440000" }, "error": null }Errors: 409 CONFLICT while the export is still queued or rendering (delete it
once it has finished); 404 when it does not exist, was already deleted, or
belongs to another project.
Transcripts
Post-call speech-to-text over every participant's microphone. Guide: Transcripts.
Request a Transcript
| Method | POST |
| Path | /v1/sessions/:sessionId/transcript |
| Auth | API key, restricted key (rk_live_) or dashboard login session |
Body (optional): { "language": "auto" }. auto detects each participant's
language, multi follows a speaker who switches languages, or a BCP-47 tag
such as en or pt-BR. Defaults to the project's setting. Send an
Idempotency-Key to make retries safe.
Response (202):
{ "data": {
"session_id": "…", "status": "pending", "language": "auto", "languages": [],
"speech_seconds": 0, "error_code": null, "created_at": "…", "completed_at": null,
"is_reused": false
}, "error": null }Asking again returns the transcript already queued, running or up to date with
"is_reused": true. If people rejoined and spoke since the last run, only the
new speech is transcribed. transcript.ready fires when it finishes.
Billed per minute of speech: silence and muted time are removed before transcription, and only what is sent counts, summed over participants. Both plans include 60 minutes per billing period; past that, pay-as-you-go is billed $0.006 a minute.
Errors: 409 CONFLICT when the session has not ended, is already transcribed
with a different language, or the organisation has too many transcripts in
progress; 400 for a malformed language; 403 PLAN_LIMIT when the plan's
transcription minutes are used and it cannot bill for more (Free);
503 SERVICE_UNAVAILABLE when transcription is not enabled on the server.
Get a Transcript
| Method | GET |
| Path | /v1/sessions/:sessionId/transcript |
| Auth | API key, restricted key (rk_live_) or dashboard login session |
Query parameters (optional):
| Parameter | Values | Default |
|---|---|---|
format | json, vtt, srt, txt | json |
lang | A language the transcript holds | all |
JSON response: the fields above plus origin_ts and cues:
{ "data": {
"status": "ready", "languages": ["en"], "speech_seconds": 412.6,
"origin_ts": 1794593215983,
"cues": [{ "start_ms": 1200, "end_ms": 4800, "speaker": "alice", "lang": "en", "text": "Thanks for joining." }]
}, "error": null }speaker is the participant's user id. Times are ms from origin_ts, the start
of the recording, which is also where an MP4 export starts. While the transcript
is pending or processing, JSON returns the cues written so far; vtt, srt
and txt answer 409 until it is ready. failed and skipped carry an
error_code: unavailable, allowance, unsupported_language,
provider_rejected or processing_failed.
Errors: 404 when no transcript was ever requested for the session.
Automatic Transcripts
| Method | GET, PUT |
| Path | /v1/projects/:projectId/transcription |
| Auth | API key or dashboard login session; PUT needs an owner or admin |
PUT { "enabled": true, "language": "auto" } transcribes every session in the
project a few minutes after it ends. GET also returns available, false when
the server has no speech-to-text provider configured.
Participant Redaction
Redact Participant
| Method | DELETE |
| Path | /v1/sessions/:sessionId/participants/:userId |
| Auth | API key (the session's project) |
Deletes all media track streams for the participant (cam, mic, screen), removes their lines from the session's transcript, and appends a participant.redacted event to the timeline. The rest of the session remains intact.
Exports made before the redaction are not changed or deleted, but they are never reused: the next export request renders a fresh file without the participant. earlierExports counts the earlier exports that may still show the participant (finished ones, and any still rendering when the redaction ran) and earlierExportIds lists their job ids, so you can remove them with Delete Export.
Response:
{ "data": {
"redacted": "alice",
"deletedStreams": 3,
"earlierExports": 1,
"earlierExportIds": ["550e8400-e29b-41d4-a716-446655440000"]
}, "error": null }Webhooks
An API key manages its own project's webhooks; pass project_id (query string
or body) for another project in the organisation. A dashboard session must pass
project_id.
List Webhooks
| Method | GET |
| Path | /v1/webhooks |
| Auth | API key or dashboard login session |
Response: every webhook for the project, active or paused. events is a
comma-separated string.
{ "data": [
{ "id": "...", "project_id": "...", "url": "https://example.com/hook",
"events": "session.created,session.ended", "is_active": true, "created_at": "..." }
], "error": null }Create Webhook
| Method | POST |
| Path | /v1/webhooks |
| Auth | API key or dashboard login session |
Request body:
{ "url": "https://example.com/hook",
"events": ["session.created", "session.started", "session.ended"] }Valid event types: session.created, session.started, session.ended, recording.ready, export.completed, transcript.ready. The URL must use https and resolve to a public address; private and loopback addresses are refused.
Response:
{ "data": { "id": "...", "project_id": "...", "url": "...",
"events": "session.created", "is_active": true, "created_at": "...",
"secret": "whsec_..." }, "error": null }secret signs this endpoint's deliveries and is returned only here, once.
Each endpoint has its own secret. See the
Webhooks guide for verifying signatures.
Update or Delete a Webhook
| Method | PATCH or DELETE |
| Path | /v1/webhooks/:id |
| Auth | API key or dashboard login session |
PATCH body takes is_active (false to pause, true to resume), events
(replaces the subscribed event types), or both:
{ "events": ["session.ended", "recording.ready"] }A request with an invalid field changes nothing. DELETE removes the endpoint.
Rotate a Webhook Secret
| Method | POST |
| Path | /v1/webhooks/:id/rotate-secret |
| Auth | API key or dashboard login session |
Response: { "data": { "id": "...", "secret": "whsec_..." }, "error": null }.
The new secret is returned only here, once, and signs every delivery from now
on; the old secret stops working immediately.
List Deliveries
| Method | GET |
| Path | /v1/webhooks/:id/deliveries |
| Auth | API key or dashboard login session |
Recent delivery attempts (limit, default 50): event_type, http_status,
ok, total_attempts, session_id, created_at.
Usage & Billing
All billing is per organisation; with an API key, the key's organisation.
Get Plans
| Method | GET |
| Path | /v1/billing/plans |
| Auth | None (public) |
The price book: for each plan, included participant-minutes, storage (GiB), replay minutes and exports, overage rates, call-size and concurrency limits, maximum retention and project limit.
Get Usage
| Method | GET |
| Path | /v1/usage |
| Auth | API key (that project's usage) or dashboard login session (the organisation's) |
Response: all-time totals and what they would cost on the current plan.
{ "data": {
"streaming_minutes_total": 125.3,
"storage_bytes_total": 524288000,
"replay_minutes_total": 40,
"billingCalculation": { "plan": "free", "streamingMinutesUsed": 125.3, "includedMinutes": 10000, "totalCost": 0, ... }
}, "error": null }Get Project Usage Records
| Method | GET |
| Path | /v1/projects/:projectId/usage |
| Auth | API key or dashboard login session (same organisation) |
Paged with limit (default 500) and offset.
Response:
{ "data": {
"summary": { "streaming_minutes_total": 125.3, "storage_bytes_total": 524288000 },
"records": [
{ "id": "...", "project_id": "...", "session_id": "...",
"usage_type": "streaming_minutes", "value": 125.3,
"recorded_at": "..." }
]
}, "error": null }usage_type is streaming_minutes (participant-minutes), storage_bytes or
replay_minutes.
Get Billing Summary
| Method | GET |
| Path | /v1/billing/summary |
| Auth | API key or dashboard login session |
Usage and cost for the current billing period: the Stripe subscription period,
or a rolling 30 days without a subscription (period.source says which).
Response:
{ "data": {
"plan": "free",
"subscriptionStatus": "none",
"period": { "start": "...", "end": "...", "source": "rolling" },
"usage": { "total_streaming_minutes": 125.3, "total_storage_bytes": 524288000, "total_replay_minutes": 40 },
"costBreakdown": {
"streamingMinutesUsed": 125.3, "includedMinutes": 10000, "billableStreamingMinutes": 0, "streamCost": 0,
"storageBytesUsed": 524288000, "includedStorageGib": 25, "billableStorageGib": 0, "storageCost": 0,
"replayMinutesUsed": 40, "includedReplayMinutes": 1500, "billableReplayMinutes": 0, "replayCost": 0,
"baseCost": 0, "totalCost": 0, "hasPaidUsage": false, "plan": "free"
},
"planConfig": { ... }
}, "error": null }Storage fields are in GiB (2³⁰ bytes) except storageBytesUsed, which is bytes. On pay-as-you-go, storage counts only recordings older than 30 days (planConfig.storageFreeDays); younger ones are paid for by the participant-minutes that made them, so includedStorageGib is 0 there.
Get Billing Limits
| Method | GET |
| Path | /v1/billing/limits |
| Auth | API key or dashboard login session |
Response:
{ "data": {
"plan": "free",
"subscriptionStatus": "none",
"withinIncludedAllowance": true,
"streamingMinutesUsed": 125.3,
"includedMinutes": 10000,
"storageUsedGib": 0.5,
"includedStorageGib": 25,
"replayMinutesUsed": 40,
"includedReplayMinutes": 1500,
"exportMinutesUsed": 0,
"includedExportMinutes": 300,
"billableExportMinutes": 0,
"maxParticipantsPerCall": 4,
"maxConcurrentParticipants": 8,
"hasActiveSubscription": false,
"isBlocked": false,
"cancelsAt": null,
"statusMessage": "Within Free plan allowance"
}, "error": null }List Invoices
| Method | GET |
| Path | /v1/billing/invoices |
| Auth | API key or dashboard login session |
Up to 12 recent invoices ({ "invoices": [...] }, empty without a billing
relationship), each with amounts, status, period and Stripe's hosted invoice
and PDF links.
Start Checkout (Switch to Pay-as-you-go)
| Method | POST |
| Path | /v1/billing/checkout |
| Auth | Dashboard login session with the owner or admin role. API keys get 403: they can't manage people or billing |
No body is needed. Response: { "url": "https://checkout.stripe.com/..." } to redirect to. Checkout saves a card and charges nothing: pay-as-you-go has no monthly fee, and each monthly invoice bills only usage past the free allowance. 409 if the organisation already has an active subscription.
Create Stripe Billing Portal Session
| Method | POST |
| Path | /v1/billing/portal or /v1/projects/:projectId/billing/portal |
| Auth | Dashboard login session with the owner or admin role. API keys get 403: they can't manage people or billing |
Returns { "url": "https://billing.stripe.com/..." } for managing the
organisation's subscription and payment method. Both paths open the same
organisation-level portal.
API Key Management
List API Keys
| Method | GET |
| Path | /v1/api-keys |
| Auth | API key or dashboard login session |
With an API key, lists its project's keys (or ?project_id= for another
project in the organisation); a dashboard session lists the whole
organisation's. Secrets are never included.
Response:
{ "data": [
{ "id": "...", "project_id": "...", "label": "default", "created_at": "..." }
], "error": null }Create API Key
| Method | POST |
| Path | /v1/projects/:projectId/api-keys, /v1/api-keys (the key's own project, or project_id in the body), or /v1/me/api-keys (dashboard session; the organisation's first project) |
| Auth | API key or dashboard login session (same organisation); the email address must be verified |
Body (optional): { "label": "production" }.
Response: the new key's id, label, project_id, created_at and raw
secret (sk_live_...). The secret is shown only once — store it securely.
Move API Key to Another Project
| Method | PATCH |
| Path | /v1/api-keys/:keyId |
| Auth | API key or dashboard login session |
Body: { "project_id": "..." } (a project in the same organisation).
Delete API Key
| Method | DELETE |
| Path | /v1/api-keys/:keyId |
| Auth | API key or dashboard login session |
Response: { "deleted": true, "id": "..." }. The deleted key is immediately invalidated.
Restricted Keys
| Method | GET, POST, DELETE |
| Path | /v1/restricted-keys, /v1/restricted-keys/:keyId |
| Auth | API key or dashboard login session (a restricted key cannot manage keys) |
POST body: { "project_id": "...", "label": "my-app" } — response (201)
includes the rk_live_... secret, once. GET lists live keys (optionally
?project_id=); DELETE revokes one.
Authentication & User Management (Email/Password)
Register
| Method | POST |
| Path | /v1/auth/register |
| Auth | None (public) |
Request body: {"email": "user@example.com", "password": "at-least-8-chars", "name": "Ada"} (name optional)
Response (201): creates user + organisation + project, sets the session cookie, and emails a verification link. API keys can only be created once the address is verified.
{ "data": {
"emailVerificationRequired": true,
"orgId": "...", "projectId": "...",
"user": { "id": "...", "email": "user@example.com", "name": "Ada" }
}, "error": null }Verify Email, Resend, Reset Password
| Method | GET / POST |
| Path | GET /v1/auth/verify-email?token=, POST /v1/auth/resend-verification, POST /v1/auth/forgot-password, POST /v1/auth/reset-password |
| Auth | None, except resend-verification (dashboard login session) |
verify-email is the link in the verification email; it redirects to the
sign-in page. forgot-password takes { "email": "..." } and always answers
200. reset-password takes { "token": "...", "password": "..." }.
Login
| Method | POST |
| Path | /v1/auth/login |
| Auth | None (public) |
Request body: {"email": "user@example.com", "password": "..."}
Response (200): { "user": { "id", "email", "name" } } and sets the session cookie (synento_session), valid for 7 days.
Logout
| Method | POST |
| Path | /v1/auth/logout |
Response (200): clears session cookie.
Current User
| Method | GET / PATCH |
| Path | /v1/me |
| Auth | Dashboard login session only |
GET response:
{ "data": { "id": "...", "email": "user@example.com", "name": "", "role": "owner",
"emailVerified": true, "orgId": "...", "orgName": "...", "projectId": "...",
"projectName": "...", "hasApiKey": true }, "error": null }PATCH body: { "name": "Ada" }. Change the password with
POST /v1/me/password ({ "current_password", "new_password" }).
Close Account
| Method | DELETE |
| Path | /v1/account |
| Auth | Dashboard login session only |
Body: { "password": "..." }. The last member of an organisation takes it with
them: the subscription is cancelled and every recording erased.
Organisation & Membership
Organisation
| Method | GET / PATCH |
| Path | /v1/organisation |
| Auth | GET: API key or dashboard login session. PATCH: dashboard login session with the owner or admin role only (API keys get 403) |
GET returns { "id", "name" }; PATCH body { "name": "..." } renames it.
Members
| Method | GET, PATCH, DELETE |
| Path | /v1/organisation/members, /v1/organisation/members/:userId |
| Auth | GET: API key or dashboard login session. PATCH, DELETE and revoking an invitation: dashboard login session only (API keys get 403) |
GET returns { "members": [...], "invitations": [...] } (pending
invitations). PATCH (owners only) changes a member's role (owner,
admin, member); DELETE (owners and admins) removes them. An organisation
always keeps at least one owner. Revoke a pending invitation with
DELETE /v1/organisation/invitations/:id.
Send Invitation to Project's Organisation
| Method | POST |
| Path | /v1/projects/:projectId/invitations |
| Auth | Dashboard login session only (owner or admin; only an owner can invite an owner). API keys get 403 |
Request body: {"email": "new@example.com", "role": "member"}
Response (201):
{ "data": { "invitationId": "...", "email": "new@example.com", "role": "member",
"token": "...", "accept_url": "https://synento.com/accept-invite?token=..." }, "error": null }Redeem Invitation Token
| Method | POST |
| Path | /v1/invitations/redeem |
| Auth | Dashboard login session (the user must be logged in) |
Request body: {"token": "invite-token-xyz"}
Moves the signed-in user into the inviting organisation with the invited role. Only the address the invitation was sent to can redeem it.
Public Session Catalog
List Public Sessions
| Method | GET |
| Path | /v1/public/sessions?project_id={projectId} |
| Auth | None (public) |
Returns up to 100 of the project's sessions with is_public = true, newest
first. project_id is required, so one tenant's public sessions are never
listed through another's page.
Response:
{ "data": [
{ "id": "...", "name": "Public Demo", "created_at": "...",
"started_at": "...", "ended_at": "..." }
], "error": null }GET /v1/public/analytics/popular-sessions?project_id= returns the project's
five most recently ended public sessions, with durationMinutes and
participantCount.
Replay Links
Create Expiring Replay Link
| Method | POST |
| Path | /v1/sessions/:sessionId/replay-links |
| Auth | API key (the session's project). A restricted key gets 403. |
Request body: {"ttl_minutes": 60} — optional; an integer from 1 to 43200
(30 days), default 60.
Response:
{ "data": {
"id": "...",
"token": "...",
"expires_at": "...",
"link": "https://api.synento.com/v1/public/sessions/{sessionId}/replay?token={token}"
}, "error": null }link is
/v1/public/sessions/:sessionId/replay with the
token filled in. It gives unauthenticated windowed playback, as JSON, until it
expires; without from_ts it returns the recording's first window. It is data
for your own player, not a hosted replay page.
Revoke Replay Link
| Method | DELETE |
| Path | /v1/sessions/:sessionId/replay-links/:linkId |
| Auth | API key (the session's project) |
linkId is the id returned when the link was created. The link stops
working at once. Response: { "data": { "id": "...", "revoked": true }, "error": null };
404 for an unknown link or another project's session.
Configuration
GET /v1/public/config (no auth) reports whether the server allows
unauthenticated demo connections. Production never does.
Synento documentation
Synento is an agent-native video API. A coding agent can set up a project, write the integration, and prove media arrived by reading the session manifest. Live video, replay, and MP4 export all read the same durable streams.
Browser support
Which browsers can run a Synento session, how the SDK reports it, and what has actually been verified.