Synento docs

API Reference

Complete endpoint documentation for the Synento server API. Base URL: https://api.synento.com

View as Markdown

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_xxxxx or X-API-Key: sk_live_xxxxx (direct API, CLI, and server-side integrations)
  • Dashboard login session — synento_session HTTP-only cookie set by POST /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 by POST /v1/sessions, POST /v1/projects/{projectId}/sessions, POST /v1/sessions/{sessionId}/connection (live and replay) and GET /v1/sessions/{sessionId}/manifest. Every other route refuses it with 403 FORBIDDEN and a message naming the project secret key. This is what an agent writes into your app's environment. Manage them with GET/POST /v1/restricted-keys and DELETE /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_… or rk_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 } }  // Error

Every 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

MethodGET
Path/health
AuthNone (public)

Response: plain text ok.

Get Readiness

MethodGET
Path/ready
AuthNone (public)

Response: { "data": { "ready": true, "checks": { "database": "ok", "s2": "ok" } }, "error": null }, or 503 when a check fails.


Projects

List Projects

MethodGET
Path/v1/projects
AuthAPI 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

MethodPOST
Path/v1/projects
AuthAPI 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

MethodPATCH
Path/v1/projects/:projectId
AuthAPI key or dashboard login session (same organisation)

Request body: { "name": "Renamed", "environment": "staging" } — name is required, environment optional. Response: the updated project.

Delete Project

MethodDELETE
Path/v1/projects/:projectId
AuthAPI 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

MethodGET or PUT
Path/v1/projects/:projectId/retention
AuthAPI 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

MethodGET
Path/v1/projects/:projectId/analytics/session-insights and /v1/projects/:projectId/analytics/participant-metrics
AuthAPI 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

MethodPOST
Path/v1/sessions (the key's own project) or /v1/projects/:projectId/sessions
AuthAPI 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

MethodGET
Path/v1/sessions/:sessionId or /v1/projects/:projectId/sessions/:sessionId
AuthAPI 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

MethodGET
Path/v1/sessions
AuthAPI 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

MethodGET
Path/v1/recordings
AuthAPI 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

MethodDELETE
Path/v1/sessions/:sessionId
AuthAPI 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

MethodPUT
Path/v1/sessions/:sessionId/visibility
AuthAPI key (the session's project)

Request body:

{ "is_public": true }  // or false to make private

Response:

{ "data": { "id": "...", "is_public": true }, "error": null }

Get Connection Token (Session)

MethodPOST
Path/v1/sessions/:sessionId/connection
AuthAPI 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

MethodGET (upgrade)
Path/ws?session={sessionId}&user_id=alice (add &replay=true for a replay token)
AuthConnection 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

MethodGET
Path/v1/sessions/:sessionId/manifest
AuthAPI 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)

MethodGET
Path/v1/sessions/:sessionId/playback/timeline
AuthAPI 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)

MethodGET
Path/v1/sessions/:sessionId/playback?from_ts={ms}&window_size=30000
AuthAPI key or dashboard login session

Query parameters:

  • from_ts — start of the window, epoch milliseconds (start at the timeline's minTs)
  • 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

MethodGET
Path/v1/sessions/:sessionId/timeline
AuthAPI 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)

MethodGET
Path/v1/public/sessions/:sessionId/playback, /v1/public/sessions/:sessionId/playback/timeline, /v1/public/sessions/:sessionId/manifest
AuthNone — public sessions only (is_public = true); others answer 404

Same parameters and response shapes as the authenticated endpoints above.

MethodGET
Path/v1/public/sessions/:sessionId/replay?token={linkToken}&from_ts={ms}&window_size=30000
AuthNone — 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

MethodGET
Path/v1/sessions/:sessionId/export
AuthAPI key or dashboard login session

Query parameters (optional):

ParameterValuesDefault
layoutgrid, presentergrid
orientationlandscape (1280×720), vertical (720×1280)landscape
focusParticipant 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

MethodGET
Path/v1/exports/:jobId
AuthAPI 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

MethodGET
Path/v1/exports/:jobId/download
AuthAPI key or dashboard login session

Response: binary MP4 (video/mp4) when the job is completed; 404 otherwise.

Delete Export

MethodDELETE
Path/v1/exports/:jobId
AuthAPI 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

MethodPOST
Path/v1/sessions/:sessionId/transcript
AuthAPI 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

MethodGET
Path/v1/sessions/:sessionId/transcript
AuthAPI key, restricted key (rk_live_) or dashboard login session

Query parameters (optional):

ParameterValuesDefault
formatjson, vtt, srt, txtjson
langA language the transcript holdsall

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

MethodGET, PUT
Path/v1/projects/:projectId/transcription
AuthAPI 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

