# Synento

---



---

> Synento is an agent-native video API. Browsers encode with WebCodecs and send binary frames over a WebSocket, and every session is appended to durable streams, so each session is already its own recording. Replay, windowed playback and MP4 export read the same streams that carried the live call.

---



---

Key facts for agents: the fastest path is the remote MCP server at https://api.synento.com/mcp (Streamable HTTP, OAuth 2.1): it provisions, mints a restricted rk_live_ key for the app's .env, and verifies media with verify_session. Without MCP: the API key is a server-side secret (never send it to a browser); browsers join with short-lived connection tokens minted per session and user; POST /v1/sessions accepts an Idempotency-Key header; every response is the envelope { data, error }; verify an integration by reading GET /v1/sessions/{id}/manifest — a track is listed only once media reached it, so check each participant has both cam and mic.

---



---

# Synento Documentation

Source: https://synento.com/docs

> Synento is an agent-native video API — video that agents can set up independently. Add live video, session replay, and on-demand playback to any application with a few API calls.

Synento is an agent-native video API — video that agents can set up independently. Add live video, session replay, and on-demand playback to any application with a few API calls.

## Quick Links

- [Getting Started](https://synento.com/docs/getting-started.md) — Set up your first project and stream in minutes
- [Core Concepts](https://synento.com/docs/concepts.md) — Understand projects, sessions, and the stream-native recording model
- [API Reference](https://synento.com/docs/api-reference.md) — Complete endpoint documentation with request/response examples

## SDK packages

| Package | Use |
|---------|-----|
| [`@synento/client`](https://www.npmjs.com/package/@synento/client) | Browser: publish and receive live audio, video, and screen share |
| [`@synento/react`](https://www.npmjs.com/package/@synento/react) | React provider, hooks, and components over `@synento/client` |
| [`@synento/node`](https://www.npmjs.com/package/@synento/node) | Server: create sessions, mint connection tokens, manage projects |
| [`@synento/player`](https://www.npmjs.com/package/@synento/player) | Embeddable replay engine with layout composition |
| [`@synento/cli`](https://www.npmjs.com/package/@synento/cli) | Command-line project and session management |

## Guides

- [Webhooks](https://synento.com/docs/guides/webhooks.md) — Set up event-driven integrations with webhooks
- [Recordings & Replay](https://synento.com/docs/guides/recordings-replay.md) — How stream-based recording and replay work
- [Access Control](https://synento.com/docs/guides/access-control.md) — Public sessions, expiring links, and visibility
- [Session Management](https://synento.com/docs/guides/sessions.md) — Deep dive into session lifecycle and controls
- [CLI Guide](https://synento.com/docs/guides/cli.md) — Use the Synento CLI for project and session management
- [SDK Guide](https://synento.com/docs/guides/sdk.md) — Integrate using the JavaScript/TypeScript SDK
- [Browser Support](https://synento.com/docs/browser-support.md) — Which browsers work, what the SDK reports, and what has been verified

## Examples

Copy-paste examples ready to run:

- [Web Quickstart](https://synento.com/docs/examples/web-quickstart.md) — Embed a live video stream in any web page
- [SDK Basic Usage](https://synento.com/docs/examples/sdk-basic.md) — Create sessions and manage them with the SDK
- [SDK Advanced Patterns](https://synento.com/docs/examples/sdk-advanced.md) — Replay, exports, and webhooks with the SDK
- [CLI Examples](https://synento.com/docs/examples/cli-examples.md) — Common CLI workflows

## Key Features

| Feature | Description |
|---------|-------------|
| Live Streaming | Multi-participant WebSocket-based video streaming with adaptive scaling |
| Stream-Native Recording | Separated tracks (cam/mic/screen) + typed event timeline — layout-agnostic |
| Composable Replay | Configurable layouts (grid, active-speaker, presenter, screen-share) at playback time |
| Director Track | Deterministic active-speaker switching from persisted layout decisions |
| Replay | Instant replay with speed control, seek, layout switching, and windowed reading |
| MP4 Export | Async export with layout and orientation parameters; local or S3/R2 artifact storage |
| Public Sessions & Links | Share sessions publicly or via expiring token-based replay links |
| Webhooks | Event-driven callbacks for session lifecycle events |
| SDK & CLI | TypeScript SDK and command-line tool for programmatic access |

## API Overview

Synento exposes all functionality through REST APIs. Authentication is via API keys with the `Authorization: Bearer sk_...` header.

All JSON responses follow a standard envelope format:

```json
{ "data": { ... }, "error": null }           // Success
{ "data": null, "error": { "code": "...", "message": "..." } }  // Error
```

Key endpoint categories:

- `POST /v1/projects` — Create projects
- `POST /v1/sessions` — Create live sessions
- `GET/POST /v1/sessions/:id/connection` — Get connection tokens for WebSocket streaming
- `GET /v1/sessions/:id/manifest` — Session reconstruction contract (tracks, bounds, capabilities)
- `GET /v1/sessions/:id/playback` — Windowed replay of recorded sessions
- `GET /v1/sessions/:id/export` — Enqueue MP4 export (layout, orientation)
- `GET /v1/exports/:jobId` — Poll export status and download URL

See the full [API Reference](https://synento.com/docs/api-reference.md) for all 40+ endpoints.


---

# Getting Started

Source: https://synento.com/docs/getting-started

> Get from zero to your first live video stream in under 5 minutes.

Get from zero to your first live video stream in under 5 minutes.

> **Using a coding agent?** Connect it to Synento over MCP and it can do all of
> this for you — including proving the video works. See
> [Connect your agent](https://synento.com/docs/guides/mcp.md).

## Prerequisites

- A Synento account ([sign up free](https://synento.com/signup): 3,000 participant-minutes a month, no card)
- A server-side key — an `sk_live_` API key from the dashboard or CLI, or an
  `rk_live_` restricted key (one project; enough for everything on this page)

## Option A: Use the SDK (Recommended)

### 1. Install the packages

```bash
npm install @synento/node      # server-side: create sessions, mint tokens
npm install @synento/client    # browser: publish and receive live audio/video
```

React applications can use [`@synento/react`](https://www.npmjs.com/package/@synento/react) for hooks and
components, and [`@synento/player`](https://www.npmjs.com/package/@synento/player) for embedded
replay.

### 2. Mint connection tokens on your server

Your API key is a **server-side secret**. It never goes to the browser. Instead,
your backend exposes one small route that creates a session and mints a
short-lived connection token for the user asking to join.

```typescript
// app/api/synento/route.ts  (Next.js App Router)
import { createSynentoClient, resolveWsUrl } from "@synento/node";

// Reads SYNENTO_API_KEY and SYNENTO_API_URL from the environment.
const synento = createSynentoClient();

export const dynamic = "force-dynamic"; // or the route is cached and serves a stale token

export async function POST(request: Request) {
  const { sessionId, userId } = await request.json();

  const token = await synento.createConnectionToken(sessionId, { userId });

  return Response.json({
    token: token.accessToken,
    wsUrl: resolveWsUrl({
      apiBaseUrl: process.env.SYNENTO_API_URL ?? "https://api.synento.com",
      requestOrigin: request.headers.get("origin"),
      sessionId,
      userId,
    }),
  });
}
```

Use `resolveWsUrl` rather than assembling the URL yourself — it handles the
loopback-hostname case that otherwise makes local development fail in a way
that produces no error at all, just a call that never connects.

### 3. Join from the browser

```typescript
import { SynentoRoom } from "@synento/client";

const room = new SynentoRoom({
  userId: "alice",
  // Re-invoked on every reconnect, so tokens rotate automatically.
  getToken: async () => {
    const res = await fetch("/api/synento", {
      body: JSON.stringify({ sessionId, userId: "alice" }),
      method: "POST",
    });
    return res.json(); // { wsUrl, token }
  },
});

room.on("participantsChanged", (ids) => console.log("in the room:", ids));
await room.connect();

// Publish. The second argument is optional — pass your local preview element
// if you have one. A stream with no video tracks publishes audio only.
const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
await room.publishCamera(stream, previewVideoEl);
```

Media travels as **binary frames**, not JSON — `@synento/client` handles the
framing, decoding and reconnection. Do not open a raw `WebSocket` and try to
`JSON.parse` messages off it.

**Recording needs no code.** The session's durable streams *are* the recording,
so there is no start-recording call and no recording flag.

### 4. See it running

[demo.synento.com](https://demo.synento.com) is a two-way call built on exactly
these packages. Open it in two tabs, join the same session, then leave and
replay it: the recording exists the moment the call does.

## Option B: Use HTTP API Directly (cURL)

### 1. Create a project

```bash
curl -X POST https://api.synento.com/v1/projects \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project"}'
```

### 2. Create a session

```bash
curl -X POST https://api.synento.com/v1/projects/{projectId}/sessions \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Demo Session"}'
```

### 3. Get a connection token

```bash
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-1"}'
```

### 4. Connect to WebSocket streaming

Once you have the `access_token` from step 3, open a WebSocket. Prefer sending
the token as a **subprotocol**, so it stays out of URLs and access logs:

```
wss://api.synento.com/ws?session={sessionId}&user_id=viewer-1
Sec-WebSocket-Protocol: synento.v1, synento.token.{accessToken}
```

The query-string form (`&access_token=...`) is still accepted, but logs the
token.

What travels over that socket is **binary**, in a self-describing frame format
— not JSON. Unless you are implementing a client from scratch, use
[`@synento/client`](https://www.npmjs.com/package/@synento/client), which handles framing, codec
negotiation, decoding, backpressure and reconnection.

## Option C: Use the CLI

```bash
# Login with your API key
npx synento login sk_live_xxxxx

# Create a project (interactive or with name argument)
npx synento create-project "My Project"

# Create a session (requires project ID)
npx synento create-session "Demo Session" -p {projectId}
```

## Option D: Let your coding agent do it

Connect your agent to Synento's MCP server and ask it to add video to your app:

```bash
claude mcp add --transport http synento https://api.synento.com/mcp
```

It mints a restricted key for your `.env`, writes the server route and the
browser code above, and then checks the recording with `verify_session` to
confirm camera and microphone actually arrived. See
[Connect your agent](https://synento.com/docs/guides/mcp.md) for other clients and what you approve.

## Next Steps

- Read [Core Concepts](https://synento.com/docs/concepts.md) to understand the architecture
- Browse the full [API Reference](https://synento.com/docs/api-reference.md)
- Try the copy-paste examples in [examples/](https://synento.com/docs/examples/web-quickstart.md)
- Set up webhooks for event-driven workflows — [Webhooks Guide](https://synento.com/docs/guides/webhooks.md)

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SYNENTO_API_KEY` | Secret key. **Server-side only** — never expose it to a browser. | — |
| `SYNENTO_API_URL` | Base URL of the Synento API. | `https://api.synento.com` |

Both are read automatically by `createSynentoClient()` when you pass no
arguments.

## Troubleshooting

### "Connection refused" on WebSocket
- If you set `SYNENTO_API_URL`, check it is `https://api.synento.com`
- Check that the connection token has not expired

### "401 Unauthorized" on API calls
- Verify your API key starts with `sk_`
- Check that the Authorization header uses `Bearer <key>` (no space before the key)

### Sessions not appearing in replay
- Ensure the session has ended (replay reads completed sessions)
- Check that events were actually sent during the stream


---

# Web Quickstart — Live Video in a Web Page

Source: https://synento.com/docs/examples/web-quickstart

> Join a live Synento session from the browser with two-way audio and video, using a short-lived connection token minted by your server.

Join a live Synento session from the browser with two-way audio and video. It
takes two pieces: a small server route that mints a short-lived connection
token, and a page that uses `@synento/client` to publish and receive media.

## Never put your API key in the browser

Your `sk_live_…` key can create sessions, read recordings, and change billing.
It must stay on your server. The browser only ever receives a **connection
token**: a short-lived credential scoped to one session and one user.

```
browser  ──POST /api/connection──▶  your server  ──sk_live_…──▶  Synento API
   ◀── { wsUrl, token } ──────────────────────────────────────────┘
```

## 1. Install

```bash
npm install @synento/client     # browser
npm install @synento/node       # your server
```

## 2. Mint a token on your server

This example is a Next.js route handler; any server framework works the same
way. Create the session once (or look up an existing one), then mint a token
for the user who is joining.

```ts
// app/api/connection/route.ts
import { createSynentoClient, resolveWsUrl } from '@synento/node'

// Reads SYNENTO_API_KEY and SYNENTO_API_URL from the environment.
const synento = createSynentoClient()

// Without this, Next may statically optimise the route and serve a stale token.
export const dynamic = 'force-dynamic'

export async function POST(request: Request) {
  const { sessionId, userId } = await request.json()

  // Authenticate the caller here — whoever gets a token can join this session.
  const token = await synento.createConnectionToken(sessionId, { userId })

  return Response.json({
    expiresIn: token.expiresIn,
    token: token.accessToken,
    // Let the SDK build this. Assembling the URL by hand works in production
    // and then fails on localhost, because the browser and the API commonly
    // disagree about how to spell loopback — and the rejection arrives as a
    // close(1008) *after* a successful upgrade, so it surfaces as a call that
    // silently never connects rather than as an error.
    wsUrl: resolveWsUrl({
      apiBaseUrl: process.env.SYNENTO_API_URL ?? 'https://api.synento.com',
      requestOrigin: request.headers.get('origin'),
      sessionId,
      userId,
    }),
  })
}
```

## 3. Join from the browser

`SynentoRoom` handles encoding, transport, decoding, backpressure, and
reconnection. Note that `getToken` is a *function*: the SDK calls it again on
every reconnect, so tokens rotate without any work from you.

```ts
import { SynentoRoom } from '@synento/client'

const support = SynentoRoom.checkSupport()
if (!support.supported) {
  throw new Error(support.reason) // e.g. this browser lacks WebCodecs
}

const userId = 'alice'
const sessionId = 'YOUR_SESSION_ID'

const room = new SynentoRoom({
  userId,
  getToken: async () => {
    const res = await fetch('/api/connection', {
      body: JSON.stringify({ sessionId, userId }),
      headers: { 'Content-Type': 'application/json' },
      method: 'POST',
    })
    if (!res.ok) throw new Error('could not mint a connection token')
    return res.json() // { wsUrl, token }
  },
})

// Render each remote participant into a canvas you provide.
room.on('participantsChanged', (participants) => {
  for (const id of participants) {
    if (document.querySelector(`canvas[data-user="${id}"]`)) continue
    const canvas = document.createElement('canvas')
    canvas.width = 640
    canvas.height = 480
    canvas.dataset.user = id
    document.body.append(canvas)
    room.attachParticipant(id, canvas)
  }
})

await room.connect()

// Publish camera and microphone. The <video> element is your local preview.
const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true })
const preview = document.querySelector('#preview')
preview.srcObject = stream
await room.publishCamera(stream, preview)
```

Open the page in two browser tabs with **different** user ids and you will see
and hear both participants.

## Other things you can do

```ts
room.setCameraEnabled(false)     // mute video, keep audio flowing
await room.publishScreen()       // share the screen (prompts the user)
room.unpublishScreen()
room.sendChat('hello everyone')  // chat is persisted with the recording
room.on('chat', (senderId, message) => console.log(senderId, message.message))
room.close()                     // leave and release devices
```

The `chat` event fires on the sender too — the server broadcasts the stored
record to everyone in the session, so `senderId` is your own user id for your
own messages. Render from the event alone; appending the text locally when you
call `sendChat` shows your messages twice.

Connection state is observable, which is what you want for a status indicator:

```ts
room.on('connected', () => setStatus('Connected'))
room.on('reconnecting', (attempt) => setStatus(`Reconnecting (${attempt})…`))
room.on('disconnected', (reason) => setStatus(`Disconnected: ${reason}`))
room.on('error', (err) => console.error(err))
```

## Using React

`@synento/react` wraps the same client:

```tsx
import { SynentoProvider, VideoTile, useParticipants } from '@synento/react'

function Call() {
  const participants = useParticipants()
  return participants.map((id) => <VideoTile key={id} participantId={id} />)
}

export default function App() {
  return (
    <SynentoProvider getToken={getToken} userId="alice">
      <Call />
    </SynentoProvider>
  )
}
```

## Browser support

Synento encodes with WebCodecs, so it needs Chrome/Edge 94+, Safari 16.4+, or
Firefox 133+. `SynentoRoom.checkSupport()` tells you before you try, so you can
show a clear message rather than failing at connect time.

## When the session ends

Nothing else to do — the session's durable streams *are* the recording. It is
immediately replayable and exportable to MP4, with no encoding step. See
[Recordings & Replay](https://synento.com/docs/guides/recordings-replay.md).


---

# Core Concepts

Source: https://synento.com/docs/concepts

> Understanding the building blocks of Synento.

Understanding the building blocks of Synento.

## Architecture Overview

Synento follows an **API-first**, agent-native architecture: every feature is exposed through REST endpoints, the dashboard is simply a client of those same APIs, and nothing requires a human in that dashboard to set up — a coding agent can create a project, publish media, and read it back through the same calls.

```
┌──────────────┐    REST     ┌─────────────┐   WebSocket    ┌──────────────┐
│  CLI / SDK   │ ◄────────► │  Synento    │ ◄─────────────►│  WebSocket   │
│  Dashboard   │            │  Server     │                │    Hub       │
│  External    │            │  (Fastify)  │                │   (Hub.ts)   │
│  Integrations│            └─────────────┘                └──────────────┘
└──────────────┘                                                      │
                                                                    Recording
                                                                     (StreamStore)
```

## Hierarchy: Organisation → Project → Session

### Organisation

The top-level container representing a team, company, or account. All projects belong to an organisation.

- Created automatically when you register via the dashboard
- Billing applies at the organisation level (free tier: 3,000 participant-minutes and 50 GiB, no card required)

### Project

A scoped workspace under an organisation. Each project has:
- **Environment** (e.g., `development`, `staging`, `production`) — optional, for your own organization
- **API Key** (secret key: `sk_live_xxxxx`) — used to authenticate all API requests for this project

Projects are the unit of billing. Usage is tracked per project and aggregated to the organisation level for billing purposes.

### Session

The core unit of live streaming and recording. Each session:
- Has a unique ID (UUID format)
- Can have multiple participants connected simultaneously via WebSocket
- Is automatically **recorded** as it happens — no separate recording setup needed (stream-native)
- Is instantly **replayable** once it ends, using windowed playback API

```typescript
type Session = {
  id: string;            // Unique session ID (UUID)
  projectId: string;     // Parent project
  name: string;          // Display name (optional)
  createdBy: string;     // Creator identifier
  isPublic?: boolean;    // Whether anyone can access this session's replay
  startedAt: string | null; // When first participant joined
  endedAt: string | null;   // When last participant left
  createdAt: string;     // Creation timestamp
};
```

## The Stream-Native Recording Model

This is what makes Synento fundamentally different from traditional video platforms.

### Key Principle: Recording = Persisted Stream

There is **no separate recording pipeline**. When participants stream via WebSocket, every message is immediately persisted to the StreamStore (a multi-stream append log). This same stored data powers both:

1. **Replay** — iterating the stream in chronological (or variable-speed) order
2. **Export** — reading the full stream and encoding it to MP4

### Stream Types

Synento persists a **layout-agnostic** recording: separated media tracks plus a typed event timeline. Presentation (grid, active-speaker, etc.) is resolved at playback time.

| Stream | Purpose | Example |
|--------|---------|---------|
| `media/{userId}/cam` | Camera video per participant | WebCodecs `EVC1` or MJPEG bytes |
| `media/{userId}/mic` | Microphone audio per participant | Raw s16le audio |
| `media/{userId}/screen` | Screen share per participant | Same video formats as cam |
| `events` | Structured session timeline | `{ "v": 1, "type": "speaking.started", "actor": "alice", … }` |
| `director` | Computed layout decisions | `{ "type": "director.cut", "data": { "focus": "bob" } }` |
| `chat` | Text messages | `{ "text": "Hello!", "userId": "u1" }` |
| `captions/{lang}` | Caption cues (optional) | `{ "type": "caption.cue", "data": { "text": "…", "end": … } }` |
| `meta` | Legacy join/leave/control | JSON (superseded by `events` for new integrations) |

### Composition Layer

The recording stores **what happened**; playback decides **how to show it**:

```
Tracks + events  →  Session state  →  Layout descriptor  →  Composed view
                         ↑                    ↑
                   director track      grid / active-speaker / presenter / …
```

- **Client**: `@synento/player` `Compositor` + `LayoutEngine` decode visible tracks and draw regions.
- **Server**: FFmpeg export uses the same layout vocabulary (`grid`, `presenter`, orientation).
- **Manifest**: `GET /v1/sessions/:id/manifest` indexes tracks, bounds, and capabilities for fast bootstrap.

### What This Means for Developers

- **No encoding delay** — replay is available immediately after a session ends
- **Instant layout switching** — change grid ↔ active-speaker without re-fetching
- **Selective track fetch** — manifest-driven bandwidth savings (fetch only visible tracks)
- **Windowed reading** — large sessions don't need to be loaded entirely
- **Variable speed replay** — replay at 0.5x, 2x, or any speed using time-based buffering

## Access Control Model

Sessions support three levels of access:

| Level | Who Can Access | How |
|-------|----------------|-----|
| **Private** (default) | Only holders of a valid connection token | API key + session ID |
| **Public** | Anyone with the session URL | No auth required |
| **Link-only** | Only holders of an expiring replay link | Token in URL (TTL 1 min – 30 days) |

See [Access Control Guide](https://synento.com/docs/guides/access-control.md) for detailed API usage.

## Connection Tokens & WebSocket Authentication

Every participant needs a **connection token** to join or replay a session:

1. Request via `POST /v1/sessions/{id}/connection` with API key auth
2. Receive an `access_token` (JWT) that expires in a configurable time window
3. Connect to WebSocket: `ws://host/ws?session={sessionId}&access_token={token}&user_id=alice`

Tokens include claims for:
- `user_id` — participant identifier
- `session_id` — the session to join
- Mode-specific parameters: `replay`, `from_ts`, `speed` for replay mode

## Usage Tracking & Billing

Usage is tracked per project and aggregated at the organisation level:

- **Streaming minutes**: calculated from `started_at` to `ended_at` per session
- **Storage bytes**: size of exported MP4 files

Billing tiers — the authoritative source is `GET /v1/billing/plans`:

| Tier | Participant-minutes | Storage | Retention | Cost |
|------|--------------------|---------|-----------|------|
| Free | 3,000 included | 50 GiB | up to 30 days | $0, no card |
| Pro | 4,000 included | 50 GiB | up to 90 days | $19/mo, then $0.004/participant-minute and $0.06/GiB-month |

Two things worth being precise about, because both have caused real errors:

- Usage is metered in **participant-minutes**, not room-minutes: a four-person
  call for ten minutes is 40, not 10.
- Storage is **GiB** (2³⁰ bytes), the unit S2 bills in, and the API fields say
  so (`includedStorageGib`, `storageUsedGib`). Only `storageBytesUsed` is bytes.
  Scaling a GiB figure by 1e9 renders a 50 GiB allowance as "46.57 GB".

## Replay API & Windowed Playback

The replay system uses **window-based iteration** to handle sessions of any size:

1. `GET /v1/sessions/:id/manifest` — reconstruction contract (participants, tracks, bounds, capabilities)
2. `GET /v1/sessions/:id/playback/timeline` — compact metadata (participants, duration, stream ids)
3. `GET /v1/sessions/:id/playback?from_ts=0&window_size=30000` — read 30-second windows of all tracks + events
4. Repeat until `next_base_seq` is null

Each window returns events from separated media tracks, the events timeline, director track, and chat. The Player SDK composes them into configurable layouts (grid, active-speaker, presenter, screen-share).

See [Recordings & Replay Guide](https://synento.com/docs/guides/recordings-replay.md) for layout descriptors, export parameters, and participant redaction.


---

# API Reference

Source: https://synento.com/docs/api-reference

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

Complete endpoint documentation for the Synento server API.

Base URL: `https://api.synento.com` in production, `http://localhost:8080` when
running the server locally.

## Authentication

Most authenticated endpoints accept either:

- **API key** — `Authorization: Bearer sk_live_xxxxx` or `X-API-Key: sk_live_xxxxx` (required for 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 a project, but acts for its whole organisation on the
management routes (projects, keys, webhooks, members). 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. 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](https://synento.com/docs/guides/mcp.md). 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`.

## Response Format

All JSON responses use a standard envelope:

```json
{ "data": { ... }, "error": null }           // Success
{ "data": null, "error": { "code": "...", "message": "..." } }  // Error
```

Error codes: `BAD_REQUEST` (400), `NOT_FOUND` (404), `UNAUTHORIZED` (401), `FORBIDDEN` (403), `CONFLICT` (409), `SERVER_ERROR` (500).

---

## Health

### Get Health Status
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/health` |
| **Auth** | None (public) |

Response: plain text `ok` or error message.

---

## Projects

### List Projects
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/projects` |
| **Auth** | API key (scoped to organisation) |

Response:
```json
{ "data": [
  { "id": "...", "name": "My App", "org_id": "...", "environment": null, "created_at": "..." }
], "error": null }
```

### Create Project
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/projects` |
| **Auth** | API key (scoped to organisation) |

Request body:
```json
{ "name": "My App", "environment": "production" }
```

Response (201):
```json
{ "data": { "id": "...", "name": "My App", "org_id": "...", "environment": "production" }, "error": null }
```

---

## Session Management

### Create Session
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/projects/:projectId/sessions` |
| **Auth** | API key (scoped to project) |

Request body:
```json
{ "name": "Morning Standup" }
```

Response (201):
```json
{ "data": {
  "id": "...", "project_id": "...", "name": "Morning Standup",
  "created_by": "api-key-user",
  "started_at": null, "ended_at": null, "created_at": "..."
}, "error": null }
```

**Billing:** New session creation is blocked if free tier limits are exceeded and no active Stripe subscription.

### Get Session
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/projects/:projectId/sessions/:sessionId` |
| **Auth** | API key (scoped to project) |

Response: single `Session` object in envelope. 404 if not found or wrong project.

### List Sessions
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/sessions` |
| **Auth** | API key (scoped to project) |

Returns all sessions for the authenticated project, sorted by `created_at` DESC. No projectId in the path.

Response:
```json
{ "data": [
  { "id": "...", "project_id": "...", "name": "Session 1", ... },
  { "id": "...", "project_id": "...", "name": "Session 2", ... }
], "error": null }
```

### Set Session Visibility
| | |
|-|-|
| **Method** | `PUT` |
| **Path** | `/v1/sessions/:sessionId/visibility` |
| **Auth** | API key (scoped to project) |

Request body:
```json
{ "is_public": true }  // or false to make private
```

Response:
```json
{ "data": true, "error": null }  // updated visibility state
```

### Get Connection Token (Session)
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/sessions/:sessionId/connection` |
| **Auth** | API key (scoped to project) |

Request body:
```json
{ "user_id": "alice",
  "replay": false,      // omit or false for live; true for replay mode
  "from_ts": 0,         // optional: start replay from this timestamp (ms)
  "speed": 1.0,         // optional: replay speed multiplier
  "focus": ""           // optional: focus on specific stream
}
```

Response (200):
```json
{ "data": {
  "access_token": "...",      // JWT token, short-lived (5 min)
  "expires_in": 300,          // seconds until expiry
  "session": "...",           // session ID
}, "error": null }
```

---

## Live Streaming (WebSocket)

### Connect via WebSocket
| | |
|-|-|
| **Method** | `GET` (upgrade) |
| **Path** | `/ws?session={sessionId}&access_token={token}&user_id=alice` |
| **Auth** | Connection token (JWT) from `/connection` endpoint |

Connects to the live stream. Messages received are JSON events:
```json
{ "type": "message", "stream_type": "media/alice", "timestamp_ms": 1234567, "body": "<base64-jpeg>" }
{ "type": "message", "stream_type": "chat", "timestamp_ms": 1234568, "body": "<base64-json>" }
{ "type": "control", ... }  // join/leave/control signals as meta events
```

---

## Session Events

### Create Session
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/sessions` |
| **Auth** | API key (project-scoped) |

Creates a session for the authenticated project. Same response shape as creating a project-scoped session.

### Get Session Timeline
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/sessions/:sessionId/timeline` |
| **Auth** | API key (project-scoped) or dashboard login session (`synento_session` cookie) |

Returns all events in a session's timeline. For large sessions, prefer the windowed playback API below.

---

## Replay & Playback

### Get Playback Timeline (Metadata)
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/sessions/:sessionId/playback/timeline` |
| **Auth** | API key (project-scoped) or public session access |

Returns compact timeline metadata without loading full event data:
```json
{ "data": {
  "participant_count": 3,
  "stream_ids": ["events", "director", "chat", "media/alice/cam", "media/alice/mic", "media/bob/cam"],
  "total_events_estimated": 15420,
  "min_ts": 1699876000000,
  "max_ts": 1699876300000
}, "error": null }
```

### Get Session Manifest
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/sessions/:sessionId/manifest` |
| **Auth** | API key (project-scoped) or public session access |

Returns the layout-agnostic reconstruction contract: participants, separated track index (cam/mic/screen), time bounds, stream paths, and capabilities (`separated-tracks`, `event-timeline`, `director-track`, `configurable-layouts`, `captions` when present).

```json
{ "data": {
  "version": 1,
  "session_id": "sess-abc123",
  "epoch": 1699876000000,
  "start_ts": 1699876000000,
  "end_ts": 1699876300000,
  "participants": [
    { "user_id": "alice", "tracks": [
      { "kind": "cam", "stream_id": "a/.../media/alice/cam", "start_ts": 1000, "end_ts": 5000 }
    ]}
  ],
  "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 Window (Windowed Stream Reading)
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/sessions/:sessionId/playback?from_ts={ms}&window_size=30000` |
| **Auth** | API key (project-scoped) or public session access |

Query parameters:
- `from_ts` — milliseconds to start reading from (required)
- `window_size` — size of window in ms (optional, defaults 30s)

Response:
```json
{ "data": {
  "events": [
    { "seq": 100, "timestamp_ms": 1699876030000, "stream_id": "a/.../media/alice/cam",
      "body_base64": "<base64-payload>" }
  ],
  "base_seq": 100,
  "next_base_seq": null
}, "error": null }
```

Playback windows include events from all separated media tracks, the `events` timeline, `director` track, and `chat`. Media payloads are raw track bytes (WebCodecs `EVC1` or MJPEG); timeline events are JSON in the envelope `{ v, type, ts, actor, data }`.

### Get Public Playback (Unauthenticated)
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/public/sessions/:sessionId/playback?from_ts={ms}&window_size=30000` |
| **Auth** | None — only works for public sessions (`is_public = true`) |

Same response shape as authenticated playback, but only accessible for public sessions.

### Get Public Playback Timeline (Unauthenticated)
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/public/sessions/:sessionId/playback/timeline` |
| **Auth** | None — public sessions only |

Same response as authenticated timeline, for public sessions.

### Replay via Expiring Link
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/public/sessions/:sessionId/replay?token={linkToken}&from_ts=0&window_size=30000` |
| **Auth** | None — replay token required (or public session) |

Reads a playback window using an expiring replay link token. Same response shape as public playback.

---

## Export (MP4)

Export is **asynchronous**. Enqueue a job, poll status, then download the completed MP4.

Send a project API key on every step below.

### Enqueue Session Export
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/sessions/:sessionId/export` |
| **Auth** | API key (project-scoped) or dashboard login session (`synento_session` cookie) |

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):
```json
{ "data": { "job_id": "550e8400-e29b-41d4-a716-446655440000" }, "error": null }
```

Returns 503 with `USAGE_LIMITS_EXCEEDED` when free tier limits are exceeded.

### Poll Export Job Status
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/exports/:jobId` |
| **Auth** | API key (project-scoped) or dashboard login session (`synento_session` cookie) |

Response:
```json
{ "data": {
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "room_id": "sess-abc123",
  "download_url": "/v1/exports/550e8400-e29b-41d4-a716-446655440000/download"
}, "error": null }
```

Status values: `queued`, `processing`, `completed`, `failed`.

### Download Export MP4
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/exports/:jobId/download` |
| **Auth** | API key (project-scoped) or dashboard login session (`synento_session` cookie) |

Response: binary MP4 data when the job is `completed`.

---

## Participant Redaction

### Redact Participant
| | |
|-|-|
| **Method** | `DELETE` |
| **Path** | `/v1/sessions/:sessionId/participants/:userId` |
| **Auth** | API key (project-scoped) |

Deletes all media track streams for the participant (`cam`, `mic`, `screen`) and appends a `participant.redacted` event to the timeline. The rest of the session remains intact.

Response:
```json
{ "data": { "redacted": "alice", "deletedStreams": 3 }, "error": null }
```

---

## Webhooks

### List Webhooks
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/webhooks` |
| **Auth** | API key (project-scoped) |

Response: array of active webhooks for the project.
```json
{ "data": [
  { "id": "...", "project_id": "...", "url": "https://example.com/hook",
    "events": ["session.created", "session.ended"], "is_active": true }
], "error": null }
```

### Create Webhook
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/webhooks` |
| **Auth** | API key (project-scoped) |

Request body:
```json
{ "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`

Response (201):
```json
{ "data": { "id": "...", "project_id": "...", "url": "...",
  "events": ["session.created"], "is_active": true }, "error": null }
```

---

## Usage & Billing

### Get Usage Records
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/projects/:projectId/usage` (project-scoped) or `/v1/usage` |
| **Auth** | API key (project-scoped) or dashboard login session (`synento_session` cookie) |

Response:
```json
{ "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 }
```

### Get Billing Summary
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/billing/summary` |
| **Auth** | API key (project-scoped) — no projectId in path required |

Response:
```json
{ "data": {
  "streaming_minutes_used": 125.3,
  "storage_bytes_used": 524288000,
  "cost_breakdown": {
    "streaming_cost": 12.53,
    "storage_cost": 0.03,
    "total_due": 12.56
  }
}, "error": null }
```

### Get Billing Limits
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/billing/limits` |
| **Auth** | API key (project-scoped) or dashboard login session (`synento_session` cookie) |

Response:
```json
{ "data": {
  "within_free_tier": true,
  "streaming_minutes_used": 125.3,
  "storage_bytes_used_gb": 0.5,
  "has_active_subscription": false,
  "is_blocked": false,
  "status_message": ""
}, "error": null }
```

### Create Stripe Billing Portal Session (Project-scoped)
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/projects/:projectId/billing/portal` |
| **Auth** | API key (project-scoped) or dashboard login session (`synento_session` cookie) |

Returns a Stripe billing portal URL. Response includes `portal_url` for redirecting the user to manage their subscription.

### Create Stripe Billing Portal Session (Org-scoped)
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/billing/portal` |
| **Auth** | API key (project-scoped) — no projectId needed |

Same as above but uses organisation-level Stripe customer. Recommended for dashboards (no projectId required).

---

## API Key Management

### List API Keys
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/api-keys` |
| **Auth** | API key (project-scoped) — no projectId needed in path |

Returns metadata for keys belonging to the authenticated project. Secrets are not included (only ID and creation date).

Response:
```json
{ "data": [
  { "id": "...", "project_id": "...", "created_at": "..." }
], "error": null }
```

### Create API Key
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/projects/:projectId/api-keys` |
| **Auth** | API key (project-scoped) |

Response (201): returns the new key's ID and raw secret (`sk_live_...`). The secret is shown only once — store it securely.

### Delete API Key
| | |
|-|-|
| **Method** | `DELETE` |
| **Path** | `/v1/api-keys/:keyId` |
| **Auth** | API key (project-scoped) — no projectId needed in path |

Response: success confirmation. The deleted key is immediately invalidated.

---

## Authentication & User Management (Email/Password)

### Register
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/auth/register` |
| **Auth** | None (public) |

Request body: `{"email": "user@example.com", "password": "secret123"}`

Response (201): creates user + organisation + project, sets session cookie.
```json
{ "data": { "id": "...", "email": "user@example.com", ... }, "error": null }
```

### Login
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/auth/login` |

Request body: `{"email": "user@example.com", "password": "secret123"}`

Response (200): sets session cookie (`synento_session`). Session expires in 7 days.

### Logout
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/auth/logout` |

Response (200): clears session cookie.

### Get Current User
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/me` |

Response (200): returns current authenticated user data.
```json
{ "data": { "id": "...", "email": "user@example.com" }, "error": null }
```

---

## Organisation Membership (Invitations)

### Send Invitation to Project's Organisation
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/projects/:projectId/invitations` |
| **Auth** | API key (project-scoped) |

Request body: `{"email": "new@example.com", "role": "member"}`

Response (201):
```json
{ "data": { "id": "...", "org_id": "...", "email": "new@example.com",
  "role": "member", "created_by": "...", "accepted_at": null }, "error": null }
```

### Redeem Invitation Token
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/invitations/redeem` |

Request body: `{"token": "invite-token-xyz"}`

Auth: session cookie (user must be logged in). Updates the user's `org_id` and role.

Response (200): success confirmation with updated org membership.

---

## Public Session Catalog

### List Public Sessions
| | |
|-|-|
| **Method** | `GET` |
| **Path** | `/v1/public/sessions` |
| **Auth** | None (public) |

Returns all sessions with `is_public = true`, sorted by creation date DESC. No project IDs exposed for privacy.

Response:
```json
{ "data": [
  { "id": "...", "name": "Public Demo", "created_at": "...",
    "started_at": "...", "ended_at": "..." }
], "error": null }
```

---

## Replay Links

### Create Expiring Replay Link
| | |
|-|-|
| **Method** | `POST` |
| **Path** | `/v1/sessions/:sessionId/replay-links` |
| **Auth** | API key (project-scoped) |

Request body: `{"expires_in_minutes": 60}` (optional, defaults to a reasonable TTL)

Response (201):
```json
{ "data": {
  "link": "https://host/v1/public/sessions/{sessionId}/replay?token={token}",
  "token": "...",
  "expires_at": "..."
}, "error": null }
```

The replay link provides unauthenticated windowed playback access until it expires (max 30 days = 43200 minutes).


---

# Browser support

Source: https://synento.com/docs/browser-support

> Which browsers can run a Synento session, how the SDK reports it, and what has actually been verified.

# Browser support

Synento encodes in the browser with **WebCodecs** and ships frames over a
WebSocket. There is no WebRTC fallback — that is a deliberate architectural
choice, not a gap: every frame is written to a durable stream, which is what
makes each session its own recording — so a browser either has the APIs or
it cannot publish. The SDK checks before connecting and tells you which piece is
missing.

## Requirements

A browser needs all four:

| Capability | Used for |
|---|---|
| `WebSocket` | Transport for media, chat and control |
| `VideoEncoder` / `VideoDecoder` / `VideoFrame` (WebCodecs) | Encoding your camera, decoding everyone else's |
| `navigator.mediaDevices` | Camera and microphone capture (requires a secure context) |
| `AudioWorkletNode` | Microphone capture at 16 kHz mono |
| `AudioEncoder` / `AudioDecoder` (Opus) | **Optional.** Compresses audio ~8x. Without it the call falls back to uncompressed PCM and works exactly the same, so this does not affect whether a browser is supported — `checkSupport()` reports it as `webCodecsAudio` for visibility only. |

`navigator.mediaDevices` only exists on **HTTPS or `localhost`**. On a plain
HTTP origin — including a LAN IP such as `http://192.168.1.10:3000` — capture is
unavailable no matter which browser you use.

## Matrix

| Browser | Publish + subscribe | Notes |
|---|---|---|
| Chrome / Edge 94+ | Yes | The reference target. H.264, VP9 and VP8 all negotiate. |
| Safari 16.4+ (macOS) | Yes | WebCodecs shipped in 16.4. Verified manually, not in CI. |
| Safari 16.4+ (iOS / iPadOS) | Publish + subscribe, with caveats | See [iOS](#ios) below. |
| Firefox 133+ | Yes | WebCodecs enabled by default from 133. |
| Firefox < 133 | No | `VideoEncoder` is absent; the SDK reports it and refuses to connect. |
| Any browser over plain HTTP | No | No `mediaDevices` outside a secure context. |

## What has actually been verified

Being precise about this matters more than the table looking green.

- **Chromium — automated, every CI run.** A two-party call with synthetic camera
  and microphone hardware: both sides decode the other's video, chat is
  delivered, and both participants' camera and microphone tracks are checked for
  recorded data in S2. See `e2e/tests/live-call.spec.ts`.
- **Playwright WebKit — automated, non-media flows only.** It runs sign-in, the
  dashboard, recording and export. **A WebKit pass is not a Safari pass.**
  Playwright's WebKit is a build of the engine, not the shipping browser: its
  WebCodecs support and media handling differ from Safari's, and it has no
  equivalent of Chromium's fake-device switch. Treating it as Safari coverage
  would be exactly the false assurance the suite exists to prevent.
- **Safari on macOS and iOS — manual.** Run the checklist below before a release.
  The result belongs in this table, not in a test report.

### Manual Safari pass

Against a deployed environment over HTTPS (not `localhost`, so the iOS device can
reach it):

1. Open the demo in Safari, join a session, and confirm the local preview shows.
2. Join the same session from a second device or browser. Confirm video appears
   **both ways** and that you can hear audio in both directions.
3. Send a chat message each way.
4. Lock the phone / switch apps for ~15 seconds, then return: the SDK should
   reconnect and resume publishing without a reload.
5. Leave, then open the recording in the dashboard: replay should show both
   participants with audio.
6. Export to MP4 and play the file.

### iOS

Two behaviours are worth knowing about, and both are platform behaviour rather
than Synento bugs:

- **Backgrounding stops capture.** iOS suspends media capture when the tab is not
  frontmost. The connection resumes on return, but the recording has a gap.
- **Autoplay of remote audio needs a gesture.** Audio playback starts from a user
  interaction (the join tap counts). A page that connects on load without any tap
  may render video silently until the user touches something.

## What your code should do

`checkSupport()` returns a structured report, and `SynentoRoom.connect()` refuses
to open a socket when it fails, rather than half-joining a call:

```ts
import { SynentoRoom } from '@synento/client'

const support = SynentoRoom.checkSupport()
if (!support.supported) {
  // support.reason is written for humans and names the missing capability.
  showUnsupportedMessage(support.reason)
  return
}
```

The individual booleans (`webSocket`, `webCodecsVideo`, `mediaDevices`,
`audioWorklet`) are all on the report, so you can tell "update your browser"
apart from "this page needs HTTPS" — a distinction users can act on.


---

# CLI Examples — Common Workflows

Source: https://synento.com/docs/examples/cli-examples

> Practical examples of using the Synento CLI for day-to-day operations.

Practical examples of using the Synento CLI for day-to-day operations.

## Setup

```bash
# Install from local monorepo
cd cli && npm install -g .

# Or use npx (no global install needed)
npx synento --help
```

## Login & Authentication

### Interactive Login
Run the command — it will prompt for your API key:
```bash
synento login
# Enter your API key (sk_live_xxx): sk_live_abc123...
```

### Non-Interactive Login (Scripts/CI)
Pass the API key as an argument or via stdin:
```bash
# Via argument (recommended for scripts)
synento login sk_live_xxxxx --url https://api.synento.com

# Via stdin (piping from secure env storage)
echo "$SYNENTO_API_KEY" | synento login

# Via environment variable (CLI reads automatically)
export SYNENTO_API_KEY=sk_live_xxxxx
synento login  # no argument needed — reads from env var
```

Credentials are stored in `~/.config/synento/credentials.json`:
```json
{ "apiKey": "sk_live_xxxxx", "apiUrl": "https://api.synento.com" }
```

## Creating Projects

### Interactive Mode
Prompts for project name and optional environment:
```bash
synento create-project
# Enter project name: Acme Video Platform
# Environment (optional, press Enter to skip): production

Output: {"id":"proj_xyz123","name":"Acme Video Platform","orgId":"org_abc456"}
```

### Non-Interactive Mode
Provide all arguments inline:
```bash
synento create-project "Staging Environment" --env staging
# → {"id":"proj_staging","name":"Staging Environment","orgId":"..."}
```

## Creating Sessions

Sessions require a project ID (use `-p` or `--project`):
```bash
# Interactive — prompts for session name (defaults to "Untitled session")
synento create-session -p proj_xyz123

# Non-interactive with custom name
synento create-session "Weekly Standup" -p proj_xyz123
# → {"id":"sess_daily456","name":"Weekly Standup"}
```

## Automation Scripts

### Daily Session Creator
Create recurring sessions with the CLI in a cron job:
```bash
#!/bin/bash
# create-daily-standup.sh

PROJECT_ID="$(synento list | grep '"id"' | head -1)"  # or hardcode the ID
SESSION_NAME="Daily Standup — $(date +%Y-%m-%d)"

RESULT=$(synento create-session "$SESSION_NAME" -p "$PROJECT_ID" --url https://api.synento.com)

echo "Created session: $RESULT"
```

### Session Token Generator (Future CLI Command)
When `synento create-session-token` is added, you'll be able to:
```bash
# Get a live connection token for CLI-based streaming
TOKEN=$(synento create-session-token -s sess_abc123 --url https://api.synento.com)
echo "Connection URL: wss://.../ws?session=$SESSION_ID&access_token=$TOKEN&user_id=alice"
```

### Session Export Script (via HTTP API)
The CLI doesn't have an export command yet, but you can pipe cURL through the stored credentials:
```bash
#!/bin/bash

# Read credentials (same store CLI uses)
CRED_FILE="$HOME/.config/synento/credentials.json"
API_KEY=$(node -e "console.log(require('$CRED_FILE').apiKey)")

# Export a session to MP4
curl -o "recording.mp4" \
  "https://api.synento.com/v1/sessions/sess_abc123/export" \
  -H "Authorization: Bearer $API_KEY"

echo "Exported to recording.mp4 ($(du -h recording.mp4 | cut -f1))"
```

### Bulk Session Deletion (HTTP API)
The CLI doesn't support deletion yet — use the HTTP API directly:
```bash
#!/bin/bash

PROJECT_ID="proj_abc123"
API_KEY="$(node -e "console.log(require('$HOME/.config/synento/credentials.json').apiKey)")"

# List all sessions and filter to old ones
curl -s "https://api.synento.com/v1/sessions" \
  -H "Authorization: Bearer $API_KEY" | \
node -e "
const stdin = require('fs').readFileSync('/dev/stdin', 'utf8');
const {data: sessions} = JSON.parse(stdin);

// Filter to sessions older than 7 days
const cutoff = Date.now() - (7 * 24 * 60 * 60 * 1000);
const old = sessions.filter(s => new Date(s.createdAt).getTime() < cutoff);

console.log(`Found ${old.length} sessions older than 7 days`);
for (const s of old) console.log(` - ${s.id} (${s.name})`);
"
```

## Troubleshooting CLI Commands

### "Authentication required" or connection errors
- Verify `synento login` completed successfully (check for success message)
- Check that credentials file exists: `cat ~/.config/synento/credentials.json`
- Verify the URL is reachable: `curl -s https://api.synento.com/health`
- Use the `--url` flag to override for a single command

### "API key invalid" or 401 errors
- Ensure the API key starts with `sk_` (invalid prefix = rejection)
- Check that your Synento server is running and accessible
- Try re-running `syneto login` to refresh stored credentials

### "ENOENT: no such file" for config
- Run `synento login` to create the credentials directory and file


---

# SDK Advanced Patterns — Replay, Exports & Webhooks

Source: https://synento.com/docs/examples/sdk-advanced

> Intermediate patterns for building robust applications on top of Synento's SDK.

Intermediate patterns for building robust applications on top of Synento's SDK.

## Pattern 1: Session Replay Engine with Auto-Looping

```javascript
import { createSynentoClient } from "@synento/node";

const synento = createSynentoClient({ apiKey: process.env.SYNENTO_API_KEY });

/**
 * Replay a session by streaming its recorded events through the SDK.
 */
async function replaySession(sessionId, renderFrame) {
  // Fetch manifest for track index and bounds (recommended bootstrap)
  const manifestUrl = `${synento.baseUrl}/v1/sessions/${sessionId}/manifest`;
  const manifestRes = await fetch(manifestUrl, {
    headers: { Authorization: `Bearer ${synento.apiKey}` },
  });
  const { data: manifest } = await manifestRes.json();

  console.log(`Session has ${manifest.participants.length} participants, ` +
    `capabilities: ${manifest.capabilities.join(", ")}`);

  // Walk through the session window by window
  let fromTs = manifest.start_ts ?? 0;
  const windowSize = 30_000; // 30 seconds per window
  let eventCount = 0;

  while (fromTs <= (manifest.end_ts ?? fromTs)) {
    const windowUrl = `${synento.baseUrl}/v1/sessions/${sessionId}/playback?from_ts=${fromTs}&window_size=${windowSize}`;
    const windowRes = await fetch(windowUrl, {
      headers: { Authorization: `Bearer ${synento.apiKey}` },
    });

    const { data } = await windowRes.json();
    if (!data.events || data.events.length === 0) break;

    for (const event of data.events) {
      const streamId = event.stream_id ?? "";
      if (streamId.includes("/media/") && streamId.endsWith("/cam")) {
        const userId = streamId.split("/media/")[1]?.split("/")[0];
        const buf = Buffer.from(event.body_base64, "base64");
        await renderFrame(buf, userId);
      } else if (streamId.endsWith("/events") || streamId.endsWith("/director")) {
        // Timeline events — useful for layout/state reduction
      } else if (streamId.endsWith("/chat")) {
        const msg = JSON.parse(Buffer.from(event.body_base64, "base64").toString());
        console.log(`[chat] ${msg.text}`);
      }
      eventCount++;

      if (eventCount % 100 === 0) {
        console.log(`Replayed ${eventCount} events...`);
      }
    }

    fromTs += windowSize;
    await new Promise(r => setTimeout(r, 10));
  }

  console.log(`Replay complete: ${eventCount} total events`);
}

// Usage: render each frame to a file (useful for creating thumbnails)
await replaySession("sess_abc123", async (frameBuffer, userId) => {
  // Write frame to a numbered file named after the user
  const timestamp = Date.now();
  console.log(`Frame for ${userId} at ${timestamp}`);
});
```

## Pattern 2: Webhook Handler with Signature Verification

```javascript
import { createHmac, timingSafeEqual } from "node:crypto";

const WEBHOOK_SECRET = "your-webhook-secret-from-api"; // stored per webhook
const ALLOWED_EVENTS = new Set([
  "session.created", "session.started", "session.ended",
  "recording.ready", "export.completed"
]);

function verifyWebhookSignature(payload, signature) {
  const expected = createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest("hex");

  // Constant-time comparison to prevent timing attacks
  return expected === signature;
}

/**
 * Example Express handler for processing webhooks.
 */
function webhookHandler(req, res) {
  const signature = req.headers["x-synento-signature"];

  if (!signature) {
    return res.status(401).json({ error: "Missing signature" });
  }

  // Parse the raw body (Express needs express.raw for this)
  const payload = req.body;

  if (!verifyWebhookSignature(payload, signature)) {
    console.warn("Invalid webhook signature from", req.ip);
    return res.status(403).json({ error: "Invalid signature" });
  }

  const eventType = payload.type; // e.g., "session.started"
  const sessionId = payload.session_id;

  if (!ALLOWED_EVENTS.has(eventType)) {
    console.warn(`Unknown event type: ${eventType}`);
    return res.status(400).json({ error: "Unknown event type" });
  }

  // Process asynchronously — respond immediately
  processWebhookEvent(payload).catch(err => {
    console.error(`Failed to process webhook ${eventType}:`, err);
  });

  res.status(200).send("OK");
}

async function processWebhookEvent(payload) {
  switch (payload.type) {
    case "session.started":
      // Session just went live — notify participants, start recording analytics...
      console.log(`🟢 LIVE: ${payload.session_id} started`);
      break;

    case "session.ended":
      // Session ended — trigger export, send email notifications...
      console.log(`⏹️ ENDED: ${payload.session_id}`);
      // Optionally trigger MP4 export
      await triggerExport(payload.session_id);
      break;

    case "export.completed":
      // MP4 is ready — notify the user, store download URL...
      console.log(`📦 EXPORTED: ${payload.session_id}`);
      break;

    default:
      console.log(`Event: ${payload.type} for session ${payload.session_id}`);
  }
}

async function triggerExport(sessionId, opts = {}) {
  const params = new URLSearchParams();
  if (opts.layout) params.set("layout", opts.layout);
  if (opts.orientation) params.set("orientation", opts.orientation);
  if (opts.focus) params.set("focus", opts.focus);

  const exportRes = await fetch(
    `${process.env.SYNENTO_API_URL}/v1/sessions/${sessionId}/export?${params}`,
    { headers: { Authorization: `Bearer ${process.env.SYNENTO_API_KEY}` } }
  );

  if (!exportRes.ok) {
    console.error(`Export enqueue failed for ${sessionId}: HTTP ${exportRes.status}`);
    return;
  }

  const { data: { job_id } } = await exportRes.json();

  // Poll until complete
  while (true) {
    const statusRes = await fetch(
      `${process.env.SYNENTO_API_URL}/v1/exports/${job_id}`,
      { headers: { Authorization: `Bearer ${process.env.SYNENTO_API_KEY}` } }
    );
    const { data } = await statusRes.json();
    if (data.status === "completed") {
      const downloadRes = await fetch(
        `${process.env.SYNENTO_API_URL}${data.download_url}`,
        { headers: { Authorization: `Bearer ${process.env.SYNENTO_API_KEY}` } }
      );
      return Buffer.from(await downloadRes.arrayBuffer());
    }
    if (data.status === "failed") {
      throw new Error(data.error ?? "Export failed");
    }
    await new Promise(r => setTimeout(r, 2000));
  }
}

module.exports = { webhookHandler };
```

## Pattern 3: Session Queue for Production Limits

When creating sessions in a loop (e.g., scheduling daily standups), respect billing limits:

```javascript
/**
 * Create sessions safely, respecting billing limits.
 */
async function createSessionWithLimits(name) {
  // Check if we're within limits before attempting creation
  const limits = await synento.getBillingLimits();

  if (limits.isBlocked) {
    throw new Error(`Session creation blocked: ${limits.statusMessage}`);
  }

  // Safe to create a session — within tier limits
  return await synento.createSession({ name });
}

/**
 * Process a queue of pending sessions, respecting rate limits.
 */
async function processSessionQueue(pendingSessions) {
  const created = [];

  for (const name of pendingSessions) {
    try {
      const session = await createSessionWithLimits(name);
      created.push(session);

      // Brief delay between sessions to avoid rate limiting
      await new Promise(r => setTimeout(r, 500));

    } catch (err) {
      console.error(`Failed to create "${name}": ${err.message}`);

      // If billing limits hit, stop the queue
      if (err.statusCode === 402 || err.message.includes("blocked")) {
        console.log(`Queue stopped — billing limits exceeded. ${created.length} created.`);
        break;
      }

      // Other errors — continue with next session in queue
    }
  }

  return created;
}
```

## Pattern 4: Expiring Link Generator for Marketing Pages

Generate shareable replay links for public sessions in marketing content:

```javascript
async function createShareLink(sessionId, expiresInMinutes = 1440) { // default: 24 hours
  const res = await fetch(
    `${synento.baseUrl}/v1/sessions/${sessionId}/replay-links`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${synento.apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ expires_in_minutes: expiresInMinutes }),
    }
  );

  const { data } = await res.json();
  return data.link; // Shareable URL like: https://host/v1/public/sessions/{id}/replay?token=xyz
}

// Usage for a marketing page: render an iframe with the expiring link
async function getEmbeddedUrl(sessionId) {
  const shareLink = await createShareLink(sessionId, 43200); // max: 30 days
  return `${shareLink}&from_ts=0&window_size=15000`;
}

// In your server response:
const iframeUrl = await getEmbeddedUrl("sess_abc123");
res.send(`<iframe src="${iframeUrl}" width="640" height="360"></iframe>`);
```


---

# SDK Basic Usage — Node.js

Source: https://synento.com/docs/examples/sdk-basic

> Full working example of creating a project, sessions, and managing them via the SDK.

Full working example of creating a project, sessions, and managing them via the SDK.

## Setup

```bash
mkdir synento-sdk-demo && cd synento-sdk-demo
npm init -y
echo '{"type":"module"}' > package.json
```

Install the Node SDK:
```bash
npm install @synento/node
```

## Complete Example: `index.mjs`

```javascript
import { createSynentoClient } from "@synento/node";

const synento = createSynentoClient({
  apiKey: process.env.SYNENTO_API_KEY, // sk_live_xxxxx
});

async function main() {
  console.log("Synento SDK Demo");
  console.log("==================\n");

  // 1. Health check
  const healthy = await synento.healthCheck();
  console.log(`Server reachable: ${healthy}`);

  // 2. Create a project (or list existing ones)
  let projects = await synento.listProjects();
  if (projects.length === 0) {
    console.log("No projects found. Creating 'Demo Project'...");
    const project = await synento.createProject("Demo Project", "development");
    console.log(`Created: ${project.name} (${project.id})`);
  } else {
    console.log(`Found ${projects.length} project(s):`);
    for (const p of projects) {
      console.log(`  - ${p.name} (${p.id}) [${p.environment || "no env"}]`);
    }
  }

  // 3. Create two sessions
  const session1 = await synento.createSession({ name: "Team Meeting" });
  console.log(`\nCreated session: ${session1.name} (${session1.id})`);

  const session2 = await synento.createSession({ name: "Q&A Session" });
  console.log(`Created session: ${session2.name} (${session2.id})`);

  // 4. List all sessions
  const sessions = await synento.listSessions();
  console.log(`\nTotal sessions: ${sessions.length}`);

  // 5. Toggle visibility
  const isPublic = await synento.setSessionVisibility(session1.id, true);
  console.log(`Session visibility: ${isPublic ? "public" : "private"}`);

  // 6. Get connection tokens
  const token1 = await synento.createConnectionToken(session1.id, { userId: "alice" });
  console.log(`\nAlice's token expires in ${token1.expiresIn}s`);

  const token2 = await synento.createConnectionToken(session1.id, {
    userId: "bob",
    replay: true,      // bob is watching a recording
    fromTs: 0,         // start from the beginning
  });
  console.log(`Bob's replay token expires in ${token2.expiresIn}s`);

  // 7. WebSocket URLs
  console.log(`\nAlice WS: ${synento.getWebSocketUrl(session1.id, token1.accessToken, "alice")}`);
  console.log(`Bob WS:   ${synento.getWebSocketUrl(session1.id, token2.accessToken, "bob")}`);

  // 8. Usage & billing
  try {
    const usage = await synento.getUsage();
    console.log(`\nUsage records: ${usage.length}`);

    const billing = await synento.getBillingSummary();
    console.log(`Streaming minutes: ${billing.streamingMinutesUsed}`);

    const limits = await synento.getBillingLimits();
    console.log(`Within free tier: ${limits.withinFreeTier}`);
  } catch (err) {
    console.log("Usage info:", err.message);
  }
}

main().catch(console.error);
```

## Run It

```bash
export SYNENTO_API_KEY=sk_live_xxxxx
node index.mjs
```

## Expected Output

```
Synento SDK Demo
==================

Server reachable: true
No projects found. Creating 'Demo Project'...
Created: Demo Project (proj_abc123)

Created session: Team Meeting (sess_def456)
Created session: Q&A Session (sess_ghi789)

Total sessions: 2
Session visibility: true

Alice's token expires in 300s
Bob's replay token expires in 300s

Alice WS: wss://api.synento.com/ws?session=sess_abc123&access_token=...&user_id=alice
Bob WS:   wss://api.synento.com/ws?session=sess_abc123&access_token=...&user_id=bob

Usage records: 0
Streaming minutes: 0
Within free tier: true
```


---

# Access Control

Source: https://synento.com/docs/guides/access-control

> Manage who can access your sessions: private, public, and expiring links.

Manage who can access your sessions: private, public, and expiring links.

## Access Levels

Synento supports three access modes for sessions:

| Mode | Who Can Replay | Auth Required? | Use Case |
|------|----------------|----------------|----------|
| **Private** (default) | Connection token holders only | Yes — API key + valid JWT | Internal meetings, customer calls |
| **Public** | Anyone with the session ID | No — completely open | Demo sessions, public webinars |
| **Expiring Link** | Anyone with the unique URL | No — token-based (time-limited) | Share with external parties temporarily |

## Making a Session Public/Private

Toggle visibility via the update endpoint:

```bash
# Make public — anyone can replay
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"is_public": true}'

# Make private — only token holders can replay (default)
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"is_public": false}'
```

Response: `{"data": true, "error": null}` (reflects the updated visibility state).

## Public Session Access Endpoints

When a session is public (`is_public = true`), these endpoints work without authentication:

### Public Playback Window
```bash
curl "https://api.synento.com/v1/public/sessions/{sessionId}/playback?from_ts=0&window_size=30000"
```

### Public Timeline Metadata
```bash
curl https://api.synento.com/v1/public/sessions/{sessionId}/playback/timeline
```

### Public Replay with Token Fallback
```bash
curl "https://api.synento.com/v1/public/sessions/{sessionId}/replay?token=EXPIRING_TOKEN&from_ts=0"
```

This endpoint checks for an expiring replay token first, then falls back to the public session check if no valid token is provided.

## Expiring Replay Links

Create time-limited replay links for sharing with external parties:

```bash
curl -X POST https://api.synento.com/v1/sessions/{sessionId}/replay-links \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"expires_in_minutes": 60}'
```

Response:
```json
{ "data": {
  "link": "https://host/v1/public/sessions/{sessionId}/replay?token=abc123",
  "token": "abc123",
  "expires_at": "2025-01-15T13:00:00.000Z"
}, "error": null }
```

### Link Details

| Parameter | Default | Max Value | Description |
|-----------|---------|-----------|-------------|
| `expires_in_minutes` | Platform default | 43200 (30 days) | TTL of the link in minutes |

The link works with all playback query parameters:
```
https://host/v1/public/sessions/{sessionId}/replay?token={token}&from_ts=5000&window_size=60000
```

When the token expires, access is denied (401 or 403). Links are automatically invalidated when the session's recording is deleted.

## Public Session Catalog

Anyone can browse publicly accessible sessions (no auth required):

```bash
curl https://api.synento.com/v1/public/sessions
```

Response (no project IDs exposed for privacy):
```json
{ "data": [
  { "id": "...", "name": "Public Demo",
    "created_at": "...", "started_at": "...", "ended_at": "..." }
], "error": null }
```

Sessions are sorted by `created_at` DESC. Only metadata is included — no project or organisation data.

## Embedding Public Sessions

Public sessions can be embedded via an iframe with the replay endpoint:

```html
<iframe 
  src="https://your-server.com/v1/public/sessions/{sessionId}/replay?from_ts=0&window_size=30000"
  width="640" height="360">
</iframe>
```

For a richer experience, use the [Player SDK](https://synento.com/docs/guides/sdk.md) with the public playback endpoints.

## Security Notes

1. **Public sessions are fully visible** — anyone with the session ID can replay them
2. **Expiring links degrade to public access** if the underlying session is marked `is_public = true`
3. **Session IDs are not secrets** — access control relies on `is_public` flag and token validation, not ID obscurity
4. **Replay tokens are independent of connection tokens** — use `POST /v1/sessions/:sessionId/replay-links` for sharing, not `/connection` endpoints

## Credentials

Who can do what to your account, from widest to narrowest:

| Credential | Held by | Reaches |
|---|---|---|
| Dashboard session | You, in a browser | Everything in your organisation |
| API key `sk_live_…` | Your servers | Your organisation's management API, and sessions in its project |
| Restricted key `rk_live_…` | Your app, often written there by an agent | One project: create sessions, mint connection tokens, read manifests — nothing else |
| Agent token `sat_…` / OAuth token | An MCP client | Only the MCP endpoint, only the projects and permissions you approved |
| Connection token | One participant's browser | One session, as one participant, for an hour |

Give each piece of code the narrowest one that works. An app that only creates
sessions and lets people join needs no more than a restricted key. See
[Connect your agent](https://synento.com/docs/guides/mcp.md) for the agent credentials.


---

# CLI Guide

Source: https://synento.com/docs/guides/cli

> The Synento Command Line Interface (CLI) provides quick project and session management from the terminal.

The Synento Command Line Interface (CLI) provides quick project and session management from the terminal.

## Installation

The CLI is published as an npm package in `cli/`:

```bash
npx synento --help
```

Or install globally for convenience:

```bash
cd cli && npm install -g .
synento --help
```

## Commands

### `synento login [apiKey] [--url <baseUrl>]`

Authenticate and store credentials locally. Credentials are saved to `~/.config/synento/credentials.json`.

**Interactive mode:**
```bash
synento login
# Prompts: Enter your API key (sk_live_xxx): 
```

**Non-interactive mode:**
```bash
synento login sk_live_xxxxx

# Or via stdin (for scripting):
echo "sk_live_xxxxx" | synento login
```

Every command talks to the hosted API, `https://api.synento.com`.

**Environment variable override:**
```bash
export SYNENTO_API_KEY=sk_live_xxxxx
synento login  # uses env var if no argument provided
```

### `synento create-project [name] [--env <environment>] [--url <baseUrl>]`

Create a new project under your organisation. In non-interactive mode, pass the name as an argument:

```bash
# Interactive — prompts for project name and environment
synento create-project

# Non-interactive with all values
synento create-project "My App" --env production
```

Response (printed to stdout):
```json
{ "id": "proj_abc123", "name": "My App", "org_id": "org_xyz789" }
```

### `synento create-session [name] -p|--project <projectId> [--url <baseUrl>]`

Create a new session under the specified project:

```bash
# Interactive — prompts for session name (defaults to "Untitled session")
synento create-session -p proj_abc123

# Non-interactive
synento create-session "Team Standup" -p proj_abc123
```

Response (printed to stdout):
```json
{ "id": "sess_def456", "project_id": "proj_abc123", "name": "Team Standup" }
```

## Credential Storage

Credentials are stored in `~/.config/synento/credentials.json`:
```json
{ "apiKey": "sk_live_xxxxx", "apiUrl": "https://api.synento.com" }
```

This file is excluded from git via the root `.gitignore`. Never commit this file.

## Scripting Examples

### Create a project and session in one script
```bash
#!/bin/bash
KEY="sk_live_xxxxx"
PROJECT=$(synento create-project "CI Test" -p "" | grep '"id"' | cut -d'"' -f4)
SESSION=$(synento create-session "Test Run" -p "$PROJECT" | grep '"id"' | cut -d'"' -f4)
echo "Created project: $PROJECT, session: $SESSION"
```

### Pipe API key from CI environment variable
```bash
export SYNENTO_API_KEY="${{ secrets.SYNENTO_API_KEY }}"
echo "$SYNENTO_API_KEY" | synento login --url https://api.synento.com
synento create-project "Pipeline Project" | npx json -a id  # extract ID via `json` CLI
```

## Limitations

The current CLI provides basic project and session management. Future commands planned:
- `synento list-sessions` — list sessions with filtering
- `synento create-session-token` — get connection tokens for CLI-driven streaming
- `synento export` — download/export sessions to MP4


---

# Connect your agent (MCP)

Source: https://synento.com/docs/guides/mcp

> Connect Claude Code, Cursor, VS Code or any MCP client to Synento, and let it build and verify your video integration.

Synento runs a remote [MCP](https://modelcontextprotocol.io) server. Connect
your coding agent to it and the agent can set up a project, write your
integration, and then **prove the video works** by reading back what was
actually recorded — without you opening a dashboard.

The server is at:

```
https://api.synento.com/mcp
```

It speaks Streamable HTTP and authenticates with OAuth 2.1. The first time your
agent uses it, your browser opens so you can sign in and choose what the agent
may do.

## Connect

### Claude Code

```bash
claude mcp add --transport http synento https://api.synento.com/mcp
```

Then run `/mcp` in Claude Code and choose **synento** to sign in.

### Cursor

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "synento": { "url": "https://api.synento.com/mcp" }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "synento": { "type": "http", "url": "https://api.synento.com/mcp" }
  }
}
```

### Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth
will work: point it at `https://api.synento.com/mcp`. It discovers everything
else itself — the server answers an unauthenticated request with a `401` whose
`WWW-Authenticate` header points to
[`/.well-known/oauth-protected-resource/mcp`](https://api.synento.com/.well-known/oauth-protected-resource/mcp).
Clients may register dynamically (RFC 7591) or identify themselves with a
client ID metadata document.

For a client that can't sign in through a browser (a CI job, a headless
agent), create an **agent token** in the dashboard under **Agents** and send
it as a header:

```bash
claude mcp add --transport http synento https://api.synento.com/mcp \
  --header "Authorization: Bearer sat_…"
```

## What you approve

When the agent connects, Synento shows you who is asking and lets you choose:

- **Projects** — the agent can only see and act in the projects you tick.
- **Permissions** — one or more of:

| Permission | Lets the agent |
|---|---|
| `mcp:read` | Read projects, sessions, usage and session manifests |
| `mcp:write` | Create sessions and connection tokens, and run media checks |
| `keys:mint` | Create restricted server keys for your app's environment |
| `projects:create` | Create new projects, which it can then use |

Whatever you tick, an agent can never see your owner API keys, change billing,
invite people, or delete anything. You can disconnect it at any time from the
dashboard under **Agents**; its access ends on its next request.

## Tools

| Tool | What it does |
|---|---|
| `get_account` | The organisation, the projects this connection may use, plan limits, and next steps. |
| `list_projects` | The projects this connection may use. |
| `create_project` | Create a project; the connection can use it straight away. |
| `create_session` | Create a session. Accepts an `idempotency_key`, so a retry never makes a second one. |
| `create_connection_token` | A short-lived token for one participant to join from a browser — for trying things locally. |
| `list_sessions` | Recent sessions in a project. |
| `create_server_key` | A restricted `rk_live_` key for your app's server-side environment, returned once. |
| `get_session_manifest` | Every participant and track that actually holds recorded media. |
| `verify_session` | Checks a session's recording against what you expected, and says what is missing and why. |
| `run_media_check` | Publishes a synthetic two-person call through Synento and verifies it from the recording. |
| `get_guide` | Any page of these docs. The same pages are available as MCP resources. |

## The loop your agent follows

1. **`get_account`** — see which projects it may use.
2. **`create_server_key`** — mint a restricted key and write it to your app's
   server-side environment (`.env`, which must be gitignored):

   ```bash
   SYNENTO_API_KEY=rk_live_…
   SYNENTO_API_URL=https://api.synento.com
   SYNENTO_PROJECT_ID=…
   ```

3. **Write the integration** — the server creates sessions and mints
   connection tokens with [`@synento/node`](https://synento.com/docs/guides/sdk.md); the browser joins with
   `@synento/client` using only the short-lived connection token. See
   [Getting Started](https://synento.com/docs/getting-started.md).
4. **Run the app** and publish camera and microphone into a session.
5. **`verify_session`** on that session. It passes only when each participant's
   tracks actually hold recorded media. If it fails, it tells the agent what is
   missing and the usual cause — no audio track in the stream, publishing
   before `connect()` resolved, a token for the wrong session.

An agent should not report the integration as working until `verify_session`
passes. If it keeps failing, `run_media_check` tells a Synento problem from an
integration problem: it sends a synthetic call through the same WebSocket
endpoint and recording path your app uses. It does not run your code, so it
cannot prove your integration works — only `verify_session` on your app's own
session can.

## Restricted server keys

The key an agent writes into your environment is a **restricted key**
(`rk_live_…`), not an owner API key. It belongs to one project and works on
exactly four routes:

- `POST /v1/sessions` and `POST /v1/projects/{projectId}/sessions`
- `POST /v1/sessions/{sessionId}/connection` (live and replay tokens)
- `GET /v1/sessions/{sessionId}/manifest`

Every other route refuses it. `@synento/node` works with it unchanged. Keys
an agent created are marked as such under **Agents** in the dashboard, where
you can revoke them.

## Security

- **Tokens are bound to this server.** Access tokens are opaque, last an hour,
  and are issued for exactly one audience, `https://api.synento.com/mcp`.
- **PKCE is required** for every authorization, and only the authorization-code
  flow is supported.
- **Refresh tokens rotate** on every use. Presenting one that was already used
  revokes the whole connection.
- **Nothing a token grants outlives its grant.** Each request re-checks that the
  connection is still approved, the person is still in the organisation, and
  each project still belongs to it.
- **Every tool call is recorded.** The dashboard's **Agents** page shows recent
  activity: which tool, which project, and whether it worked.
- **Scope is enforced on every call.** Calling a tool without the permission it
  needs returns `403` with `error="insufficient_scope"`, so the client can ask
  you for more.

## Troubleshooting

### The browser says the request has expired

The sign-in link is valid for 30 minutes. Go back to your agent and connect
again.

### A tool fails with "requires the … scope"

The connection wasn't granted that permission. Reconnect (in Claude Code:
`/mcp`, then re-authenticate **synento**) and tick it.

### "Project … is not available to this connection"

The agent is using a project you didn't approve. Reconnect and tick it, or
allow `projects:create` and let the agent make one.


---

# Recordings & Replay

Source: https://synento.com/docs/guides/recordings-replay

> How Synento's layout-agnostic recording model works and how to replay sessions with configurable layouts.

How Synento's layout-agnostic recording model works and how to replay sessions with configurable layouts.

## The Stream-Native Recording Model

In Synento, **recording is not a separate step**. Every session automatically creates a recording the moment it starts:

```
Capture (per participant) → S2 append log (separated tracks + event timeline)
                                    ↓
              ┌─────────────────────┴─────────────────────┐
              ↓                                           ↓
     Composable replay (client)                    Export (server, MP4)
     layout descriptor + director track            same layout vocabulary
```

There is no encoding delay. As soon as the last participant leaves a session, the recording is instantly replayable at full fidelity. **Presentation is never baked in** — the stored data is a timeline of media tracks and typed events; the player (or exporter) composes the final view at playback time.

## What Gets Recorded

Each session under `a/{projectId}/rooms/{sessionId}/` persists several stream types:

### 1. Separated media tracks (`media/{userId}/{kind}`)

Each participant writes up to three independent track streams:

| Stream | Kind | Contents |
|--------|------|----------|
| `media/{userId}/cam` | Camera video | WebCodecs `EVC1` (H.264/VP9/VP8) or MJPEG image bytes |
| `media/{userId}/mic` | Microphone audio | Raw audio samples (s16le, 16 kHz mono) |
| `media/{userId}/screen` | Screen share | Same video formats as `cam` |

Track separation lets playback select only what a layout needs (e.g. active-speaker uses audio independently of video; screen-share focus reads the screen track alone).

Video payloads are **self-describing**:

- **WebCodecs chunk** (preferred): `EVC1` magic + 18-byte header (codec id, keyframe flag, dimensions, timestamp µs) + elementary stream (annexb H.264, or VP9/VP8).
- **MJPEG image** (fallback): raw JPEG/WebP bytes.

The server relay stores and forwards payloads opaquely — it never re-encodes.

### 2. Event timeline (`events` stream)

A versioned, append-only JSON timeline. Every event shares one envelope:

```json
{ "v": 1, "type": "participant.joined", "ts": 1699876000123, "actor": "alice", "data": {} }
```

Core event types:

| Type | Purpose |
|------|---------|
| `participant.joined` / `participant.left` | Lifecycle |
| `track.added` / `track.removed` | Track lifecycle (kind: `cam`, `mic`, `screen`) |
| `screenshare.started` / `screenshare.stopped` | Screen-share lifecycle |
| `speaking.started` / `speaking.stopped` | Voice activity (from client-side VAD at capture) |
| `director.cut` | Computed layout decision (focus participant, reason) |
| `caption.cue` | Timed caption overlay |
| `branding.applied` | Logo/watermark/accent colour |
| `highlight.marked` | Highlight clip span |
| `participant.redacted` | GDPR/removal annotation |

The `meta` stream still receives legacy join/leave/control records for compatibility, but **`events` is the canonical timeline** for reconstructing session state.

### 3. Director track (`director` stream)

When a session ends, the server computes active-speaker cuts from the speaking timeline and persists them as `director.cut` events. This makes active-speaker playback **deterministic and cheap** — clients read pre-computed focus switches instead of re-deriving them from raw audio on every replay.

Director cuts honour a minimum hold time (default 1.5 s) to avoid rapid switching.

### 4. Chat (`chat` stream)

Text messages between participants as JSON (base64-encoded):

```json
{"text": "Hello everyone!", "userId": "bob", "timestamp_ms": 1234567}
```

### 5. Captions (`captions/{lang}` stream, optional)

Per-language caption cues, using the same `caption.cue` event envelope. The session manifest advertises a captions stream when present.

## Session Manifest

`GET /v1/sessions/:sessionId/manifest` returns the **reconstruction contract** — enough to bootstrap playback without reading every stream:

```json
{
  "data": {
    "version": 1,
    "session_id": "sess-abc123",
    "epoch": 1699876000000,
    "start_ts": 1699876000000,
    "end_ts": 1699876300000,
    "participants": [
      {
        "user_id": "alice",
        "tracks": [
          { "kind": "cam", "stream_id": "a/.../media/alice/cam", "start_ts": 1000, "end_ts": 5000 },
          { "kind": "mic", "stream_id": "a/.../media/alice/mic", "start_ts": 1100, "end_ts": 4980 }
        ]
      }
    ],
    "streams": {
      "events": "a/.../events",
      "chat": "a/.../chat",
      "director": "a/.../director",
      "captions": "a/.../captions/en"
    },
    "capabilities": [
      "separated-tracks",
      "event-timeline",
      "director-track",
      "configurable-layouts",
      "captions"
    ]
  },
  "error": null
}
```

Use the manifest to fetch only the tracks a layout needs (bandwidth win) and to discover optional features (director track, captions).

Public sessions: `GET /v1/public/sessions/:sessionId/manifest`.

## Session Lifecycle & Recording States

| State | Description | Timestamp Field |
|-------|-------------|-----------------|
| **Created** | Session created, no participants yet | `created_at` set |
| **Started** | First participant joined | `started_at` set |
| **Streaming** | Active session with participants connected | — |
| **Ended / Recording Ready** | Last participant left, recording complete; director track computed | `ended_at` set |

A session's "recording" is the persisted streams between start and end. To check if a recording is ready: look for `ended_at !== null`.

## Accessing Recordings (Replay)

### Step 1: Get the manifest (recommended)

```bash
curl https://api.synento.com/v1/sessions/{sessionId}/manifest \
  -H "Authorization: Bearer sk_live_xxxxx"
```

Returns participants, separated track index, time bounds, and capabilities.

Alternatively, use the lighter playback timeline for stream IDs and bounds:

```bash
curl https://api.synento.com/v1/sessions/{sessionId}/playback/timeline \
  -H "Authorization: Bearer sk_live_xxxxx"
```

### Step 2: Read playback windows (iterative)

The playback API reads all relevant streams (events, director, chat, and every participant track) in time-based windows:

```bash
curl "https://api.synento.com/v1/sessions/{sessionId}/playback?from_ts=0&window_size=30000" \
  -H "Authorization: Bearer sk_live_xxxxx"
```

Continue while `next_base_seq` is non-null. When it is `null`, playback is complete.

Each event includes `stream_id` (full S2 path), `timestamp`, and `body_base64`. Media track events carry raw payload bytes (no outer wire header).

### Step 3: Compose the view (client side)

Rather than rendering one participant at a time, the **composition layer** decodes the tracks a layout needs and draws them into a single canvas:

1. **Reduce session state** — process `events` and `director` events up to the playhead (participants, active speaker, screen sharers).
2. **Resolve layout** — map a layout descriptor + session state to normalized regions (0..1 coordinates).
3. **Decode tracks** — WebCodecs `VideoDecoder` for `EVC1` chunks, `createImageBitmap` for MJPEG; one offscreen surface per visible track.
4. **Draw** — composite regions onto the output canvas; optional caption and branding overlays.

Available layout types:

| Layout | Behaviour |
|--------|-----------|
| `active-speaker` | Focus the current speaker (from director/speaking events); thumbnails for others |
| `presenter` | Focus a designated participant |
| `grid` | Equal tiles for all active cameras |
| `screen-share` | Full-frame screen share with camera thumbnails; falls back to active-speaker |
| `selected` | Grid of chosen participants only |
| `custom` | Explicit normalized regions |

The dashboard replay player (`web/app`) exposes a layout selector (Speaker / Grid / Presenter / Screen). The player SDK provides the same engine for embeds.

## Replay Controls

- **Seek** — jump to any timestamp (`from_ts` parameter)
- **Speed control** — play at 0.5x, 1x (default), or 2x
- **Layout switching** — change composition instantly without re-fetching (client-side)
- **Pause / resume** — stop consuming events without losing position

## Player SDK (`@synento/player`)

> **Two limits to know before you choose this path.**
>
> **In-browser replay is video-only.** The player composes camera and screen
> tracks; it does not decode the microphone tracks. Audio exists in the
> **MP4 export**, which is muxed server-side. If your users need to *hear* a
> recording, export it and serve the file — see
> [Exporting to MP4](#exporting-to-mp4) — rather than reaching for the player.
>
> **`PlaybackEngine` authenticates with an API key**, so the snippet below is
> for **trusted, server-side or first-party contexts only**. Never ship a
> `sk_live_` key to a browser. For a customer-facing embed today, proxy the
> playback endpoints through your own backend (which holds the key) exactly as
> the Synento dashboard does, or make the session public and read the
> unauthenticated `/v1/public/sessions/:id/...` endpoints.

The player SDK wraps windowed playback and provides a full composition stack:

```typescript
import {
  PlaybackEngine,
  Compositor,
  resolveLayout,
  reduceSessionState,
  parseSessionEvents,
  availableTracks,
  type LayoutDescriptor,
} from "@synento/player";

const engine = new PlaybackEngine(sessionId, apiBase, apiKey);
await engine.fetchTimeline();

const canvas = document.querySelector("canvas")!;
const compositor = new Compositor({ canvas, width: 1280, height: 720 });

const descriptor: LayoutDescriptor = {
  type: "active-speaker",
  orientation: "landscape",
  captions: true,
};

engine.isPlaying = true;
await engine.play(() => {
  // Pass accumulated window events + current playhead to the compositor.
  compositor.render(descriptor, windowEvents, engine.currentTimeMs);
});

compositor.dispose();
```

Lower-level helpers (`resolveLayout`, `reduceSessionState`, `availableTracks`, `resolveActiveCaption`, `resolveBranding`) are pure and reusable — the server export layout engine shares the same vocabulary.

See [`@synento/player`](https://www.npmjs.com/package/@synento/player) for the full API.

## Exporting to MP4

Export is **async** and **parameterized by layout**. The web dashboard can enqueue and download exports while logged in (session cookie via the API proxy). For scripts and integrations, pass a project API key on each request:

```bash
# Enqueue export (returns job id)
curl "https://api.synento.com/v1/sessions/{sessionId}/export?layout=presenter&orientation=vertical&focus=alice" \
  -H "Authorization: Bearer sk_live_xxxxx"
```

Response (202):

```json
{ "data": { "job_id": "..." }, "error": null }
```

Query parameters:

| Parameter | Values | Default |
|-----------|--------|---------|
| `layout` | `grid`, `presenter` | `grid` |
| `orientation` | `landscape` (1280×720), `vertical` (720×1280) | `landscape` |
| `focus` | Participant user id (for presenter layout) | first participant |

Poll status:

```bash
curl https://api.synento.com/v1/exports/{jobId} \
  -H "Authorization: Bearer sk_live_xxxxx"
```

When `status` is `completed`, download via `download_url`:

```bash
curl https://api.synento.com/v1/exports/{jobId}/download \
  -H "Authorization: Bearer sk_live_xxxxx" \
  --output session.mp4
```

Export behaviour:

- Reads separated `cam` and `mic` tracks per participant
- **Codec-aware**: H.264 sessions mux annexb directly; MJPEG sessions use `image2pipe` with frame-gap repetition
- Composes video via FFmpeg using the same layout vocabulary as the client compositor
- Export artifacts are stored by Synento and served from the download endpoint

## Participant redaction

Remove a participant's media while keeping the rest of the session:

```bash
curl -X DELETE https://api.synento.com/v1/sessions/{sessionId}/participants/{userId} \
  -H "Authorization: Bearer sk_live_xxxxx"
```

This deletes all of the participant's track streams (`cam`, `mic`, `screen`) and appends a `participant.redacted` event to the timeline. Playback and export skip redacted tracks and can render a placeholder.

## Architecture diagram

```mermaid
flowchart TB
  subgraph rec [Recording layer — layout agnostic]
    cam[media/userId/cam]
    mic[media/userId/mic]
    scr[media/userId/screen]
    ev[events timeline]
    dir[director track]
  end
  rec --> comp[Composition layer]
  comp --> lay[Layout descriptor]
  comp --> cli[Client compositor — @synento/player]
  comp --> srv[Server exporter — FFmpeg]
  lay --> cli
  lay --> srv
  cli --> view[Interactive playback]
  srv --> art[MP4 / vertical / clips]
```


---

# SDK Guide

Source: https://synento.com/docs/guides/sdk

> Integrate Synento into your application using the JavaScript/TypeScript SDK.

Integrate Synento into your application using the JavaScript/TypeScript SDK.

## Installation

```bash
npm install @synento/node
```

```typescript
import { createSynentoClient } from "@synento/node";
import type { Session, Project, ConnectionToken } from "@synento/node";
```

## Initialization

```typescript
const synento = createSynentoClient({
  apiKey: "sk_live_xxxxx",
  baseUrl: "https://api.synento.com" // optional: SYNENTO_API_URL, then this
});
```

This client holds your secret API key, so it belongs on the server only. In the
browser, use [`@synento/client`](https://www.npmjs.com/package/@synento/client) and have your server
mint short-lived connection tokens for it.

## Retry Configuration

Enable automatic retry for transient failures (network errors, 5xx responses):

```typescript
synento.withRetry({ maxRetries: 3, baseDelayMs: 500 });
```

The retry uses exponential backoff with jitter. Check the current config:
```typescript
const options = synento.getRetryOptions(); // { maxRetries: 2, baseDelayMs: 500 }
```

## Session Methods

### Create a Session
```typescript
const session = await synento.createSession({ name: "My Meeting" });
console.log(session.id); // sess_abc123
```

### List Sessions
```typescript
const sessions = await synento.listSessions();
for (const s of sessions) {
  console.log(`${s.name} — ${s.startedAt ? "Started" : "Not started"} at ${s.createdAt}`);
}
```

### Get a Single Session
```typescript
const session = await synento.getSession("sess_abc123");
if (session) {
  console.log(`Session ended at: ${session.endedAt || "not yet"}`);
} else {
  console.log("Session not found"); // returns null for 404
}
```

### Toggle Session Visibility
```typescript
await synento.setSessionVisibility("sess_abc123", true); // make public
```

## Connection Token Methods

### Get a Live Streaming Token
```typescript
const token = await synento.createConnectionToken("sess_abc123", { userId: "alice" });
// → { accessToken: "...", expiresIn: 300, session: "sess_abc123" }
```

### Get a Replay Token
```typescript
const token = await synento.createConnectionToken("sess_abc123", {
  userId: "viewer",
  replay: true,
  fromTs: 0,     // start from beginning (use timeline API to find the right offset)
  speed: 1.0,    // playback speed (0.25 to 4)
});

// Connect WebSocket for replay
const wsUrl = synento.getWebSocketUrl("sess_abc123", token.accessToken, "viewer");
const ws = new WebSocket(wsUrl);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data as string);
  if (data.stream_type.startsWith("media/")) {
    // Decode and render video frame from data.body (base64 JPEG)
  }
};
```

### Generate WebSocket URL
```typescript
const wsUrl = synento.getWebSocketUrl(sessionId, accessToken, "alice");
// → wss://host/ws?session=sess_abc123&access_token=...&user_id=alice
```

## Project Methods

### Create a Project
```typescript
const project = await synento.createProject("My App", "production");
// → { id: "...", name: "My App", orgId: "...", environment: "production" }
```

### List Projects
```typescript
const projects = await synento.listProjects();
// → [{ id, name, orgId, environment }, ...]
```

## Webhook Methods

### Create a Webhook
```typescript
const webhook = await synento.createWebhook(
  "https://example.com/webhooks/synento",
  ["session.created", "session.started", "session.ended"]
);

// Events: session.created, session.started, session.ended, recording.ready, export.completed
```

### List Webhooks
```typescript
const webhooks = await synento.listWebhooks();
// → [{ id, projectId, url, events: string[], isActive }]
```

## Usage & Billing Methods

### Check Billing Limits
```typescript
const limits = await synento.getBillingLimits();
if (limits.isBlocked) {
  console.error(`Blocked: ${limits.statusMessage}`);
}

// Access individual fields
console.log(`Minutes used: ${limits.streamingMinutesUsed}`);
console.log(`Has subscription: ${limits.hasActiveSubscription}`);
```

### Get Billing Summary with Cost Breakdown
```typescript
const summary = await synento.getBillingSummary();
// → { streamingMinutesUsed, storageBytesUsed, costBreakdown?: { streamingCost, storageCost, totalDue } }
```

### Get Usage Records
```typescript
const records = await synento.getUsage();
// → [{ id, projectId, sessionId, usageType: "streaming_minutes"|"storage_bytes", value, recordedAt }]
```

## API Key Management

### List Keys (metadata only — no secrets)
```typescript
const keys = await synento.listApiKeys();
// → [{ id, projectId, createdAt }]
```

### Create a New Key (returns the raw secret)
```typescript
const result = await synento.createApiKey();
// → { id: "...", secret: "sk_live_xxxxx" } ← show this ONCE
```

### Revoke a Key (deletes it)
```typescript
await synento.revokeApiKey("key_id_here"); // deletes the key permanently
// → true (on success)
```

### Restricted keys

A restricted key (`rk_live_…`) works with the same client for everything an
integration does — `createSession`, `createConnectionToken` and
`getSessionManifest` — and nothing else. It is what a coding agent connected
over [MCP](https://synento.com/docs/guides/mcp.md) writes into your environment:

```bash
SYNENTO_API_KEY=rk_live_…
SYNENTO_API_URL=https://api.synento.com
SYNENTO_PROJECT_ID=…
```

### Check that media arrived
```typescript
const manifest = await synento.getSessionManifest(session.id);
// A participant whose tracks include "cam" and "mic" really published both.
const alice = manifest.participants.find((p) => p.user_id === "alice");
const kinds = alice?.tracks.map((t) => t.kind) ?? [];
```

## Advanced Patterns

### Full Session Lifecycle in One Block
```typescript
const project = await synento.createProject("Live Q&A");
const session = await synento.createSession({ name: "Q&A Session #5" });
await synento.setSessionVisibility(session.id, true); // make it public

const hostToken = await synento.createConnectionToken(session.id, { userId: "host" });
const guestToken = await synento.createConnectionToken(session.id, { userId: "guest-1" });

// Share URLs with participants (host token for broadcasting, guest for joining)
const hostWsUrl = synento.getWebSocketUrl(session.id, hostToken.accessToken, "host");
const guestWsUrl = synento.getWebSocketUrl(session.id, guestToken.accessToken, "guest-1");
```

### Error Handling
```typescript
import { SynentoError } from "@synento/node";

try {
  const session = await synento.createSession({ name: "Test" });
} catch (err) {
  if (err instanceof SynentoError && err.statusCode === 401) {
    console.error("Invalid or expired API key");
  } else if (err instanceof SynentoError && err.statusCode === 403) {
    console.error("Project access denied");
  } else if (err instanceof SynentoError && err.statusCode === 429) {
    console.error("Rate limited — retry after delay");
  } else {
    console.error("Unexpected error:", err.message);
  }
}
```

### Reconnecting After Token Expiry
```typescript
async function getReconnectToken(client: SynentoClient, sessionId: string): Promise<ConnectionToken> {
  const token = await client.createConnectionToken(sessionId, { userId: "reconnect-user" });
  
  // Token expires after `token.expiresIn` seconds — regenerate before expiry
  setTimeout(async () => {
    const newToken = await getReconnectToken(client, sessionId);
    // Update your WebSocket URL or reconnect...
  }, token.expiresIn * 800); // refresh at 80% of TTL
  
  return token;
}
```


---

# Session Management Guide

Source: https://synento.com/docs/guides/sessions

> Deep dive into creating, managing, and controlling live streaming sessions.

Deep dive into creating, managing, and controlling live streaming sessions.

## Creating a Session

Sessions are the core unit of Synento. Every stream is attached to exactly one session:

```bash
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:
```json
{ "data": {
  "id": "sess_abc123",
  "project_id": "proj_xyz789",
  "name": "Team Standup",
  "created_by": "api-key-user",
  "started_at": null,     // set when first participant joins
  "ended_at": null,       // set when last participant leaves
  "created_at": "2025-01-15T10:30:00.000Z"
}, "error": null }
```

### Options

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `name` | No | "Untitled session" | 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

| 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 |

Duration calculation: `ended_at - started_at` (in milliseconds). Usage tracking records this as `streaming_minutes`.

## Listing Sessions

Retrieve all sessions for a project:

```bash
curl https://api.synento.com/v1/sessions \
  -H "Authorization: Bearer sk_live_xxxxx"
```

Returns sessions sorted by `created_at` DESC. The same endpoint is accessible via SDK:

```typescript
const sessions = await synento.listSessions();
// [{ id, name, startedAt, endedAt, createdAt }, ...]
```

## Getting Session Details

Fetch a single session:

```bash
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
```bash
curl -X POST https://api.synento.com/v1/sessions/{sessionId}/connection \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"user_id": "alice", "focus": ""}'
```

### For Replay Mode
```bash
curl -X POST https://api.synento.com/v1/sessions/{sessionId}/connection \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"user_id": "viewer", "replay": true, "from_ts": 0, "speed": 1.0}'
```

### Token Connection Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `user_id` | string | `"anonymous"` | Participant identifier (appears in chat/media headers) |
| `replay` | boolean | false | If true, enables replay mode instead of live streaming |
| `from_ts` | number (ms) | 0 | Replay start timestamp; use session's `min_ts` from timeline API |
| `speed` | number | 1.0 | Replay speed multiplier (0.25x to 4x) |
| `focus` | string | "" | Focus on a specific stream (user ID or empty for all) |

### Token Response

```json
{ "data": {
  "access_token": "jwt_eyJhbGc...",    // JWT valid for 5 minutes
  "expires_in": 300,                     // seconds until expiry
  "session": "sess_abc123"              // session ID
}, "error": null }
```

The connection token's `access_token` is used to connect via WebSocket:
```javascript
const wsUrl = synento.getWebSocketUrl(sessionId, accessToken, "alice");
// → wss://host/ws?session=sess_abc123&access_token=jwt_eyJhbGc...&user_id=alice
```

## Session Visibility Management

Sessions are private by default. Control who can replay them:

### Toggle Public/Private
```bash
# 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" \
  -d '{"is_public": true}'

# Revert to private (only connection token holders can access)
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"is_public": false}'
```

### Setting via SDK
```typescript
const result = await synento.setSessionVisibility(sessionId, true);  // make public
```

## Billing & Session Limits

New session creation is checked against billing limits:

- **Free tier**: 300 streaming minutes/month across the organisation
- If exceeded with no active Stripe subscription, new sessions are blocked (402 error)

Check current limits before creating sessions:
```bash
curl https://api.synento.com/v1/billing/limits \
  -H "Authorization: Bearer sk_live_xxxxx"

# Check before every new session in your app
const limits = await synento.getBillingLimits();
if (limits.isBlocked) {
  console.error(limits.statusMessage); // Show user-friendly error to developer
}
```

## Common Patterns

### Create Session, Get Token, Connect (All in One Flow)
```typescript
const session = await synento.createSession({ name: "Team Meeting" });
const token = await synento.createConnectionToken(session.id, { userId: "alice" });

// WebSocket URL
const wsUrl = synento.getWebSocketUrl(session.id, token.accessToken, "alice");

// For embedding in the browser (token generated server-side):
document.getElementById("player").src = wsUrl; // or use Player SDK with access_token
```

### List and Replay All Ended Sessions in a Project
```typescript
const sessions = await synento.listSessions();
for (const session of sessions) {
  if (session.endedAt && !session.isPublic) {
    const token = await synento.createConnectionToken(session.id, { 
      userId: "replay-bot",
      replay: true,
    });
    // Use the token with Player SDK or direct WebSocket for replay...
  }
}
```


---

# Webhooks Guide

Source: https://synento.com/docs/guides/webhooks

> Set up event-driven integrations that react to Synento session events.

Set up event-driven integrations that react to Synento session events.

## Overview

Synento automatically emits webhook events for key lifecycle moments:
- `session.created` — a new session is created via API
- `session.started` — the first participant joins a session
- `session.ended` — all participants leave (last one departs)
- `recording.ready` — stream recording is fully persisted and replayable
- `export.completed` — MP4 export finishes successfully

## Setting Up a Webhook Receiver

### 1. Create the webhook endpoint on your server

```javascript
// Example: Express.js handler
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-synento-signature'] ?? '';

  // Verify HMAC-SHA256 over the raw body, exactly as received
  const crypto = require('crypto');
  const expected = crypto.createHmac('sha256', YOUR_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (signature.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.body.toString());

  // Dispatch based on event type
  switch (payload.type) {
    case 'session.created':
      console.log('New session:', payload.session_id);
      break;
    case 'session.started':
      console.log('Session started:', payload.session_id);
      break;
    case 'session.ended':
      console.log('Session ended:', payload.session_id);
      break;
    case 'recording.ready':
      console.log('Recording ready:', payload.session_id);
      break;
    case 'export.completed':
      console.log('Export completed:', payload.session_id);
      break;
  }

  res.status(200).send('OK');
});
```

### 2. Register the webhook with Synento

```bash
curl -X POST https://api.synento.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["session.created", "session.started", "session.ended"]
  }'
```

### 3. List your webhooks to verify

```bash
curl https://api.synento.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_xxxxx"
```

## Webhook Payload Structure

Each webhook event has the following structure:

```json
{
  "id": "<event-uuid>",
  "type": "session.started",
  "timestamp": "2025-01-01T12:00:00.000Z",
  "project_id": "<project-uuid>",
  "session_id": "<session-uuid>"
}
```

## Signature Verification

Every webhook includes an `X-Synento-Signature` header containing an HMAC-SHA256 digest of the raw request body, signed with your webhook's secret key.

Always verify this signature before processing — **never trust the payload without verification**.

The digest is lowercase hex. Compute it over the raw body bytes exactly as
they arrived — not over JSON you have parsed and re-serialised, which will not
match — and compare in constant time, as the receiver example above does.

## Event Delivery & Retry

Synento delivers each webhook with the following reliability guarantees:

| Aspect | Detail |
|--------|--------|
| Delivery model | Best-effort POST to your endpoint |
| Timeout | 5 seconds per attempt (AbortController) |
| Retry | A failed delivery (network error, timeout or non-2xx) is retried by a background job with exponential backoff, about 2 then 4 minutes apart. Pending retries are stored durably and survive a server restart. |
| Delivery log | Every attempt is recorded; see the Webhooks page in the dashboard |
| Ordering | Events for the same session are generally ordered but not guaranteed |

## Monitoring & Debugging

When testing locally:
1. Use ngrok or similar to expose your localhost endpoint
2. Register the public URL as the webhook target
3. Create a session and check your local logs for incoming webhooks

Once verified, switch to a stable production URL.

## Best Practices

1. **Always verify signatures** — unverified webhooks could be spoofed
2. **Respond quickly (200 OK)** — process the payload asynchronously; don't block on long operations
3. **Log all incoming events** — use logs to audit and debug event flows
4. **Handle idempotency** — if an event is delivered twice, your handler should handle it gracefully
5. **Use `session.started` + `session.ended`** — together they give you accurate session duration