MethodDELETE
Path/v1/sessions/:sessionId/participants/:userId
AuthAPI 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

MethodGET
Path/v1/webhooks
AuthAPI 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

MethodPOST
Path/v1/webhooks
AuthAPI 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

MethodPATCH or DELETE
Path/v1/webhooks/:id
AuthAPI 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

MethodPOST
Path/v1/webhooks/:id/rotate-secret
AuthAPI 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

MethodGET
Path/v1/webhooks/:id/deliveries
AuthAPI 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

MethodGET
Path/v1/billing/plans
AuthNone (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

MethodGET
Path/v1/usage
AuthAPI 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

MethodGET
Path/v1/projects/:projectId/usage
AuthAPI 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

MethodGET
Path/v1/billing/summary
AuthAPI 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

MethodGET
Path/v1/billing/limits
AuthAPI 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

MethodGET
Path/v1/billing/invoices
AuthAPI 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)

MethodPOST
Path/v1/billing/checkout
AuthDashboard 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

MethodPOST
Path/v1/billing/portal or /v1/projects/:projectId/billing/portal
AuthDashboard 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

MethodGET
Path/v1/api-keys
AuthAPI 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

MethodPOST
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)
AuthAPI 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

MethodPATCH
Path/v1/api-keys/:keyId
AuthAPI key or dashboard login session

Body: { "project_id": "..." } (a project in the same organisation).

Delete API Key

MethodDELETE
Path/v1/api-keys/:keyId
AuthAPI key or dashboard login session

Response: { "deleted": true, "id": "..." }. The deleted key is immediately invalidated.

Restricted Keys

MethodGET, POST, DELETE
Path/v1/restricted-keys, /v1/restricted-keys/:keyId
AuthAPI 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

MethodPOST
Path/v1/auth/register
AuthNone (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

MethodGET / POST
PathGET /v1/auth/verify-email?token=, POST /v1/auth/resend-verification, POST /v1/auth/forgot-password, POST /v1/auth/reset-password
AuthNone, 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

MethodPOST
Path/v1/auth/login
AuthNone (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

MethodPOST
Path/v1/auth/logout

Response (200): clears session cookie.

Current User

MethodGET / PATCH
Path/v1/me
AuthDashboard 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

MethodDELETE
Path/v1/account
AuthDashboard 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

MethodGET / PATCH
Path/v1/organisation
AuthGET: 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

MethodGET, PATCH, DELETE
Path/v1/organisation/members, /v1/organisation/members/:userId
AuthGET: 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

MethodPOST
Path/v1/projects/:projectId/invitations
AuthDashboard 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

MethodPOST
Path/v1/invitations/redeem
AuthDashboard 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

MethodGET
Path/v1/public/sessions?project_id={projectId}
AuthNone (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.


MethodPOST
Path/v1/sessions/:sessionId/replay-links
AuthAPI 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.

MethodDELETE
Path/v1/sessions/:sessionId/replay-links/:linkId
AuthAPI 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.

On this page

AuthenticationRate limitsResponse FormatIdempotencyPaginationHealthGet Health StatusGet ReadinessProjectsList ProjectsCreate ProjectUpdate ProjectDelete ProjectRecording retentionProject AnalyticsSession ManagementCreate SessionGet SessionList SessionsList RecordingsDelete SessionSet Session VisibilityGet Connection Token (Session)Live Streaming (WebSocket)Connect via WebSocketReplay & PlaybackGet Session ManifestGet Playback Timeline (Metadata)Get Playback Window (Windowed Stream Reading)Get Session TimelinePublic Playback (Unauthenticated)Replay via Expiring LinkExport (MP4)Enqueue Session ExportPoll Export Job StatusDownload Export MP4Delete ExportTranscriptsRequest a TranscriptGet a TranscriptAutomatic TranscriptsParticipant RedactionRedact ParticipantWebhooksList WebhooksCreate WebhookUpdate or Delete a WebhookRotate a Webhook SecretList DeliveriesUsage & BillingGet PlansGet UsageGet Project Usage RecordsGet Billing SummaryGet Billing LimitsList InvoicesStart Checkout (Switch to Pay-as-you-go)Create Stripe Billing Portal SessionAPI Key ManagementList API KeysCreate API KeyMove API Key to Another ProjectDelete API KeyRestricted KeysAuthentication & User Management (Email/Password)RegisterVerify Email, Resend, Reset PasswordLoginLogoutCurrent UserClose AccountOrganisation & MembershipOrganisationMembersSend Invitation to Project's OrganisationRedeem Invitation TokenPublic Session CatalogList Public SessionsReplay LinksCreate Expiring Replay LinkRevoke Replay LinkConfiguration