# TRaX Developer Docs — full text



<!-- guides/api-philosophy -->


# Our API philosophy

TRaX is **API-first and community-friendly**. The platform is a set of
capabilities — studios, sources, destinations, going live, stream status,
platform connections, chat, and media — and we want you to build on all of it.
Apps, bots, dashboards, mobile controllers, full third-party "thick clients"
that produce a show without ever opening our web studio: that's the point, not a
side effect.

## Open-by-default

Our default posture is to **expose as much of the platform as we safely can**.
When we look at a capability and ask whether third-party developers should be
able to use it, we treat that as the wrong question. The only question we ask is:

> **Can we offer this safely?**

If a capability can be offered safely, the default answer is *yes, expose it.*
We don't hoard surface area, and we don't make you screen-scrape the web app to
do something the platform already knows how to do.

## What "safely" means

"Safely" isn't a vibe — it's a checklist, and it's the *only* thing we gate on:

- **Authenticated.** Every request carries an identity. You act as yourself
  using an API key you create, or your app acts on a user's behalf with their
  consent through OAuth.
- **Scoped.** A credential can do only what its scopes allow, and never more
  than you can already do yourself. A read-only key stays read-only.
- **Isolated to your tenant.** A credential can only touch resources that
  belong to it. It can never reach another account's studios, streams, or data.
- **Rate-limited.** Every credential has fair-use limits so one integration
  can't degrade the platform for everyone else.
- **Leak-free.** Our public surfaces never hand back another user's data or our
  internal plumbing.

Clear those, and we lean toward giving you the key.

## Where this is going

Today the media ingest plane (SRT, RTMP, WHIP/WHEP) is a real, documented
contract you can push and pull streams over — see the
[Reference](/reference/authentication) section. The control-plane
**[Developer API (`/v1`)](/reference/public-api)** is live in dev preview: list
your studios, read sources / destinations / live status, with **user-minted,
scoped API keys** as the first-class way to authenticate as yourself, and
go-live / go-offline plus stream-event webhooks close behind. Building a mobile
or desktop app? Start with **[Build a client](/guides/build-a-client)**.

Want to build something specific? Tell us — the roadmap follows what the
community wants to build.


<!-- guides/getting-started -->


# Getting started with TRaX

TRaX is a browser-based live production platform: an OBS-style scene canvas in the
browser, multi-host shows, and simultaneous output to multiple destinations
(Twitch, YouTube, Kick, Facebook, and any custom RTMP endpoint). Under the studio
sits a media ingest plane that accepts and serves standard streaming protocols:

| Direction | Protocols |
|---|---|
| Push a feed into TRaX | SRT, RTMP / RTMPS, WHIP (WebRTC) |
| Pull a feed out of TRaX | WHEP (WebRTC), SRT |

These protocol contracts are documented in the [Reference](/reference/authentication)
section and are usable today with credentials provisioned for you by the TRaX team.

## Building an app or integration?

Two dedicated guides cover programmatic access:

- **[Developer API (`/v1`)](/reference/public-api)** — a live, versioned REST +
  JSON API (dev preview at `api-dev.traxstreaming.live/v1`): list your studios,
  read sources / destinations / stream status, with an OpenAPI spec you can
  generate a typed client from. Authenticated with a `sk_live_…` API key you
  mint yourself.
- **[Build a client](/guides/build-a-client)** — for iOS / Android / desktop
  apps: the transport map (WebSocket to control a studio, WebRTC to publish and
  watch, REST for reads) and how a native app logs a user in with OAuth PKCE.
- **[Put TRaX chat on your own site](/guides/embed-chat)** — a drop-in
  `<trax-chat>` element that shows the broadcast's merged Twitch / YouTube / Kick
  chat to *your* members, on *your* domain, with no TRaX account for them and no
  API key in the browser.
- **[Control the mixer from your app](/guides/control-the-mixer)** — read a
  studio’s audio mix and mute or set a level on any source, through the same
  control path the studio’s own mixer uses. Development only today.
- **[Control the canvas over /v1](/guides/control-the-canvas)** — read a
  studio’s whole canvas in one call, move a tile, pick a preset or recall a
  scene, and hand the arrangement back to the auto planner. Built for a phone:
  conditional reads, small bodies, and writes that are safe to retry.
  Development only today.
- **[Stream to a live input from your app](/guides/stream-to-a-live-input)** —
  create an input over `/v1`, read its SRT / RTMP publish URL, and point an
  encoder at it. Development only today.

## Media authentication

Access to the TRaX **media plane** is authenticated per transport. Browser
publishing and playback (WHIP / WHEP) use short-lived **ES256 session JWTs**
minted by the platform (our identity provider is OIDC-based). Publishing to an
input over **SRT or RTMP** uses the input's **stream key**, carried inside the
publish URL the platform hands you.

What that means for pushing and pulling media:

- You can push to an input **today**: create it over `/v1` and read its publish
  URL ([Stream to a live input](/guides/stream-to-a-live-input), dev only), or
  copy the URL from the studio's Connection Information panel.
- You can verify any TRaX-issued token yourself against our published JWKS — see
  [Authentication & session tokens](/reference/authentication).
- A first-party app logs the user in with OAuth (PKCE) and uses that user token
  across the control and media planes — see [Build a client](/guides/build-a-client).

## Where to go next

1. [Authentication & session tokens](/reference/authentication) — how every request
   is authorized, token claims, JWKS verification.
2. [SRT: the streamid contract](/reference/srt-streamid) — the most robust way to
   push a feed.
3. [RTMP / RTMPS](/reference/rtmp) — the most compatible way.
4. [WHIP / WHEP](/reference/whip-whep) — browser-native, sub-second latency.
5. [Push a feed with OBS or ffmpeg](/guides/obs-ffmpeg-quickstart) — a 10-minute
   end-to-end win; [Stream to a live input](/guides/stream-to-a-live-input) is
   the same thing driven from your own code.
6. [Bring your own storage](/guides/byo-storage-setup) — use your own
   S3-compatible bucket as a media library and record your program straight
   into it ([cloud recording](/guides/cloud-recording)).


<!-- guides/build-a-client -->


# Build a client (iOS, Android, desktop)

TRaX is built to be driven by your own code — including full third-party
"thick clients" that produce a show without ever opening our web studio. A rich
client doesn't speak one protocol; it speaks **several, one per job**. This
guide is the map: which transport for which task, and how to authenticate each.

## The two authentication models — pick by who you are

Before anything else, decide *who your code acts as*:

| You're building… | Authenticate as | Credential |
|---|---|---|
| A **first-party app a user logs into** (mobile / desktop that produces or controls a show) | **the user** | OAuth 2.0 (PKCE) → user access token (JWT), sent as `Authorization: Bearer <jwt>` |
| **Server-to-server automation / a third-party integration** (dashboards, bots, headless jobs) | **yourself** (the developer) | an API key: `Authorization: Bearer sk_live_…` on the [`/v1` REST API](/reference/public-api) |

These aren't mutually exclusive — a mobile app might log the user in with OAuth
for live control *and* call `/v1` with the user's token for reads — but the
question "am I logging a **user** in, or running **my own** automation?" decides
your primary path.

## Transport map — which API for which job

| I want to… | Transport | How | Auth |
|---|---|---|---|
| **Control a studio** + receive live state (scenes, sources, go-live, presence, chat control) | **WebSocket** | connect to the studio control plane (below) | user bearer |
| **Publish** camera / mic / screen from the app | **WebRTC WHIP** | POST an SDP offer to the studio's WHIP endpoint — see [WHIP / WHEP](/reference/whip-whep) | media session token (Bearer) |
| **Publish** a hardware / OBS / camera feed | **SRT** or **RTMP(S)** | [SRT streamid](/reference/srt-streamid) · [RTMP](/reference/rtmp) | the input's stream key, inside the publish URL |
| **Stream to a live input** the app created itself | **SRT** or **RTMP(S)** | `POST …/sources` then `POST …/sources/{sourceId}/ingest` for the URL — see [Stream to a live input](/guides/stream-to-a-live-input) *(dev only today)* | `sk_live_` key (`sources:write` + `sources:ingest`) to provision, stream key in the URL to publish |
| **Contribute a phone camera** into a studio as a participant | **SRT** | provision an ingest, then publish — see [Contribute from a phone](/guides/contribute-from-a-phone) | user bearer to provision, scoped stream key in streamid to publish |
| **Watch** the program output (confidence monitor) | **WebRTC WHEP** | mint a read token + URL, then play — see [Monitor the program output](/guides/monitor-the-program) | media read token (Bearer) |
| **Watch** the program or a source preview — **now** | **WebRTC WHEP** | POST an SDP offer to the WHEP endpoint — see [WHIP / WHEP](/reference/whip-whep) | media read token (Bearer) |
| **Watch** at lowest latency — **later** | **MoQ** *(roadmap)* | not shipped yet; use WHEP today | — |
| **List / read** studios, sources, destinations, stream status; **go live / offline** | **REST `/v1`** | the [Developer API](/reference/public-api) | `sk_live_` API key (or user bearer) |

**Rule of thumb for a thick client:** one **WebSocket** to control a studio and
stream its live state; **WebRTC** (WHIP up / WHEP down) for media; **REST**
(`/v1`) for headless reads and automation. Stream **paths** (the `studios/{id}/…`
names you publish and play) follow one grammar — see [Stream paths](/reference/path-grammar).

## Native-app authentication — OAuth 2.0 with PKCE

A first-party app logs the user in against the TRaX identity provider using the
**Authorization Code flow with PKCE** (the standard, secret-less flow for native
and single-page apps). You get back a **user access token (JWT)** and a refresh
token; the access token is what every TRaX surface accepts as
`Authorization: Bearer <jwt>`.

**Identity provider (dev):** `https://auth-dev.traxstreaming.live`

| Purpose | Endpoint |
|---|---|
| Authorize | `https://auth-dev.traxstreaming.live/oauth/v2/authorize` |
| Token | `https://auth-dev.traxstreaming.live/oauth/v2/token` |
| End session (logout) | `https://auth-dev.traxstreaming.live/oidc/v1/end_session` |

Scopes: `openid profile email`. You'll register your app (to get a **client id**
and your allowed **redirect URIs**) with the TRaX team — contact us for a
native app registration.

**The flow:**

1. **Generate a PKCE pair.** Create a random `code_verifier`, then
   `code_challenge = BASE64URL(SHA256(code_verifier))`.
2. **Open the authorize URL** in a system browser / `ASWebAuthenticationSession`
   (iOS) / Custom Tab (Android) — not an embedded webview:

   ```
   https://auth-dev.traxstreaming.live/oauth/v2/authorize
     ?response_type=code
     &client_id=<your-client-id>
     &redirect_uri=<your-redirect-uri>
     &scope=openid%20profile%20email
     &code_challenge=<challenge>
     &code_challenge_method=S256
   ```

   Use a **custom URI scheme** (`com.yourapp://callback`) or a loopback
   redirect for the native round-trip.
3. **Handle the redirect** — you receive `?code=<authorization_code>`.
4. **Exchange the code for tokens** (no client secret — PKCE stands in for it):

   ```bash
   curl -sS https://auth-dev.traxstreaming.live/oauth/v2/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d grant_type=authorization_code \
     -d client_id=<your-client-id> \
     -d code=<authorization_code> \
     -d redirect_uri=<your-redirect-uri> \
     -d code_verifier=<code_verifier>
   ```

   The response includes `access_token` (a JWT), `refresh_token`, and
   `expires_in`. Store them in the platform keystore (iOS Keychain / Android
   Keystore), and use `grant_type=refresh_token` with the same `client_id` to
   get a fresh access token before it expires.

Send the resulting access token as `Authorization: Bearer <jwt>` on the
WebSocket upgrade, on WebRTC WHIP/WHEP signaling, and on `/v1` REST calls.

> This is the same OAuth-PKCE pattern this docs site itself uses to log in — a
> native app differs only in the redirect (custom scheme / loopback instead of a
> web `/callback` page) and in storing tokens in the OS keystore.

### Native vs. browser: the header advantage

A **native app can set request headers everywhere**, which keeps auth uniform:

- **WebSocket** — set `Authorization: Bearer <jwt>` on the upgrade request.
  (Browsers can't set headers on a WebSocket handshake, so the web client has to
  fall back to passing the token another way — a native app has no such limit
  and should use the header.)
- **WebRTC WHIP / WHEP** — set `Authorization: Bearer <token>` on the signaling
  `POST`.
- **REST `/v1`** — `Authorization: Bearer …` as usual.

Preferring the header on native keeps the token out of URLs and logs.

## Controlling a studio (WebSocket)

Real-time studio control — scenes, sources, going live, presence, chat control,
and the live state stream back to your UI — runs over a **WebSocket** to the
studio control plane:

```
wss://studio-api-dev.traxstreaming.live/api/v1/ws/studios/{studioId}/events
```

Open it with the user's bearer token (header, or a `?token=<jwt>` query param
where headers are impossible); the server resolves the user's access to that
studio once at upgrade, then gates each operation by role. This socket is
version-gated — add a `?client=<epoch-seconds>` build stamp to the connect URL
(or send it as an `X-Trax-Client` header). Frames are JSON — request/reply RPCs
plus server-pushed realtime events.

For a concrete walkthrough — connecting, seeding the source list + layout, and
the RPCs that add / move / activate sources and switch presets and scenes — see
[Drive the studio canvas](/guides/drive-the-canvas).

The **full RPC + event catalog** for this surface is first-party/internal
today. If you're a logged-in first-party developer, see the internal reference
for the exhaustive method and event lists (WS RPCs, WS events, and the private
transport map). Third-party apps reach the platform through the public `/v1`
REST gateway and this WebSocket — never internal service endpoints directly.

## Where to go next

1. [Developer API (`/v1`)](/reference/public-api) — REST reference, endpoint
   table, API keys, and OpenAPI client generation.
2. [Authentication & session tokens](/reference/authentication) — token claims
   and how to verify a TRaX-issued token against our JWKS.
3. [WHIP / WHEP](/reference/whip-whep) — publish and play media over WebRTC.
4. [SRT streamid](/reference/srt-streamid) · [RTMP / RTMPS](/reference/rtmp) —
   push a hardware or OBS feed.
5. [Contribute from a phone](/guides/contribute-from-a-phone) — join a studio as
   a camera source over SRT, with reconnection and QR walk-up guests.
   [Stream to a live input](/guides/stream-to-a-live-input) — the `/v1` path
   for an app that creates its own input and publishes to it with an API key.
6. [Drive the studio canvas](/guides/drive-the-canvas) — control layout, sources,
   presets, and scenes over the studio WebSocket.
7. [Monitor the program output](/guides/monitor-the-program) — play the studio's
   program feed over WHEP as a confidence monitor.
8. [Stream paths](/reference/path-grammar) — the `studios/{id}/…` path grammar
   shared by every media transport.

Tell us what you're building — the roadmap follows what the community wants to
ship.


<!-- guides/obs-ffmpeg-quickstart -->


# Quickstart: push a feed to TRaX with OBS or ffmpeg

Ten minutes from an input to a live feed. You need one thing: the input's
**publish URL**, which carries the host, the stream path and the stream key in
one string. Two places hand it to you:

- **From your own code:** create a `generic-input` source and call
  `POST /v1/studios/{id}/sources/{sourceId}/ingest`. The full walk-through,
  including the response shape, is [Stream to a live input from your app](/guides/stream-to-a-live-input).
- **From the studio:** open the input's **Connection Information** panel. It
  shows the same URLs, already split into the Server / Stream Key pair OBS wants.

Either way the credential is the input's **stream key**. It appears twice in an
SRT streamid and twice in an RTMP query string, and it is the whole capability;
there is no token to add. Treat the full URL as a password.

## Option A — SRT (recommended)

### ffmpeg

```bash
ffmpeg -re -i input.mp4 -c:v libx264 -preset veryfast -b:v 4M \
  -c:a aac -b:a 160k -f mpegts \
  "srt://<trax-media-host>:8890?streamid=publish:<path>:<key>:<key>"
```

### OBS

1. Settings → Stream → Service: **Custom…**
2. Server:
   `srt://<trax-media-host>:8890?streamid=publish:<path>:<key>:<key>`
3. Stream Key: leave **empty** (everything rides in the streamid)

Do not URL-encode the streamid, and keep it under 512 bytes; see the
[SRT contract](/reference/srt-streamid) for the failure modes.

## Option B — RTMP / RTMPS

### ffmpeg

```bash
ffmpeg -re -i input.mp4 -c:v libx264 -preset veryfast -b:v 4M \
  -c:a aac -b:a 160k -f flv \
  "rtmp://<trax-media-host>:1935/<path>?user=<key>&pass=<key>"
```

### OBS

OBS publishes to `<Server>/<Stream Key>`, so the URL splits at its last `/`:

1. Settings → Stream → Service: **Custom…**
2. Server: `rtmp://<trax-media-host>:1935/inputs`
3. Stream Key: `<last path segment>?user=<key>&pass=<key>`

Credentials ride in the **query string**, not in a `/live/<key>` path and not in
the URL's userinfo (`rtmp://user:pass@host/…` is not read and fails). For RTMPS
use port 1936 and the `rtmps://` scheme; plain RTMP sends the key in clear
text. See the [RTMP contract](/reference/rtmp).

## Verify it's flowing

The input's tile in the studio's Sources panel goes live within a few seconds
of the first packets, and back to offline within about five seconds of the
encoder stopping. A healthy SRT contribution holds a stable round-trip and no
reconnect churn; if the sender dies within the first second, check the
streamid rules first.

Publishing does not take the studio on air. A live input is something the
operator places on the canvas; going live to destinations is a separate step
([details](/guides/stream-to-a-live-input#what-you-will-see-in-the-studio)).

## Recommended encoder settings

| Setting | Value |
|---|---|
| Video codec | H.264, high profile |
| Keyframe interval | 2 s |
| Rate control | CBR, 4–8 Mbps for 1080p60 |
| Audio | AAC 160 kbps, 48 kHz stereo |


<!-- guides/contribute-from-a-phone -->


# Contribute a camera from a phone (SRT)

A phone can join a TRaX studio as a **camera source** and publish its camera and
mic over **SRT**. The phone is not compositing anything — the cloud encoder owns
the live program, so the show keeps running even if the app backgrounds, the
screen locks, or the signal drops for a moment. This is the ingest path the TRaX
iOS app uses, and it is open to your own client.

The model in one sentence: **a contributing phone is a participant whose device
source has `transport = srt`.** Media rides SRT; identity and control ride the
studio WebSocket. You reuse everything the platform already does with
participants — the person grouping, the mixer strip, the canvas tile, mute and
kick — instead of inventing a new kind of source.

> **There are now two ways to do this, and this is the older one.**
> [Go live from a phone over `/v1`](/guides/go-live-from-a-phone) provisions the
> same input and hands back the same SRT credential in ONE call on the public
> API, authenticated with an `sk_live_` key or an OIDC bearer like everything
> else in `/v1`. It is the same server-side path — the same source row, the same
> canvas tile, the same reconnection behaviour — so the two are
> interchangeable rather than parallel implementations.
>
> Prefer `/v1` for a new client. Stay here when you also need the studio
> WebSocket for identity and control, or the walk-up QR guest flow, neither of
> which `/v1` carries.

## What you talk to

Contribution is a first-party flow on the **studio control plane** (the studio
API), not the `/v1` REST gateway. Three hosts are involved:

| | Development | Production |
|---|---|---|
| Studio API (control plane) | `https://studio-api-dev.traxstreaming.live` | `https://studio-api.traxstreaming.live` |
| Identity (OAuth login) | `https://auth-dev.traxstreaming.live` | `https://auth.traxstreaming.live` |
| SRT ingest | `srt://ingest.traxstreaming.live:8890` | `srt://ingest.traxstreaming.live:8890` |

Always publish to the exact `srtIngestUrl` the provisioning response hands you
rather than hardcoding the ingest host.

## Authenticate as the user

Every call below carries the user's access token: `Authorization: Bearer <jwt>`,
the OAuth 2.0 + PKCE token described in [Build a client](/guides/build-a-client#native-app-authentication--oauth-20-with-pkce).
It is the same bearer you use for the studio WebSocket and for `/v1`. The one
exception is the walk-up QR guest path, which uses a scoped greenroom session
instead of an account (see [Walk-up guests](#walk-up-guests-qr) below).

## 1. Provision an SRT ingest

Ask the studio for a scoped ingest, identifying the device that is about to
publish:

```
POST /api/v1/studios/{studioId}/contribute/ingest
Authorization: Bearer <jwt>
Content-Type: application/json

{ "deviceId": "9C1B...stable-per-install-id", "deviceLabel": "EJ's iPhone" }
```

- **`deviceId`** (required) is a stable id your app mints once and keeps in the
  Keychain / Keystore. It is what makes a reconnection resolve to the *same*
  camera tile instead of a new one.
- **`deviceLabel`** is the human name shown in the studio ("EJ's iPhone").

You must be a member of the studio (any role). If contribution is not enabled
for the studio, the endpoint returns `404`.

The `201` response is the descriptor you publish with:

```json
{
  "source": { "id": "mc-…", "name": "EJ's iPhone", "type": "mobile_contrib", "…": "…" },
  "path": "inputs/mobile-contrib-mc-8f3c…",
  "streamId": "publish:inputs/mobile-contrib-mc-8f3c…:<streamKey>:<streamKey>",
  "srtIngestUrl": "srt://ingest.traxstreaming.live:8890?streamid=publish:inputs/mobile-contrib-mc-8f3c…:<streamKey>:<streamKey>",
  "autoSeat": true,
  "autoGoLive": true,
  "deviceId": "9C1B…"
}
```

| Field | What it is |
|---|---|
| `srtIngestUrl` | The full SRT URL to publish to — streamid included. Use it verbatim. |
| `streamId` | The SRT `streamid` on its own, if your SRT stack takes host and streamid separately. |
| `path` | The stream path this contribution lives at (`inputs/mobile-contrib-<id>`). |
| `autoSeat` | Whether the source auto-seats on the canvas when it starts publishing (see below). |
| `autoGoLive` | Deprecated alias of `autoSeat` — same value, removed in a future release. Read `autoSeat`. |
| `source` | The participant device source the feed is bound to — it appears in the studio's Sources immediately, offline until SRT flows. |

## 2. Publish over SRT

Open an SRT publisher (`libsrt` on iOS/Android, or `ffmpeg` from a workstation)
to `srtIngestUrl`. The credential is entirely inside the streamid:

```
publish:<path>:<streamKey>:<streamKey>
```

The whole capability is the scoped per-path **stream key** — user and password
positions are both the key. There is **no JWT in the streamid**, which keeps it
well under libsrt's 512-byte cap. Do not URL-encode the streamid; libsrt wants
the literal colons. See [SRT: the streamid contract](/reference/srt-streamid)
for the field grammar and the failure modes.

`ffmpeg` sanity check from a laptop:

```bash
ffmpeg -re -i camera.mp4 -c:v libx264 -c:a aac -f mpegts \
  "srt://ingest.traxstreaming.live:8890?streamid=publish:inputs/mobile-contrib-mc-8f3c…:<streamKey>:<streamKey>"
```

## What happens on the studio side

- The feed **auto-seats as a participant device source** under the contributing
  person, inheriting their name, avatar, and color. No host click is needed.
- The **cloud encoder is the authority.** If the phone backgrounds or loses
  signal, the source goes offline and the program falls back to a slate; when
  the phone comes back it re-seats the same tile. The broadcast itself never
  depended on the phone.
- **`autoSeat` seats the source, it does not start the broadcast.** Bringing a
  camera onto the canvas is separate from going live to your destinations. The
  studio's master go-live control stays authoritative — a contributing phone can
  never force the program on air.

## Reconnection and the device registry

Each phone is a durable device, not a per-connection source. List a user's
devices and their history:

```
GET /api/v1/contribute/devices
Authorization: Bearer <jwt>

→ 200 { "devices": [ { "deviceId": "9C1B…", "label": "EJ's iPhone",
                       "lastSeenAt": "…", "connectionCount": 12, "…": "…" } ] }
```

Because the source id is derived from the studio plus the durable device, the
same `deviceId` reconnecting into the same studio re-provisions the **same
path** and re-seats the **same tile** — layout and position survive drops and
app restarts.

## 3. Release the input when you're done

When the phone is finished contributing, hand its input back to the studio:

```
DELETE /v1/studios/{studioId}/contribute
Authorization: Bearer <token>
Content-Type: application/json

{ "deviceId": "9C1B…" }
```

→ **204 No Content**

This is the teardown twin of the provision call. It stops the cloud encoder
from re-arming a pull against a path the phone is no longer publishing to. Call
it from `applicationWillTerminate` (or your platform's equivalent) so a clean
exit gives the session back instead of leaving it to time out.

**Keep-source.** Release **deactivates** the input; it does not delete it. The
source row, its media path, and its **canvas placement survive**, so a later
provision with the **same `deviceId`** re-seats the **same tile** exactly like a
reconnection does. Use `DELETE /v1/studios/{studioId}/sources/{sourceId}` when
you actually want the input removed from the studio.

**Safe from a background teardown.** The call answers **204 on everything that
is merely "nothing to do"** — an unknown `deviceId`, one already released, one
that never published, or an empty body. A shutting-down app has no screen to
show an error on and no chance to retry, so a teardown never fails on request
framing it cannot fix. The only answers you must not ignore are **403** (the
`deviceId` belongs to another user), **401** (no auth), and **5xx** (the release
genuinely did not happen).

Unlike provisioning, release is **not** gated by the deployment's contribute
switch: that flag stops new sessions being created, but a session that already
exists must always be releasable.

## Walk-up guests (QR)

A host can let someone contribute without an account. The host mints a
short-lived join code (admin role required):

```
POST /api/v1/studios/{studioId}/contribute/qr
Authorization: Bearer <jwt>

→ 201 {
  "studioId": "…",
  "token": "…",
  "deepLink": "traxstreaming://contribute?studio=…&token=…",
  "joinUrl": "https://studio-api.traxstreaming.live/m/contribute?studio=…&token=…",
  "expiresAt": "2026-08-11T20:15:00Z"
}
```

Render the `token` (or the deep link) as a QR code. The token is the only way
in — there is no enumeration — and it expires in 15 minutes with a small use
cap; re-mint to rotate. A guest scans it, enters a name, and their app
provisions an ingest against the greenroom session:

```
POST /api/v1/greenroom/contribute/ingest
Content-Type: application/json
Cookie: <greenroom session established by the join token>

{ "deviceId": "…", "deviceLabel": "Guest — Sam" }
```

The response is the same SRT descriptor as the authenticated path, and the guest
auto-seats as a participant device source. Guest ingests are rate-limited, and
the guest is kickable and forgotten on leave.

## Control the studio while you publish

Contribution is only the camera leg. The same app holds a **WebSocket** to the
studio for tally ("you're live"), mute, flip-camera, and stop — bidirectional
control that has nothing to do with the media plane. That surface, and how to
authenticate it, is in [Build a client → Controlling a studio](/guides/build-a-client#controlling-a-studio-websocket).

## Where to go next

1. [Build a client](/guides/build-a-client) — the transport map, native OAuth +
   PKCE, and the studio-control WebSocket.
2. [Stream to a live input](/guides/stream-to-a-live-input) — the `/v1` path
   when the feed should be a plain input rather than a participant, driven by
   an API key instead of a user login.
2. [Drive the studio canvas](/guides/drive-the-canvas) — control layout, sources,
   presets, and scenes over the studio WebSocket while you publish.
3. [Monitor the program output](/guides/monitor-the-program) — watch the
   composited program feed over WHEP.
4. [SRT: the streamid contract](/reference/srt-streamid) — the streamid grammar,
   the 512-byte cap, and how publishes fail.
3. [Stream paths](/reference/path-grammar) — the path grammar shared by every
   media transport.
4. [Authentication & session tokens](/reference/authentication) — the user-login
   (OIDC + PKCE) and media-token models in full.


<!-- guides/go-live-from-a-phone -->


# Go live from a phone over /v1

A phone is the hardest client this API has. It gets used in a car park, on a
rooftop, in a basement, at a festival where forty thousand other people are also
holding phones. It is also the client with the least room to be clever: it has
one radio, a battery, and a user who is about to point it at something that only
happens once.

So this guide is short on purpose. **Two calls put a phone on air**, and both of
them are built to survive a bad link:

1. **`POST /v1/studios/{id}/contribute`** — provisions this device's input on the
   studio and hands back the credential to publish into it, in one round trip.
2. **`POST /v1/studios/{id}/monitor`** — the return feed, so whoever is holding
   the camera can see what the show is actually sending.

The first one is the one that matters. If it succeeds you can push video; if it
fails there is no stream, and nothing else on this API changes that.

> **Which host.** `https://api.traxstreaming.live/v1` with a production key, or
> `https://api-dev.traxstreaming.live/v1` with a dev key. Only the host differs.

## Before you start

- An API key holding **`sources:ingest`**, **`sources:write`** and
  **`viewer:tokens`**. Create it under **Developer → API keys**, or use the
  user's own OIDC bearer if your app signs people in — see
  [Build a client](/guides/build-a-client#native-app-authentication--oauth-20-with-pkce).
  Add **`sources:read`** and **`studios:read`** if you also want to poll (you
  do; see [Polling on cellular](#polling-on-cellular)).
- The **studio id** the phone is joining.
- A **device id** your app mints once. Read the next section before you pick one.

### Why contribute needs three scopes

Each one is a different power, and none of them implies another:

| Scope | What it lets this call do |
|---|---|
| `sources:write` | Create an input on the studio |
| `sources:ingest` | Hand back a live publish credential for it |
| `viewer:tokens` | Mint the return feed (monitor only) |

`sources:write` reconfigures what a studio listens for. `sources:ingest` occupies
the wire and puts pixels on the broadcaster's program. Those are different enough
that holding one has never granted the other, and `POST /contribute` genuinely
does both, so it asks for both.

The monitor's scope surprises people, so here is the reasoning rather than just
the rule. It is **`viewer:tokens`**, not `stream:read`. `stream:read` is a
*default* scope — every key created without an explicit list carries it forever —
and this endpoint hands back a credential that **plays the program**. That is not
a power a key should acquire by not thinking about it. `viewer:tokens` is the
scope this platform already uses for minting media playback credentials, it is
opt-in by name, and a key holding it can already mint a `video.play` token for
the same studio through `POST /v1/viewer-tokens`. Requiring it here therefore
grants nothing your key could not already do — it just refuses to give the
program feed away to a key that never asked for it.

## The device id is the whole design

`deviceId` is a value **your app mints once and keeps in the Keychain (iOS) or
Keystore (Android)**. It is opaque to TRaX and never resolved to a person: send
an identifier for the *device*, not for whoever is holding it.

It is also the **idempotency key**, and that is what makes everything else in
this guide safe. The same `deviceId` always resolves to the same input on the
same studio — the same media path, the same credential, the same canvas tile.

That has two consequences worth internalising:

- **A phone that reconnects lands back on its own tile.** The operator's layout
  survives a lift ride.
- **A `deviceId` your app regenerates each launch produces a new input each
  launch.** The operator watches their source list fill up with duplicates of one
  phone, and nothing in the API will stop you: from the server's side, a new
  device id *is* a new device.

Mint it once. Persist it. Never derive it from something that changes — not the
session, not the login, not the network.

## Step 1 — put the phone on the studio

```bash
curl -sS https://api.traxstreaming.live/v1/studios/$STUDIO/contribute \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deviceId": "5C1B9E77-...-KEYCHAIN", "deviceLabel": "EJ'\''s iPhone" }'
```

```json
HTTP/1.1 201 Created
{
  "sourceId": "mc-9f21c4a7e0b3d6...",
  "streamName": "inputs/mobile-contrib-mc-9f21c4a7e0b3d6...",
  "deviceId": "5C1B9E77-...-KEYCHAIN",
  "autoSeat": true,
  "ingest": {
    "srt": {
      "complete": "srt://ingest.traxstreaming.live:8890?streamid=publish:inputs/mobile-contrib-mc-9f21...:sk_stream_...:sk_stream_...&latency=200",
      "base": "srt://ingest.traxstreaming.live:8890"
    }
  },
  "granted": ["srt"],
  "streamKey": "sk_stream_...",
  "srtStreamId": "publish:inputs/mobile-contrib-mc-9f21...:sk_stream_...:sk_stream_...",
  "ingestHost": "ingest.traxstreaming.live",
  "ingestMetro": "auto"
}
```

Dial `ingest.srt.complete` **verbatim**. Do not rebuild it from `base` +
`streamKey`: the credential form is the server's to decide and it has changed
before, and a client that reassembles the URL from a remembered shape keeps
sending the old one long after the server moved on.

Everything in that response except `sourceId`, `streamName`, `deviceId` and
`ingestHost` is a live publish credential. Keychain, not log line, not analytics
event, not a crash report.

### `201` the first time, `200` every time after

Send the same `deviceId` again and you get `200` with the **same** `sourceId`,
the **same** `streamKey`, the **same** URLs. Nothing is created and nothing is
rotated.

That is the contract this whole guide rests on. **Retrying is safe, including
after a timeout where you never saw the response.** Nothing on this path rotates
a credential, so a retry cannot invalidate the key the timed-out attempt already
issued.

`created` is deliberately not in the body — the status code already says it, and
two answers to one question is how a client ends up trusting the wrong one.

If you want to *deliberately* invalidate a credential — it got pasted into a
support chat, the phone walked off — that is
`POST /v1/studios/{id}/sources/{sourceId}/ingest/rotate`, by name, on purpose.
See [Stream to a live input](/guides/stream-to-a-live-input#rotate-the-key).

### `autoSeat`

`autoSeat: true` means this input takes a seat on the canvas by itself **when the
studio is already live**. It never starts the broadcast — going live is the
operator's call and nothing on this path can make it happen. Read it to tell your
user what to expect when they hit publish: a tile that appears on air, or a
source the operator still has to place.

### `ingestHost` and `ingestMetro`

`ingestHost` is there so you can show *"publishing to ingest.traxstreaming.live"*
without parsing — or displaying — a string that is also a secret.

`ingestMetro` is `"auto"`, and that is a measurement rather than a placeholder.
Nearest-point-of-presence selection happens **in DNS**, when your device resolves
the ingest hostname — not when this call mints the URL. The server genuinely does
not know which PoP you will reach, and guessing from your IP address would be
wrong for every VPN, every carrier-grade NAT and most mobile subscribers, which
is exactly the population this endpoint exists for.

**Display it; do not branch on it.** A later release may name a real metro here,
and a client that special-cased the string would break on the improvement.

### Asking for RTMP

Send `protocols` to get more than the SRT default:

```json
{ "deviceId": "...", "protocols": ["srt", "rtmp"] }
```

`protocols` is a **request, not a guarantee**. Read `granted` off the response
and configure from that. Ask for exactly what you will dial — every extra entry
is another copy of the same live secret sitting in your app's memory, logs and
crash reports.

SRT is the right default for a phone. It recovers from packet loss without
retransmitting the whole world, which is what a cellular uplink does to you.

## Step 2 — the return feed

```bash
curl -sS -X POST https://api.traxstreaming.live/v1/studios/$STUDIO/monitor \
  -H "Authorization: Bearer $TRAX_API_KEY"
```

No body required.

```json
HTTP/1.1 200 OK
{
  "whep": {
    "url": "https://media.traxstreaming.live/s/5b2e9d41-.../pp/whep",
    "token": "eyJhbGciOiJFUzI1NiIs..."
  },
  "srt": null,
  "streamName": "s/5b2e9d41-.../pp",
  "expiresAt": "2026-08-23T16:05:00Z"
}
```

POST your SDP offer to `whep.url` with `Authorization: Bearer <whep.token>`.
That token is **not** your API key and **not** the user's login token: it
authorises exactly this studio's program path, for a few minutes, and nothing
else — which is what makes it safe to put on a signaling request your API key has
no business appearing on.

**Take the WHEP path.** WebRTC degrades on a lossy cellular uplink far better
than anything else here: it drops frames and keeps going where a stricter
transport would stall.

### The expiry is not what you think

The credential lasts 300 seconds by default (900 maximum, clamped rather than
refused if you ask for more). That sounds impossibly short for a two-hour show.
It is not, because **the media server authorises a read once, at session
establishment, and never re-checks**. A monitor that is already playing keeps
playing long past `expiresAt`. You need a fresh mint to **(re)connect**, not to
keep watching.

So: mint when you open the monitor, mint again if it drops, and schedule from
`expiresAt` — never from the TTL you asked for, which may have been clamped.

### When `srt` is `null`

`srt` is an alternative for clients that cannot speak WHEP, and `null` is a real
answer rather than a missing field. The read credential rides **inside** SRT's
streamid, which libsrt caps at 512 bytes and rejects locally — before anything
reaches the network — when exceeded. When the composed URL would be over that
cap, or no SRT endpoint is configured, the server returns `null` instead of a URL
that cannot dial.

Handle it by falling back to WHEP, which is the path you should be on anyway.

### A black monitor is a state, not an error

The credential is always issued when you are allowed to hold it. Whether *frames*
flow depends on the studio being live with its program preview published. A
monitor opened off-air simply shows nothing yet. Render that; do not report it as
a failure.

## Building for a bad connection

Everything above is designed around the assumption that your requests will
sometimes not arrive. Here is what to do about it.

### Timeouts

**10 seconds** per request. Long enough to survive a slow radio handover, short
enough that a user staring at a spinner gets an answer rather than a hang.

Both endpoints here are single round trips by design, so a 10-second budget is a
real budget rather than an aspiration.

### Retries

Retry `contribute` freely. It is idempotent, it cannot double-provision, and it
cannot rotate the credential a previous attempt issued. Retry `monitor` freely
too — a spare monitor token costs nothing and expires on its own.

Back off exponentially with jitter: **1s, 2s, 4s, 8s**, capped, with a random
±30%. The jitter matters more than it looks. Phones at an event all lose signal
at the same moment and all come back at the same moment; without jitter they
retry in lockstep and turn one outage into two.

### Honour `Retry-After`

Two responses carry it, and both mean what they say:

- **429** — you are over the credential-mint budget (roughly 5 per minute per
  caller, with a small burst). Wait the interval; do not guess.
- **503 `unavailable`** — the studio service is briefly unreachable. Wait the
  interval and retry; this is the transient one.

One 503 does **not** carry `Retry-After`, on purpose:

- **503 `contribute_disabled`** — the device-contribute path is switched off on
  this deployment. There is no interval after which this succeeds. Surface it to
  the user; do not retry it.

Branch on `error.code`, never on the status alone. Two 503s that mean opposite
things is exactly why the codes exist.

### Polling on cellular

Poll **every 15–30 seconds**, not faster. The answer you are usually waiting for
— did my input come up, is the show live — is push-driven on the operator's side;
your poll is a fallback, and a fallback that runs every two seconds is just a
battery drain.

The three reads a phone polls support conditional requests:

- `GET /v1/studios/{id}/sources/{sourceId}` — *is my input publishing yet*
- `GET /v1/studios/{id}/sources` — *did my input show up*
- `GET /v1/studios/{id}/stream-status` — *is the show on air*

Each returns an `ETag`. Send it back as `If-None-Match` and an unchanged answer
costs you a **304 with no body**:

```bash
# First poll
curl -sS -D- https://api.traxstreaming.live/v1/studios/$STUDIO/sources/$SOURCE \
  -H "Authorization: Bearer $TRAX_API_KEY"
# → 200 OK
#   ETag: "kZ3n8Qw2r1vB7yTcXsLmPQ"

# Every poll after
curl -sS -D- https://api.traxstreaming.live/v1/studios/$STUDIO/sources/$SOURCE \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H 'If-None-Match: "kZ3n8Qw2r1vB7yTcXsLmPQ"'
# → 304 Not Modified   (no body)
```

Keep the last `ETag` per URL and send it every time. The tag changes the moment
the answer does, so a 304 means *nothing has happened*, and a 200 means
*something has* — which is precisely the signal you were polling for.

On a metered cellular link this is the difference between a poll that completes
and a poll that times out.

### What to do when you are offline

Nothing clever. A contributed input is **durable**: it survives your app being
killed, the phone rebooting, and the network going away entirely. When you come
back, call `contribute` with the same `deviceId` and you get your input back with
the same credential.

Do not cache the credential and skip the call — call it and let the `200` confirm
what you already had. It is one round trip and it is the only way to learn that
an operator deleted your input while you were away.

## What this guide does not cover

- **Going live.** Contributing a camera never starts a broadcast. That is
  `POST /v1/studios/{id}/go-live`, it needs `stream:golive`, and it is the
  operator's decision — see [Getting started](/guides/getting-started).
- **The audio mixer.** Your input arrives with a channel strip the operator can
  reach; you can too, with `audio:read` / `audio:write` — see
  [Control the mixer](/guides/control-the-mixer).
- **The first-party SRT flow on the studio control plane.** If you are building
  against the studio API rather than `/v1`, see
  [Contribute a camera from a phone](/guides/contribute-from-a-phone), which
  covers the participant model, the studio WebSocket and the QR walk-up flow.

## Reference

- [`POST /v1/studios/{id}/contribute`](/reference/api/v1#contribute)
- [`POST /v1/studios/{id}/monitor`](/reference/api/v1#mintprogrammonitor)
- [Stream to a live input from your app](/guides/stream-to-a-live-input) — the
  same credential shape, for an input you created yourself
- [Monitor the program output (WHEP)](/guides/monitor-the-program) — the WHEP
  playback details

## Stop polling: the events stream

Everything above is a request you make. This is the one you don't.

A phone that polls `listSources` and `stream-status` every four seconds and
`destinations` every eight is spending about **37 requests a minute** on this
API while it is also pushing video up the same cellular uplink. Those requests
compete with your own SRT stream for the scarce direction — and they do it
hardest exactly when the link is worst and you need the video most.

Open this instead, once:

```bash
curl -N -H "Authorization: Bearer $TRAX_API_KEY" \
  https://api.traxstreaming.live/v1/studios/$STUDIO_ID/events
```

```
: connected

id: 9f2c1a4b7e3d-0
event: snapshot
data: {"sources":[…],"streamStatus":{"live":false,…},"destinations":[…],"canvas":{…},"audio":{…},"chatConnectors":[…]}

id: 9f2c1a4b7e3d-1
event: source
data: {"id":"…","name":"Phone","publishing":true,"publishedAt":"2026-08-23T22:04:11Z",…}

: heartbeat 2026-08-23T22:04:26Z
```

**The first event is a `snapshot` of everything.** Opening this stream IS your
initial read — you do not need to GET anything to prime yourself.

**Every `data:` is the same JSON the equivalent GET returns.** A `source` event
is a `Source`, exactly as `listSources` gives you one. Apply an event by
replacing the row it names; there is no partial-update form to learn.

| `event` | what to do |
| --- | --- |
| `snapshot` | replace your whole model — sources, stream status, destinations, the canvas, the audio mixer, and every chat connector, all at once |
| `source` | replace (or insert) that source — this is where `publishing` flips |
| `streamStatus` | replace the stream status |
| `destination` | replace (or insert) that destination |
| `canvas` | replace your whole canvas — layout mode, active preset/scene, and every tile's placement (a `CanvasState`, the same shape `GET …/canvas` returns) |
| `audio` | replace your whole mixer — the master strip plus one strip per source (a `StudioAudio`, the same shape `GET …/audio` returns) |
| `chatConnector` | replace (or insert) that platform's chat connector — its reconnect-pill state (a `ChatConnector`) |
| `sourceRemoved` / `destinationRemoved` | drop the row named by `data.id` |
| `chatConnectorRemoved` | a platform was unlinked; drop the connector named by `data.platform` |

A `destination` event fires no matter where the change came from — a toggle in
the web studio, another phone, or a `/v1` call of your own. The same is true for
every row here: this stream is the studio's state, not your client's echo. The
`canvas` and `audio` events are whole-object replacements — reconcile each one
by swapping your entire canvas or mixer for what it carries, exactly as you do
for `snapshot`.

### Reconnecting

Cellular drops. That is the normal case, not the exception, and the stream is
built for it.

Keep the `id` of the last event you processed. On reconnect, send it back:

```bash
curl -N -H "Authorization: Bearer $TRAX_API_KEY" \
     -H "Last-Event-ID: 9f2c1a4b7e3d-1" \
  https://api.traxstreaming.live/v1/studios/$STUDIO_ID/events
```

The server replays what you missed. If it cannot honour the id — too old, or a
different server — it sends a fresh `snapshot` instead and carries on. **That is
not an error.** So always send your last id, never reason about whether it will
work, and never fall back to re-GETting the three collections. A browser's
`EventSource` sends this header for you; if you cannot set headers, use
`?lastEventId=`.

Treat the id as opaque. Do not parse it, do not compare two of them.

### Keepalives

Lines beginning with `:` are SSE comments, not events. On a quiet studio you
will see `: heartbeat <time>` about every fifteen seconds; that is what stops a
cellular NAT or a proxy from reaping a working-but-silent connection. A
standard `EventSource` ignores comments for you. If you wrote your own client,
use them to reset a dead-stream timer — and if the timer fires, reconnect with
your last id.

### Scopes and limits

Requires `stream:read`, `sources:read` and `destinations:read` — the same three
permissions the three reads it replaces require. No new scope: a key that could
already make those calls can open this stream today.

At most **5 concurrent event streams per credential** (a `429` with
`Retry-After` beyond that) and **32 watchers on one studio**. You need one.

The stream **ends when your access does** — if the studio is deleted or your key
is revoked it terminates rather than sitting open against something that is
gone. Reconnect on any disconnect; back off if you get a `429`.

### What to keep polling

Nothing. The canvas, the audio mixer and the chat connectors all ride this one
stream now — a phone that opens it never has to poll `…/canvas`, `…/audio` or
the connector list to stay current. And it costs no extra permission: the same
`stream:read`, `sources:read` and `destinations:read` that open the stream carry
every event on it.


<!-- guides/sdk-typescript -->


# SDK quickstart: TypeScript / JavaScript

Generate a typed client for the `/v1` Developer API from its OpenAPI spec and
make your first call. Works for Node and the browser (server-side for anything
holding an API key — never ship a secret key to a browser).

> No hand-written SDK is published yet — you generate one from the live spec.
> An official TypeScript SDK is a [roadmap](/reference/roadmap) item.

## 1. Get the spec

The live, machine-readable contract:

```
https://api-dev.traxstreaming.live/v1/openapi.json
```

## 2. Generate a typed client

Two good options — pick one.

**Option A — types + a tiny typed fetch wrapper** (recommended, lightweight):

```bash
npm i -D openapi-typescript
npm i openapi-fetch
npx openapi-typescript https://api-dev.traxstreaming.live/v1/openapi.json -o src/trax-api.d.ts
```

**Option B — a full generated client** (heavier, more ceremony):

```bash
npm i -D @openapitools/openapi-generator-cli
npx openapi-generator-cli generate \
  -i https://api-dev.traxstreaming.live/v1/openapi.json \
  -g typescript-fetch -o src/trax-client
```

## 3. Authenticate

Create an API key from your account's **Developer / API Keys** screen (copy the
`sk_live_…` secret once), and keep it server-side — an environment variable, not
in source:

```bash
export TRAX_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

## 4. First call

Using **openapi-fetch** with the generated types:

```ts
import createClient from 'openapi-fetch'
import type { paths } from './trax-api'

const trax = createClient<paths>({
  baseUrl: 'https://api-dev.traxstreaming.live',
  headers: { Authorization: `Bearer ${process.env.TRAX_API_KEY}` },
})

// List your studios (requires the studios:read scope)
const { data, error, response } = await trax.GET('/v1/studios', {
  params: { query: { limit: 50 } },
})

console.log('request id:', response.headers.get('X-Request-Id'))

if (error) {
  // One envelope for every error: { error: { code, message, requestId } }
  console.error(error.error.code, error.error.message)
} else {
  for (const studio of data.data) console.log(studio.id, studio.name)
  if (data.nextCursor) {
    // pass data.nextCursor as ?cursor= to page — see /reference/pagination
  }
}
```

Or with plain `fetch`, no codegen at all:

```ts
const res = await fetch('https://api-dev.traxstreaming.live/v1/studios?limit=50', {
  headers: { Authorization: `Bearer ${process.env.TRAX_API_KEY}` },
})
const body = await res.json()
if (!res.ok) throw new Error(body.error.code)   // 'invalid_key' | 'rate_limited' | …
console.log(body.data, body.nextCursor)
```

## Next

- [Pagination](/reference/pagination) — loop `nextCursor` to read a full list.
- [Errors](/reference/errors) — branch on `error.code`; retry only transient codes.
- [Rate limits](/reference/rate-limits) — honor `Retry-After` on `429`.
- [Build a client](/guides/build-a-client) — add real-time control (WebSocket)
  and media (WebRTC) for a full app; use OAuth when acting **as a user**.


<!-- guides/stream-to-a-live-input -->


# Stream to a live input from your app

Your app holds an `sk_live_` key and an encoder (a phone, a capture box, OBS on
a laptop). This guide takes you from that key to video arriving in a studio:
create an input, ask `/v1` where to publish, hand the URL to the encoder.

> **Which host.** Creating an input and reading its publish URLs are live in
> production: use `https://api.traxstreaming.live/v1` with a production key, or
> `https://api-dev.traxstreaming.live/v1` with a dev key. Only the host differs.
> [Rotating a key](#rotate-the-key) is the exception — that endpoint is on dev
> only for now; this page will say so when it reaches production.

Two calls, in order:

1. **`POST /v1/studios/{id}/sources`** with `type: "generic-input"` creates the
   input. It is a durable object in the studio; it exists whether or not anything
   is publishing to it.
2. **`POST /v1/studios/{id}/sources/{sourceId}/ingest`** returns the publish
   URLs for that input. Nothing is created; you are reading a credential that
   already exists.

The thing to internalise: **the input is the durable object and you point a
device at it.** Calling the second endpoint twice hands two devices the same
endpoint. It never makes a second input.

## Before you start

- An API key holding **`sources:write`** (to create the input) and
  **`sources:ingest`** (to read its publish URLs). `sources:ingest` is its own
  scope because the response is a live credential: `sources:write` does not
  imply it, and no default read set includes it. Create the key under
  **Developer → API keys** in your account.
- The **studio id** the input should live in.
- A studio on an account with an active subscription. Without one, creating the
  input returns `402 subscription_required`.

## Step 1 — create the input

```bash
curl -sS https://api.traxstreaming.live/v1/studios/$STUDIO/sources \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Field camera 1", "type": "generic-input" }'
```

```json
HTTP/1.1 201 Created
{
  "id": "8f3c2a10-6d1e-4b7a-9c0f-2e5d7a1b4c93",
  "studioId": "5b2e9d41-07c3-4f8a-b6e1-9a4d2c7f0e15",
  "name": "Field camera 1",
  "type": "generic-input",
  "active": false,
  "status": "OK"
}
```

Keep `id`. It is the `{sourceId}` for everything that follows, and it is stable
for the life of the input. The source appears in the studio's Sources panel
immediately, offline, waiting for media.

## Step 2 — get the publish URLs

```bash
curl -sS https://api.traxstreaming.live/v1/studios/$STUDIO/sources/$SOURCE/ingest \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "protocols": ["srt", "rtmp"] }'
```

The body is optional. Send nothing and you get `["srt"]`. Ask for exactly what
your encoder will dial: every extra protocol is another copy of the same secret
in your app's memory, logs and crash reports.

```json
HTTP/1.1 200 OK
{
  "streamName": "inputs/generic-input-8f3c2a10-6d1e-4b7a-9c0f-2e5d7a1b4c93",
  "ingestUrls": {
    "srt": {
      "complete": "srt://east01.ingest.traxstreaming.live:8890?streamid=publish:inputs/generic-input-8f3c2a10-…:<KEY>:<KEY>",
      "base": "srt://east01.ingest.traxstreaming.live:8890"
    },
    "rtmp": {
      "complete": "rtmp://east01.ingest.traxstreaming.live:1935/inputs/generic-input-8f3c2a10-…?user=<KEY>&pass=<KEY>",
      "base": "rtmp://east01.ingest.traxstreaming.live:1935/inputs/generic-input-8f3c2a10-…"
    }
  },
  "granted": ["srt", "rtmp"],
  "streamKey": "<KEY>"
}
```

`<KEY>` is the input's stream key. It is the entire credential: the same value
sits in both credential positions of the SRT streamid and in both RTMP query
parameters. There is no token to refresh and nothing else to mint.

| Field | What it is |
|---|---|
| `streamName` | The media path this input publishes to. The one field here that is safe to log; use it to correlate a device with what the studio shows. |
| `ingestUrls.<proto>.complete` | The URL to hand the encoder, credential included. **This is the secret.** Keychain, not log line, not analytics event. |
| `ingestUrls.<proto>.base` | The same endpoint with the credential removed. Safe to display. It does **not** authenticate on its own; never present it as something to publish to. |
| `granted` | The protocols you actually got. Configure from this list, never from what you asked for. |
| `streamKey` | The key on its own, for encoders whose UI has a separate key field. **Always present** — on a mint and on a rotate alike, and on a brand-new input as much as an established one. It adds no exposure beyond `complete`, which already contains it. |

### `granted` is the answer, not `protocols`

`srt`, `rtmp` and `rtmps` are the protocols that can be granted today. The
request also accepts `webrtc`, `rtsp` and `hls`, and none of them is ever
granted:

- `webrtc`: the WHIP URL for a plain input carries no publish credential, so it
  would fail at the handshake. Browser and WebRTC publishing use a different
  mechanism; see [WHIP / WHEP](/reference/whip-whep).
- `rtsp`: pull-only. The URL is a hint for an IP camera the platform dials out
  to, not a place a device publishes.
- `hls`: has no publish form.

Asking for one of those is not an error; it is simply absent from `granted` and
from `ingestUrls`. A name outside that list of six is a `400`, because a silently
dropped typo leaves a client waiting for an endpoint that is never coming.

### The URL shapes

Two forms, one credential. The [SRT](/reference/srt-streamid) and
[RTMP](/reference/rtmp) reference pages have the full grammar.

```
srt://<host>:8890?streamid=publish:<streamName>:<KEY>:<KEY>
rtmp://<host>:1935/<streamName>?user=<KEY>&pass=<KEY>
rtmps://<host>:1936/<streamName>?user=<KEY>&pass=<KEY>
```

RTMP credentials go in the **query string**. The older `rtmp://user:pass@host/…`
userinfo form is not read by the ingest server and fails authentication; if you
have it in a config file from before, replace it. An SRT `complete` URL may also
carry `&latency=…` and `&oheadbw=…` when the input has SRT tuning set in the
studio; pass the URL through unchanged and those apply.

## Step 3 — publish

Use the host the response gives you. Do not hardcode the ingest hostname; it is
the platform's to change.

### ffmpeg over SRT

```bash
ffmpeg -re -i camera.mp4 \
  -c:v libx264 -preset veryfast -b:v 4M -g 60 \
  -c:a aac -b:a 160k -f mpegts \
  "srt://east01.ingest.traxstreaming.live:8890?streamid=publish:inputs/generic-input-…:<KEY>:<KEY>"
```

Quote the URL. Do not percent-encode the streamid: the SRT library wants the
literal colons, and an encoded one fails authentication.

### OBS over SRT

1. Settings → Stream → Service: **Custom…**
2. Server: the SRT `complete` URL, whole.
3. Stream Key: leave **empty**. Everything rides in the streamid.

### libsrt on iOS / Android

Open a caller socket to `base` (`host:port`) and set `SRTO_STREAMID` to the
streamid portion of `complete`, the part after `streamid=`. It is
`publish:<streamName>:<KEY>:<KEY>` and must stay under libsrt's 512-byte cap,
which it does by a wide margin: the key replaces what used to be a token.

### ffmpeg over RTMP

```bash
ffmpeg -re -i camera.mp4 \
  -c:v libx264 -preset veryfast -b:v 4M -g 60 \
  -c:a aac -b:a 160k -f flv \
  "rtmp://east01.ingest.traxstreaming.live:1935/inputs/generic-input-…?user=<KEY>&pass=<KEY>"
```

### OBS over RTMP / RTMPS

OBS publishes to `<Server>/<Stream Key>`, so split the `complete` URL at its
last `/`. This is the same split the studio's own Connection Information panel
shows:

1. Settings → Stream → Service: **Custom…**
2. Server: `rtmp://east01.ingest.traxstreaming.live:1935/inputs`
3. Stream Key: `generic-input-…?user=<KEY>&pass=<KEY>`

For RTMPS, same split on the `rtmps` entry (port 1936). Plain RTMP sends the
key in clear text on the wire; prefer RTMPS or SRT when the encoder supports
them.

### Encoder settings that work

| Setting | Value |
|---|---|
| Video codec | H.264, high profile |
| Keyframe interval | 2 s |
| Rate control | CBR, 4–8 Mbps for 1080p60 |
| Audio | AAC 160 kbps, 48 kHz stereo |

## Step 4 — confirm you are live

Your encoder says it connected. That is your side of the handshake. To hear it
from ours, read the input back:

```bash
curl -s https://api-dev.traxstreaming.live/v1/studios/$STUDIO/sources/$SOURCE \
  -H "Authorization: Bearer $TRAX_API_KEY"
```

```json
{
  "id": "8c1f…",
  "studioId": "a6a5…",
  "name": "Camera A",
  "type": "generic-input",
  "active": false,
  "status": "OK",
  "publishing": true,
  "publishedAt": "2026-08-22T18:14:07Z"
}
```

**Read `publishing`, not `status`.** `status` is the control-plane
provisioning state — whether this input still has a backing ingest stream —
and it says `OK` for a perfectly configured input nobody is publishing to. It
has never meant "live". `publishing` is media-plane truth, the same signal the
studio's own source LEDs burn, so the API and the operator's screen cannot
disagree.

`publishedAt` is when *this* publish began, not when we last noticed it. It
holds still while your encoder stays connected, so you can render "live for
4m" from it — and a **new** value means your publisher dropped and
reconnected, which is worth surfacing to whoever is holding the camera.

Poll it about every 2 seconds while you are waiting, then stop. Liveness
normally appears within a couple of seconds of the handshake, and it clears
within roughly 15 seconds of the publisher going away — so a source that has
genuinely stopped reads `false` after a short tail, not instantly.

**`publishing` can be `null`, and null is a third answer.** It means the
liveness tracker could not be reached on that request: *unknown*, not offline.
Keep polling. Treating null as "my stream is down" is exactly the wrong move
during a blip, and it is why the field is nullable rather than a bare boolean.

`active` is still a different question again — it is whether the operator has
put this input on the canvas. Publishing without being active is normal and
correct: you are feeding an input the operator can cut to when they want it.
See [What you will see in the studio](#what-you-will-see-in-the-studio).

The same three fields ride on every `GET /v1/studios/{id}/sources` row, so a
dashboard showing every input can read them in one request. The single-source
read exists because a *poll* should not have to pull the whole studio.

## What you will see in the studio

- The input's tile in the Sources panel goes from offline to live within a few
  seconds of the first packets. When the encoder stops, it reads offline again
  within about five seconds.
- **Publishing does not put the studio on air.** A live input is a source the
  operator can place on the canvas; the broadcast to destinations is a separate
  decision. The one exception is deliberate: if the studio's auto-go-live master
  switch is on **and** this specific input has been flagged as a trigger in the
  studio, the first packets start the broadcast. Neither flag is something your
  API key can set on the input; the operator does that in the studio.
- **One publisher per input.** A second encoder connecting with the same key
  replaces the first on the same ingest node. Two field units sharing one input
  will fight; give each its own.

## Stopping and reconnecting

Stopping is closing the connection. There is no API call to make; the input
reads offline and keeps existing.

Reconnecting is dialling the same `complete` URL again. The credential does not
expire and the input does not move, so a client that cached the response at
provisioning time reconnects without another `/v1` call. Re-fetch the ingest
endpoints on a fresh install or when you have deliberately thrown the cached
URL away, not on every reconnect: the endpoint is rate-limited at about
**5 requests per minute per caller**, separately from the rest of `/v1`, and a
client fetching it in a loop is indistinguishable from a script harvesting
publish credentials. A `429` carries a `Retry-After` header; honour it.

When the input is no longer needed, `DELETE /v1/studios/{id}/sources/{sourceId}`
removes it, and the key with it.

## When it does not work

| What you see | Almost always |
|---|---|
| Create returns `402 subscription_required` | The studio's account has no active subscription. Nothing to fix in your code. |
| Ingest returns `403 insufficient_scope` naming `sources:ingest` | Your key has `sources:write` but not `sources:ingest`. They are separate on purpose; mint a key that holds both. |
| Ingest returns `404 studio not found` | Wrong studio id, wrong source id, or the key's owner does not own that studio. Deliberately the same answer for all three. |
| Ingest returns `400` | A protocol name outside `srt, rtmp, rtmps, webrtc, rtsp, hls`, or a body field the endpoint does not know. The message names it. |
| `GET …/ingest` returns `405` | The endpoint is POST only, so the credential never lands in a URL line, a proxy log or a `Referer`. |
| `429` with `Retry-After` | You fetched the endpoints more than about 5 times in a minute. Cache the response; back off for the header's value. |
| `503 write_disabled` | The deployment's write gate is off. Not something you can retry through. |
| SRT connects, then drops in under a second | The streamid was percent-encoded, or edited. Pass `complete` through byte for byte. |
| RTMP is refused at connect | Credentials in userinfo (`rtmp://user:pass@…`) instead of the query string, or a mangled key. The server closes the connection on a bad key. |
| Media flows but the studio stays off air | Expected. See [What you will see in the studio](#what-you-will-see-in-the-studio). |

## Rotate the key

A stream key that got out (pasted into a support chat, on a laptop that walked
off, held by a contributor who no longer works with you) is replaced with one
call:

```bash
curl -sS -X POST \
  "https://api.traxstreaming.live/v1/studios/$STUDIO/sources/$SOURCE/ingest/rotate" \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "protocols": ["srt"], "kickPublishers": true }'
```

Both body fields are optional; an empty body is valid. The response is
**200**, not 201 (nothing was created; the secret attached to the input
changed), and it is byte-for-byte the shape `POST …/ingest` returns:
`streamName`, `ingestUrls`, `granted`, `streamKey`. A client that can configure
an encoder from a mint result needs no second code path for a rotate result.

**There is no overlap window.** The old URL and key stop authenticating the
moment the call returns. That is deliberate: a grace period in which both keys
work is exactly the interval in which the leaked one is still useful. Every
device still configured with the old URL fails its next handshake until you
re-point it. Rotate when you can re-provision, not in the sixty seconds before
a show. Put another way: **rotate and re-provision in the same maintenance
step.** A rotation with no plan for the devices holding the old URL is an
outage you scheduled for yourself.

**`kickPublishers` decides what happens to a session publishing right now,**
and it defaults to `false`. The media server authorises a publish once, at the
handshake, and never re-checks, so an encoder that connected with the old key
keeps broadcasting through the rotation until its socket drops. Send `true`
when you are revoking a leaked credential and mean it: the in-flight session is
cut. Leave it `false` for a planned hand-over: the broadcast in progress
finishes on the old key while every *new* connection needs the new one.

Three smaller rules:

- **`protocols` scopes what comes back, not what is invalidated.** Rotation
  always replaces the single underlying stream key, so asking only for `srt`
  still kills the old `rtmp` URL. The grant rules are the mint's: `srt`,
  `rtmp` and `rtmps` are grantable; `webrtc`, `rtsp` and `hls` are not; read
  `granted` off the response.
- **A typo does not cost you a key.** An unrecognised protocol name is a `400`
  and nothing is rotated; the names are checked before the write.
- **Same scope, same budget, same refusals as the mint.** `sources:ingest`
  (rotation is a credential mint, not a source edit), the separate
  ~5-per-minute bucket with `Retry-After` on `429`, and the same `400` / `401`
  / `403` / `404` / `503 write_disabled` answers as
  [Step 2](#step-2--get-the-publish-urls).

The studio sees it. Open studio tabs re-render the Connection Information
panel with the new URLs, so an app rotating over `/v1` does not leave the
operator holding dead details. It works the other way too: an operator can
rotate from the studio, which invalidates your app's cached URL. Treat a
refused SRT or RTMP handshake on a URL that used to work as "re-fetch the
ingest endpoints", not as "my API key is wrong".


## Where to go next

1. [Developer API (`/v1`)](/reference/public-api) — scopes, the endpoint table,
   and the OpenAPI document to generate a client from.
2. [SRT: the streamid contract](/reference/srt-streamid) and
   [RTMP / RTMPS](/reference/rtmp) — the credential grammar in full and how each
   transport fails.
3. [Contribute a camera from a phone](/guides/contribute-from-a-phone) — the
   other ingest path, for a phone that should appear as a *participant* with a
   name and avatar rather than a plain input.
4. [Build a client](/guides/build-a-client) — the transport map for a thick
   client that also controls the studio and watches the program.


<!-- guides/control-the-canvas -->


# Control the canvas over /v1

You are holding a phone. The show is on a laptop in another room, or on an
encoder in a rack, and you want to move a tile — or put the wide shot back, or
cut to the scene you saved before the show. This guide is that: read the canvas,
change one thing, watch it land.

Eight endpoints, all under `/v1/studios/{id}`, all reaching the same control
plane the studio's own canvas uses. A tile you move here and a tile the operator
drags on the laptop are the same write to the same authority, which is why the
two cannot end up disagreeing about where it is.

> **Which host.** These endpoints are on dev today:
> `https://api-dev.traxstreaming.live/v1` with a dev key. This page will say so
> when they reach production.

> **Scopes.** `canvas:read` for the two reads, `canvas:write` for everything
> that changes something. Both are opt-in — a key minted without naming them
> has neither, and `studios:write` does **not** confer `canvas:write`. Renaming
> a studio and moving what viewers are looking at are different powers, and only
> one of them is visible on air the instant it lands.

## The model in one paragraph

A studio has a **canvas**: a fixed 1920×1080 coordinate space with one
**placement** per source — a rectangle, a stacking order, an opacity, a crop.
Two **layout modes** decide who owns those rectangles. In `auto` the server's
planner resolves them from the active **preset** and the current source set; you
express intent and it computes pixels. In `advanced` you own them and the
planner keeps its hands off. Either way the rectangles are stored in one place,
so what you read is what the encoder is compositing.

## Read the canvas

```http
GET /v1/studios/{studioId}/canvas
Authorization: Bearer sk_live_...
```

```jsonc
{
  "layoutMode": "auto",
  "activePreset": "2up",
  "activeSceneId": "",
  "canvasWidth": 1920,          // the COORDINATE SPACE rectangles live in
  "canvasHeight": 1080,
  "aspectRatio": "16/9",
  "fitMode": "contain",
  "focusSourceId": "src-camera",
  "tileOrder": ["src-camera", "src-screen"],
  "traySourceIds": [],
  "output": { "width": 1920, "height": 1080, "fpsNum": 60, "fpsDen": 1 },
  "layoutRev": 42,
  "membershipBasis": "resolved",
  "placements": [
    {
      "sourceId": "src-camera",
      "name": "Main camera",
      "type": "webcam",
      "active": true,
      "onCanvas": true,
      "inTray": false,
      "rect": { "x": 0, "y": 270, "width": 960, "height": 540 },
      "zIndex": 0,
      "alpha": 1,
      "visible": true
    }
    // …one row per source in the studio
  ]
}
```

One call, not two. A tile is a source *and* a rectangle; if you fetched the
layout and the source list separately you would have two answers taken at two
moments, and the miniature you drew from them could show a tile that was
deleted between the requests.

**`canvasWidth`/`canvasHeight` is not the broadcast resolution.** Rectangles are
in canvas units — always a 1920×1080 space — while `output` is what the encoder
actually produces. A 720p60 program still composites on a 1920×1080 canvas.
Scale your miniature by the canvas; label the stream by `output`.

### Drawing the miniature

`placements` comes back in **paint order**: placed tiles first, back to front
(z ascending, source id breaking ties), then the sources that have never been
placed. Walk it in order and draw each rect scaled by
`yourWidth / canvasWidth`. Three fields decide what a row means:

| Field | Means |
|---|---|
| `onCanvas` | The canvas is compositing this source **right now**. Draw it. |
| `inTray` | Active and eligible, but it did not get a seat. "Up next", not on air. |
| no `rect` | Not placed. There is no rectangle — do not draw a zero one. |

`onCanvas` is resolved **per layout mode**, from the same state the encoder is
driven from, so you never have to work it out yourself:

- **auto** — the source holds a seat in the server planner's *current*
  resolution of `activePreset`. A source the preset displaced comes back
  `onCanvas: false` **and with no `rect`**, even though the underlying layout
  row still holds the rectangle it had under the previous preset.
- **advanced** — the source has a stored, visible, non-degenerate rectangle.

**Do not derive membership from `traySourceIds`.** That list is the auto
planner's overflow intent. Nothing maintains it in advanced mode, so a tile you
placed by hand reads `onCanvas: true` while still appearing in it — that is
correct, not a contradiction. It ships on the read because
`POST /canvas/preset` takes it as a whole-set replacement and you need to be
able to send back what you read; it is not a membership signal.

A source that is **inactive** is neither `onCanvas` nor `inTray`. It is an input
that exists. Saying it is in the tray would imply it is one action from air when
it is two.

### How sure is that answer?

`membershipBasis` on the canvas tells you where `onCanvas`/`inTray` came from:

| Value | Means |
|---|---|
| `resolved` | The normal, authoritative answer. Trust it. |
| `stored` | The auto planner could not resolve this `activePreset` — the encoder ships the preset catalog independently, so a studio can hold one this server does not know. Membership fell back to persisted columns and may be stale. Render the canvas, but do **not** conclude a source is off air. |
| `""` | An older server. It makes no claim; do not read it as either value. |

`ownerSub`, when present, is the person a device source belongs to (a browser
camera, a shared screen, a phone leg). Group rows by it if you want to fold one
person's several legs into one tile the way the studio does.

There are no thumbnail images here. The canvas read is geometry and identity; to
see the actual picture, open a program monitor —
[Monitor the program output](/guides/monitor-the-program).

### Polling cheaply

The read is conditional. Keep the `ETag` and send it back:

```http
GET /v1/studios/{studioId}/canvas
If-None-Match: "a3f9…"
```

An unchanged canvas answers **304** with no body. The tag covers the whole
snapshot, not just `layoutRev`, so a source renamed or deleted invalidates it
too — a 304 always means your picture is still correct.

## Move a tile

```http
PATCH /v1/studios/{studioId}/canvas/placements/{sourceId}
Content-Type: application/json

{
  "rect": { "x": 100, "y": 50, "width": 800, "height": 450 },
  "baseRev": 42
}
```

Every field is optional and **omitted means preserve**. That is what makes this
legal:

```jsonc
{ "zIndex": 3 }          // bring it forward. Rect, alpha, crop all untouched.
{ "visible": false }     // hide it, keeping its rectangle so it does not jump back
{ "cropZoom": 1.8, "cropPanX": 0.4, "cropPanY": 0.5 }   // punch in
```

The one exception: a source that has **never** been placed has nothing to
preserve, so its first write must carry a `rect`. You will get a 400 that says
so.

**This flips the studio to `advanced`.** Per-source geometry *is* the mode: the
server writes it alongside the rectangle, atomically, because a rectangle
sitting under `auto` is geometry the next re-plan is about to erase. If you
wanted to nudge one tile inside an auto arrangement, you wanted a preset — or
this, then a replan to hand it back.

Units, and what happens if you get them wrong:

| Field | Range | Out of range |
|---|---|---|
| `rect` | canvas units; must intersect the canvas; positive, no larger than it | 400 |
| `zIndex` | -10000 … 10000, higher draws in front | 400 |
| `alpha` | 0.0 … 1.0 | 400 |
| `cropZoom` | 1.0 (none) … 10.0 | 400 |
| `cropPanX` / `cropPanY` | 0.0 … 1.0, the visible-rect centre | 400 |
| `fitMode` | `contain` or `stretch` | 400 |

These are refused, never clamped. If you sent a pan as a percentage, a 400 is
the only version of this exchange where you find out.

### Editing next to a live operator

`layoutRev` is a revision that every canvas write bumps. Send back the one you
read as `baseRev` and a write based on a revision the canvas has already passed
comes back **409** instead of clobbering. Re-read, rebase, retry.

Omit `baseRev` and you get last-write-wins. A phone editing while someone else
is at the desk should send it; a script making one considered change need not.

### Retrying on a bad connection

**A retried identical write is not a conflict.** If your request lands and the
response never arrives — which on a train is most of them — send the *same*
request again with the *same* `baseRev`. A stale `baseRev` whose request
describes the tile exactly as it already is comes back **200**, because the
write it asks for is already in effect.

That exception is narrow on purpose. A *different* write on the same stale
`baseRev` is still a 409. So: retry until you get an answer, and treat a 409 as
what it is — someone else moved something.

Every 503 carries `Retry-After`. Back off on it rather than hammering.

## Pick a preset

Usually the better call from a phone. You name the arrangement; the server
resolves the pixels — and keeps resolving them as guests join and leave, which
six hand-placed rectangles will not.

```http
POST /v1/studios/{studioId}/canvas/preset

{ "presetId": "2up", "focusSourceId": "src-camera" }
```

**Discover the ids, do not hardcode them:**

```http
GET /v1/studios/{studioId}/canvas/capabilities
```

```jsonc
{
  "presets": [
    { "id": "solo", "displayName": "Solo", "slotCount": 1,
      "slots": [ { "index": 0, "x": 0, "y": 0, "w": 1, "h": 1 } ],
      "overflowToTray": true, "schematicSvg": "<svg …>" }
  ],
  "libraryVersion": "1",
  "layoutModes": ["auto", "advanced"],
  "fitModes": ["contain", "stretch"],
  "transitions": ["cut", "fade", "slide_left", "…"],
  "canvasWidth": 1920, "canvasHeight": 1080
}
```

The catalog belongs to the encoder, not to this API — ids come and go with
encoder releases, and a client with a baked-in list quietly loses the ones it
never heard of. Cache on `libraryVersion` and refetch when it changes.
`slots` are normalized 0–1 fractions, so `schematicSvg` (or the slots
themselves) draws as a picker thumbnail at any size.

An **empty `presets` with an empty `libraryVersion`** means the encoder could
not be reached. That is a state to render — fall back to what you cached, or
hide the picker — not an error to retry into. The vocabularies below it never
degrade; they are the gateway's own.

`tileOrder`, `traySourceIds` and `slotAssignments` are whole-set replacements
when you send them, and untouched when you do not. Send the complete list; a
partial one silently drops what it omits.

Which means **read before you write**. `GET /canvas` always returns
`slotAssignments` — never `null`, and an **empty object means "no sticky seats
are assigned"**, a real state rather than a field that failed to populate. Take
that map, change the entries you mean, and send the whole thing back:

```
GET  /v1/studios/{id}/canvas          -> { "slotAssignments": { "2up": { "0": "src-a" } }, ... }
POST /v1/studios/{id}/canvas/preset   <- { "presetId": "2up",
                                           "slotAssignments": { "2up": { "0": "src-a", "1": "src-b" } } }
```

Sending `{"2up": {"1": "src-b"}}` there does not add a seat — it replaces the
map and unseats `src-a`.

Preset selection is last-write-wins and takes no `baseRev`. Picking a preset is
a discrete human action taken a few times a show — two people a second apart
should land on the second one, not on a conflict.

## Switch scenes

A scene is a **snapshot of the canvas** an operator captured: the rectangles,
the mode, and which sources were up.

```http
GET  /v1/studios/{studioId}/scenes
POST /v1/studios/{studioId}/scenes/active     { "sceneId": "scn-wide" }
```

```jsonc
{ "data": [
  { "id": "scn-wide", "name": "Wide", "isActive": true,
    "transitionType": "cut", "transitionDuration": 0, "hasComposition": true }
] }
```

`hasComposition: false` means the scene is a label with nothing saved behind it
— recalling it changes nothing. Grey the row rather than offering a recall that
silently does nothing.

**Recalling a scene on a live studio changes what viewers see, immediately.**
There is no preview bus here to rehearse on. Scene rows carry an is-preview
flag, but no second canvas is composited from it, so a "preview" on this API
would name a rehearsal that does not happen. Program is the only destination a
scene has.

The recall returns the resulting canvas, so you can render straight from the
response.

## Go back to auto

```http
POST /v1/studios/{studioId}/canvas/replan     { "layoutMode": "auto" }
```

The way out of advanced mode: the row flips and the planner re-runs in one call,
replacing hand-placed rectangles with its own. Sent without a mode against a
studio that is already in `auto`, it is a pure re-resolve.

Sent without a mode against an **advanced** studio it does nothing, and says so
by returning the unchanged canvas. That is deliberate: the planner does not own
geometry in advanced mode, and quietly re-planning a studio whose operator took
manual control would move tiles on air that nobody asked to move.

You will rarely need it. A guest joining, a camera going live, a preset being
picked — all of those re-plan on their own. `replan` is for the case where your
own edits have wandered and the honest fix is to hand the arrangement back.

## What is *not* here: dragging

There is no REST call for a drag, and there should not be one. Every endpoint on
this page persists to the database, re-asserts the geometry to a running
encoder, and fans an event out to every open studio tab. That is the right cost
for a committed move and completely the wrong cost thirty times a second.

If you are building a surface where someone drags a tile with a finger, do it
the way the web studio does: move the tile locally at whatever frame rate you
like, and **commit the final rectangle once** with a single
`PATCH …/canvas/placements/{sourceId}`. If you need the intermediate frames to
appear on the program in real time — a hardware controller, a live nudge — that
is the studio WebSocket's ephemeral transform frame, described in
[Drive the studio canvas](/guides/drive-the-canvas), which persists nothing and
acknowledges nothing by design.

## A whole session

Read, move one tile, put it back the way the studio would have it:

```bash
BASE=https://api-dev.traxstreaming.live/v1
STUDIO=…; KEY=sk_live_…

# 1. What does it look like?
curl -s -H "Authorization: Bearer $KEY" "$BASE/studios/$STUDIO/canvas"

# 2. Move the camera tile, guarded by the rev you just read.
curl -s -X PATCH -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  "$BASE/studios/$STUDIO/canvas/placements/src-camera" \
  -d '{"rect":{"x":0,"y":0,"width":1920,"height":1080},"baseRev":42}'

# 3. Changed your mind — hand it back to the planner.
curl -s -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  "$BASE/studios/$STUDIO/canvas/replan" -d '{"layoutMode":"auto"}'
```

Each of those returns the whole canvas, so you never have to re-read to find out
what your change did.

## Where to go next

1. [Monitor the program output](/guides/monitor-the-program) — see the picture
   the canvas you are driving actually produces.
2. [Control the mixer from your app](/guides/control-the-mixer) — the audio half
   of the same surface.
3. [Drive the studio canvas](/guides/drive-the-canvas) — the WebSocket path, for
   a first-party app that needs live drag frames and push updates.
4. [The /v1 reference](/reference/public-api) — every endpoint, every scope.


<!-- guides/control-the-mixer -->


# Control the mixer from your app

Someone is on the show from a phone, and they want the two controls every
contributor actually wants: *am I muted*, and *how loud am I*. This guide is
the API behind that — read a studio's audio mix, then move one fader or one
mute.

> **Which host.** These endpoints are on dev only for now:
> `https://api-dev.traxstreaming.live/v1` with a dev key. This page will say so
> when they reach production.

Three calls, and the read is the one you start with:

1. **`GET /v1/studios/{id}/audio`** returns the whole mix — the master strip
   plus one strip per source.
2. **`PATCH /v1/studios/{id}/audio/sources/{sourceId}`** moves one channel.
3. **`PATCH /v1/studios/{id}/audio/master`** moves the master.

The thing to internalise: **you are reaching the same mixer the operator is
looking at.** Not a copy of it, not a phone-side shadow of it. Mute a mic here
and the fader moves on the operator's screen, the encoder applies it, and the
viewers stop hearing that person — all from the one write.

## Before you start

- An API key holding **`audio:read`** to see the mix and **`audio:write`** to
  change it. `audio:write` includes read, so a key that controls the mixer does
  not need both. Neither is in the default scope set: a studio's mix tells you
  who is muted and how loud each person is, which is a picture of the show
  rather than inventory, so you ask for it by name. Create the key under
  **Developer → API keys** in your account.
- The **studio id**, and the **source id** of whoever you are controlling. Both
  come from `GET /v1/studios/{id}/sources`.

## Step 1 — read the mix

```bash
curl -s https://api-dev.traxstreaming.live/v1/studios/$STUDIO/audio \
  -H "Authorization: Bearer $TRAX_API_KEY"
```

```json
{
  "master": { "muted": false, "volume": 1 },
  "sources": [
    {
      "sourceId": "0520baa7-…",
      "name": "Microphone",
      "type": "webrtc-audio-input",
      "active": true,
      "muted": false,
      "volume": 0.8,
      "pan": 0,
      "soloed": false,
      "trim": 1,
      "muteGroups": []
    },
    {
      "sourceId": "4fd7c67d-…",
      "name": "Camera A",
      "type": "generic-input",
      "active": true,
      "muted": false,
      "volume": 1,
      "pan": 0,
      "soloed": false,
      "trim": 1,
      "muteGroups": []
    }
  ]
}
```

**One call returns every strip, on purpose.** A fader surface draws all of its
channels at once, and fetching them one at a time would let the strips disagree
with each other halfway through a render.

**Every source gets a strip, including ones with no audio track.** The strip is
per-source state that persists and is re-applied to the encoder whenever that
source is composited — so a camera has one even if nothing is coming out of it.
Read `type` and `active` and draw what makes sense for your app.

**Untouched sources report `volume: 1`, not `volume: 0`.** A source nobody has
moved in the mixer is running at unity, unmuted, centre. Those are the values
the encoder is applying to it right now, so reporting them is a measurement,
not a default standing in for missing data.

## Step 2 — mute someone

```bash
curl -s -X PATCH \
  https://api-dev.traxstreaming.live/v1/studios/$STUDIO/audio/sources/$SOURCE \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "muted": true }'
```

```json
{
  "sourceId": "0520baa7-…",
  "name": "Microphone",
  "type": "webrtc-audio-input",
  "active": true,
  "muted": true,
  "volume": 0.8,
  "pan": 0,
  "soloed": false,
  "trim": 1,
  "muteGroups": []
}
```

Note what did *not* happen: `volume` is still `0.8`. **Send only the fields you
are changing.** Anything you leave out keeps the value it had, which is what
lets a phone toggle mute without knowing — or destroying — the mix an operator
spent the pre-show building.

**Set `muted`. Do not write `volume: 0` and call it mute.** They are different
things and the difference is the whole point: mute is an independent gate, and
the fader keeps its position underneath it, so unmuting returns to exactly the
level the operator was at. Muting by zeroing the fader throws that position
away, and the operator has to find it again on air.

The response is the whole strip, not just what you sent, so you can render from
it without a follow-up read.

## Step 3 — set your level

```bash
curl -s -X PATCH \
  https://api-dev.traxstreaming.live/v1/studios/$STUDIO/audio/sources/$SOURCE \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "volume": 0.6 }'
```

**`volume` is a linear gain, not decibels.** `0.0` is silence, `1.0` is unity
(0 dB), and above `1.0` amplifies, up to a ceiling of `10.0`. If you send `-6`
expecting six decibels down, you get a `400` — deliberately. The alternative is
clamping it to `0.0`, which would silence someone and never tell you the client
was speaking the wrong unit.

The same applies to `pan` (`-1.0` full left … `+1.0` full right) and `trim`
(the pre-fader input gain, linear, `1.0` nominal, `0.1`–`16.0`). Out of range
is an error, every time.

## What the fields mean

| Field | What it is |
|---|---|
| `muted` | The channel's gate. Independent of `volume` — the fader keeps its position underneath |
| `volume` | The channel fader. LINEAR, `0.0`–`10.0`, `1.0` = unity (0 dB). Not decibels |
| `pan` | Stereo position, `-1.0` full left … `+1.0` full right |
| `soloed` | The operator's solo latch, shared across everyone in the studio. A mixing-desk intent flag — it does not by itself mute the other channels, so do not read it as "everything else is off" |
| `trim` | Pre-fader input gain, where a hot or quiet input is brought to a nominal level before the fader. LINEAR, `1.0` nominal |
| `muteGroups` | Which mute groups (1–4) this channel belongs to. **Read-only here** — the group master button that gives membership its meaning lives in the studio's mixer panel, so there is nothing on this API a membership could be triggered by |
| `active` | Whether the operator has this source on the canvas. A different question from `muted`, and the one that explains a strip reading muted because the source was switched off — see below |

## The master strip

```bash
curl -s -X PATCH \
  https://api-dev.traxstreaming.live/v1/studios/$STUDIO/audio/master \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "muted": true }'
```

The master is the level and gate the whole broadcast mix passes through on its
way out. **Muting it silences the program for every viewer on every
destination** while leaving each source's own strip alone. It is the "kill the
whole mix" control; to silence one contributor, patch that source instead.

It has a fader and a mute and nothing else — no pan, no solo, no trim. That is
the actual shape of the master strip in the studio, and there was no reason to
invent the rest.

## Muted because switched off

Turning a source **off** in the studio auto-mutes it, and turning it back on
restores the mute it had before. So a strip can read `"muted": true` for two
different reasons: someone muted it, or the source is not on the canvas.
`active` is what tells them apart.

This matters if you are drawing a mute button: on an inactive source, the mute
you are showing is a consequence of it being off, and unmuting it over this API
will be overwritten the next time it is switched on. Read `active` first.

## When it does not work

| Response | What happened |
|---|---|
| `400 invalid_request` | A value out of range (see the units above), or a field the endpoint does not accept. `mute` is not the spelling — it is `muted`. `muteGroups` is read-only |
| `403 forbidden` | The key lacks `audio:read` (to read) or `audio:write` (to change). A key with every `sources:*` scope still cannot reach the mixer — managing inputs and controlling the mix are separate powers |
| `404 not_found` | The studio is not one you can see, **or** the source is not in it. The two are deliberately indistinguishable |
| `503 unavailable` | Writes are disabled on this deployment, or the studio service is briefly unreachable. Retry |

## Where to go next

1. [Stream to a live input](/guides/stream-to-a-live-input) — get audio into
   the studio in the first place.
2. [Drive the canvas](/guides/drive-the-canvas) — the visual half of the same
   idea.
3. [The /v1 reference](/reference/public-api) — every endpoint and scope.


<!-- guides/drive-the-canvas -->


# Drive the studio canvas

The studio's canvas — which sources are on the program, where their tiles sit,
which preset or scene is active — is **control-plane state**, not media. A native
or desktop app drives it exactly the way the web studio does: over a single
**WebSocket** to the studio control plane, sending mutation RPCs and receiving
the state changes back as realtime events.

This guide is the "here's how you drive it" walkthrough for the WebSocket path.
If you are building a **third-party** integration, or an app that only needs to
commit changes rather than stream drag frames, the REST equivalent is
[Control the canvas over /v1](/guides/control-the-canvas) — same authority, same
geometry, one call per change and no socket to hold open. The connection and auth
are the same studio WebSocket introduced in
[Build a client → Controlling a studio](/guides/build-a-client#controlling-a-studio-websocket);
this page adds the canvas-specific RPCs, their payloads, and the sync model.

## The model in one paragraph

Every canvas edit is a **request/reply RPC** you send on the socket; every edit
(yours or a collaborator's) persists server-side and **fans out to the other
connections as a typed `*_changed` event**. There is no separate "canvas
protocol" — the studio owns the state, you mutate it, and the studio streams the
new truth to every tab and device. Two layout **modes** decide whether the server
resolves geometry for you (auto) or honors the explicit rectangles you send
(advanced).

## Connect to the studio WebSocket

```
wss://studio-api-dev.traxstreaming.live/api/v1/ws/studios/{studioId}/events
```

- **Auth.** A native app sets `Authorization: Bearer <jwt>` on the upgrade
  request (the user's OAuth token). Where headers are impossible, the token is
  also accepted as a `?token=<jwt>` query parameter.
- **Client stamp.** The events socket is version-gated. Add a
  `?client=<epoch-seconds>` query parameter (a build stamp) to the connect URL —
  a native app may instead send it as an `X-Trax-Client` header. Send a current
  epoch-seconds value; without it the upgrade can be rejected with `426` in
  environments where the gate is enforcing. (The `/monitor` and `/contribute`
  endpoints are exempt from this gate; the events socket is not.)
- **Access** is resolved once at upgrade against your membership of that studio,
  then each RPC is gated by your role (`view` < `edit` < `admin`). Canvas
  mutations require **`edit`**; reads require **`view`**.

On connect the server sends a `hello` frame carrying your connection id:

```json
{ "type": "hello", "data": { "id": "<connectionId>", "studioId": "<studioId>" } }
```

## Frame shapes

All frames are JSON. Three shapes travel this socket:

```jsonc
// 1. RPC request  (client → server)
{ "type": "toggle_source", "requestId": "<uuid>", "data": { /* payload */ } }

// 2. RPC reply    (server → client, correlated by requestId)
{ "type": "reply", "requestId": "<uuid>", "ok": true,  "result": { /* … */ } }
{ "type": "reply", "requestId": "<uuid>", "ok": false, "error": "…", "errorCode": "…" }

// 3. Realtime event (server → client, no requestId)
{ "type": "source_changed", "data": { "action": "updated", "id": "…", "source": { /* … */ } } }
```

- **`requestId`** is a client-generated correlation token; match the reply by it.
- Errors come back as a reply with `ok: false` — the RPC is never silently
  dropped. `errorCode` is a stable machine token for selected failures (e.g.
  `subscription_required`); fall back to `error` for the human message.

## Seed the current state, then subscribe

The `hello` frame does not carry the canvas. Fetch the current state over REST
once, render it, then keep it live from the socket's events:

| Read | Endpoint |
|---|---|
| Source list (tiles, mixer rows) | `GET /api/v1/sources?studioId={studioId}` |
| Layout (mode, preset, per-source geometry, tile order) | `GET /api/v1/studios/{studioId}/layout` |

Both carry `Authorization: Bearer <jwt>`. After that first paint, apply every
`source_changed` / `layout_changed` / `scene_changed` event to your local model —
never re-poll.

## Send mutations, receive events — the sync rule

You are both a **sender** of mutations and a **receiver** of everyone's changes,
including your own studio's other devices. Two properties make this converge:

- **Your own echo is dropped.** The connection that made a change does **not**
  receive the `*_changed` event for it — you already have the RPC reply. So
  **apply your change optimistically** from the reply; the fan-out is for
  *other* connections.
- **Last-write-wins, guarded by a revision.** The layout row carries a monotonic
  `layoutRev`. Geometry writes (`update_layout`, `update_source_transform`) accept
  an optional `baseRev` — the rev your edit was based on. If it is older than the
  current row the write is **rejected as stale**: the reply comes back with
  `applied: false` and the current row, and **no** event is fanned out. Rebase
  your pending edit onto the returned rev and retry instead of clobbering a
  newer state. `set_layout_preset` is last-write-wins (a discrete user action,
  not the high-frequency drag path), so it is not rev-gated and its reply always
  carries `applied: true` — the flag is there for a uniform result shape.

The realtime topics you will consume for the canvas:

| Event `type` | Fires when |
|---|---|
| `source_changed` | a source was created / updated / deleted (payload `{action, id, source}`) |
| `layout_changed` | the layout row changed — geometry, preset, tile order, mode (payload `{layout}`) |
| `scene_changed` | a scene was created / updated / deleted / flipped active (payload `{id, scene}`) |
| `studio_state_changed` | live state, mode, master audio (payload `{state}`) |

## Two layout modes: auto vs advanced

`layout.layoutMode` is either `"auto"` or `"advanced"`, and it decides who owns
the geometry:

- **`auto` (default).** The server resolves each tile's rectangle from the active
  **preset** and the source set. You express *intent* — which preset, which source
  is focused, the slot order — and the studio computes the pixels. Explicit rects
  you send are **overridden** by the planner. This is the mode to use for
  "just make it look right"; it is authoritative while it is on.
- **`advanced`.** You own the geometry. Each source's rectangle is whatever you
  last wrote (`update_source_transform` / `sourceLayouts`), and the planner does
  not touch it.

The mode flips **atomically with the geometry** in a single write: send
`layoutMode` on the same `update_layout` or `set_layout_preset` call that carries
your rects, so there is never a window where advanced geometry sits under auto
mode waiting to be re-planned. In short: **send explicit rectangles only when you
are (or are moving to) `advanced`**; in `auto`, drive presets and focus.

## Driving the canvas — the key RPCs

All of these are `edit`-gated. Payloads below are the `data` object of the RPC
frame. For every layout write — `update_layout`, `update_source_transform`, and
`set_layout_preset` — the reply `result` is the **StudioLayout row inlined at the
top level plus an `applied` boolean**, e.g.:

```jsonc
{ "applied": true, "activePreset": "2up", "layoutMode": "auto",
  "sourceLayouts": { … }, "slotAssignments": { … },
  "focusSourceId": "…", "layoutRev": 42, "updatedAt": "…" /* all row fields */ }
```

It is **not** nested under a `layout` key. Source writes return `{ source, … }`.

### Add, remove, and activate sources

```jsonc
// add_source — create a source (provisions its ingest). result: {source, …}
{ "type": "add_source", "requestId": "…", "data": { /* CreateSourceInput */ } }

// remove_source — delete a source
{ "type": "remove_source", "requestId": "…", "data": { "sourceId": "src-…" } }

// toggle_source — put a source on the program / take it off (activate/deactivate)
{ "type": "toggle_source", "requestId": "…",
  "data": { "sourceId": "src-…", "isActive": true } }
```

### Move / resize a tile (advanced mode)

`update_source_transform` writes one source's explicit rectangle. Honored in
`advanced` mode; in `auto` the planner will re-resolve it.

```jsonc
{ "type": "update_source_transform", "requestId": "…", "data": {
    "sourceId": "src-…",
    "x": 0, "y": 0, "width": 1280, "height": 720,   // integer canvas coords
    "zIndex": 1,
    "alpha": 1.0,
    "fitMode": "contain",                            // optional; omit to preserve
    "isVisible": true,                               // optional
    "baseRev": 42                                    // optional stale-write guard
} }
```

For a live drag you can stream ephemeral `live_source_transform` frames (no
`requestId`, no reply, not persisted) at up to ~30 Hz for real-time motion, then
commit the final rectangle with one `update_source_transform`.

### Switch preset / focus (auto mode)

```jsonc
// set_layout_preset — pick the active preset (and optionally mode/focus/order)
{ "type": "set_layout_preset", "requestId": "…", "data": {
    "layoutMode": "auto",
    "activePreset": "2up",          // a preset id — see discovery below
    "focusSourceId": "src-…",       // optional — promote one source to slot 1
    "traySourceIds": ["src-…"],     // optional — the "up next" overflow tray
    "tileOrder": ["src-…", "src-…"] // optional — slot order intent
} }

// set_focus — promote a single source to the focus slot
{ "type": "set_focus", "requestId": "…", "data": { "sourceId": "src-…" } }

// swap_in_from_tray — bring a tray source onto the canvas
{ "type": "swap_in_from_tray", "requestId": "…", "data": { "sourceId": "src-…" } }
```

**Preset ids — discover them, don't hardcode.** `GET
/api/v1/studios/{id}/layout/capabilities` returns the authoritative catalog for
this studio:

```jsonc
{
  "presets": [
    { "id": "solo", "displayName": "Solo", "slotCount": 1,
      "slots": [ { "index": 0, "x": 0, "y": 0, "w": 1, "h": 1 } ],
      "overflowToTray": true, "schematicSvg": "<svg …>" }
    // …one entry per preset
  ],
  "libraryVersion": "1"
}
```

The `activePreset` you send is a preset `id` from this list. Each entry also
carries a `displayName`, normalized `slots` geometry, and a `schematicSvg` you
can render as a picker thumbnail, so a switcher can be fully data-driven; cache
on `libraryVersion`. The current built-in ids are `solo` (default), `2up`,
`3up`, `4up`, `spotlight_strip`, `pip`, and `screen_speaker` — there is **no**
`grid`. The endpoint is proxied from the encoder; on a degraded encoder it
returns `{ "presets": [], "libraryVersion": "" }`, so fall back to the built-in
ids or retry.

### Partial layout writes

`update_layout` is a partial patch of the layout row — every field is optional,
and `nil` leaves the stored value untouched. Use it to set `sourceLayouts`
wholesale, flip `layoutMode`, change `aspectRatio`/`fitMode`/`tileOrder`, etc.:

```jsonc
{ "type": "update_layout", "requestId": "…", "data": {
    "layoutMode": "advanced",
    "sourceLayouts": { "src-…": { "x": 0, "y": 0, "width": 1920, "height": 1080 } },
    "baseRev": 42
} }
```

### Scenes (save & recall a look)

```jsonc
// set_active_scene — restore a saved scene's canvas to the live program
{ "type": "set_active_scene", "requestId": "…", "data": { "sceneId": "scn-…" } }

// capture_scene — re-snapshot the current canvas into an existing scene
{ "type": "capture_scene", "requestId": "…", "data": { "sceneId": "scn-…" } }

// create_scene — new scene row
{ "type": "create_scene", "requestId": "…", "data": { /* CreateSceneInput */ } }
```

## See what you are building

To watch the composited result of the canvas you are driving, open a program
monitor — the WHEP play of the same studio's program output. See
[Monitor the program output](/guides/monitor-the-program).

## The full RPC catalog

This guide covers the canvas surface. The studio WebSocket exposes many more RPCs
(destinations, go-live, chat, presence, rundown, intercom, recording…) and the
full set of realtime events. The **exhaustive, generated** method and event
reference is first-party/internal today: if you are a logged-in first-party
developer, see the internal **Studio WS API** reference (RPCs + events), which is
generated directly from the server's dispatch table. Third-party apps reach the
platform through the public [`/v1` REST gateway](/reference/public-api) and this
WebSocket — never internal service endpoints directly.

## Where to go next

1. [Build a client](/guides/build-a-client) — the transport map, native OAuth +
   PKCE, and the studio-control WebSocket.
2. [Monitor the program output](/guides/monitor-the-program) — play the program
   your canvas produces, over WHEP.
3. [Contribute a camera from a phone (SRT)](/guides/contribute-from-a-phone) —
   feed a camera into the studio you are controlling.
4. [Stream paths](/reference/path-grammar) — the path grammar shared by every
   media transport.


<!-- guides/monitor-the-program -->


# Monitor the program output (WHEP)

A native or desktop client can play the studio's **program output** — the exact
composited feed the cloud encoder is sending to your destinations — over
**WebRTC WHEP**. This is the app analogue of the program-preview tile in the web
studio: a low-latency confidence monitor of what is actually going out.

[WHIP / WHEP](/reference/whip-whep) documents the WebRTC play protocol, but a
player still needs a **read token** and the **URL** to play. This guide is the
one endpoint that hands you both, scoped to your studio's program path.

> **The same credential is on `/v1` now.**
> `POST /v1/studios/{id}/monitor` mints this token through the public gateway,
> authenticated with an `sk_live_` key or an OIDC bearer, and adds an SRT
> alternative for clients that cannot speak WHEP. See
> [Go live from a phone over `/v1`](/guides/go-live-from-a-phone#step-2--the-return-feed).
> Everything below about WHEP, the token and the expiry applies there unchanged.

## What you talk to

The monitor descriptor comes from the **studio control plane** (the studio API),
the same host you already use for login and contribution — not the `/v1` REST
gateway. Playback itself is a direct WebRTC dial to the media host in the
descriptor.

| | Development | Production |
|---|---|---|
| Studio API (control plane) | `https://studio-api-dev.traxstreaming.live` | `https://studio-api.traxstreaming.live` |
| Identity (OAuth login) | `https://auth-dev.traxstreaming.live` | `https://auth.traxstreaming.live` |
| WHEP playback | the `whepUrl` in the descriptor | the `whepUrl` in the descriptor |

Always dial the exact `whepUrl` the descriptor hands you rather than
reconstructing the media host yourself.

## Authenticate as the user

The mint call carries the user's access token: `Authorization: Bearer <jwt>`,
the OAuth 2.0 + PKCE token described in [Build a client](/guides/build-a-client#native-app-authentication--oauth-20-with-pkce).
Any studio **member** may monitor — owner or collaborator, in any role
(view is enough). The mint verifies your membership before issuing the read
capability.

## 1. Fetch the monitor descriptor

Ask the studio for a program-monitor capability. No request body is required:

```
POST /api/v1/studios/{studioId}/monitor
Authorization: Bearer <jwt>
```

```bash
curl -sS -X POST \
  https://studio-api-dev.traxstreaming.live/api/v1/studios/$STUDIO_ID/monitor \
  -H "Authorization: Bearer $USER_JWT"
```

The `200` response is the descriptor you play with:

```json
{
  "whepUrl": "https://<media-host>:8889/s/<studioId>/pp/whep",
  "streamName": "s/<studioId>/pp",
  "token": "<JWT — aud trax-mediamtx-read>",
  "expiresAt": "2026-08-11T20:15:00Z"
}
```

| Field | What it is |
|---|---|
| `whepUrl` | The WHEP play URL to POST your SDP offer to. Use it verbatim. |
| `streamName` | The program path this monitor reads (`s/<studioId>/pp`). |
| `token` | The **read token** — a short-lived JWT (`aud: trax-mediamtx-read`) scoped to exactly that one path. This is the Bearer for the WHEP POST, **not** your user token. |
| `expiresAt` | RFC 3339 expiry of the read token. |

`403` means you are not a member of the studio; `503` means the monitor signer
or media endpoint is momentarily unavailable — retry.

## 2. Play it over WHEP

This is the standard WHEP play flow from [WHIP / WHEP](/reference/whip-whep),
with one rule: the Bearer on the signaling `POST` is the descriptor's **read
token**, not the user token.

1. Create a **recv-only** `RTCPeerConnection`.
2. Create an SDP offer, gather ICE (**non-trickle** — wait for
   `iceGatheringState === "complete"`).
3. `POST` the offer to `whepUrl` with `Content-Type: application/sdp` and
   `Authorization: Bearer <token>`.
4. Set the returned SDP answer as the remote description and render the track.

```js
// descriptor = the JSON from POST /monitor
const pc = new RTCPeerConnection();
pc.addTransceiver('video', { direction: 'recvonly' });
pc.addTransceiver('audio', { direction: 'recvonly' });
pc.ontrack = (e) => { videoEl.srcObject = e.streams[0]; };

await pc.setLocalDescription(await pc.createOffer());
// non-trickle: let ICE finish before signaling
await new Promise((resolve) => {
  if (pc.iceGatheringState === 'complete') return resolve();
  pc.addEventListener('icegatheringstatechange', () => {
    if (pc.iceGatheringState === 'complete') resolve();
  });
});

const res = await fetch(descriptor.whepUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/sdp',
    Authorization: `Bearer ${descriptor.token}`, // the READ token
  },
  body: pc.localDescription.sdp,
});
await pc.setRemoteDescription({ type: 'answer', sdp: await res.text() });
```

Audio arrives as **Opus** (feeds contributed as AAC are transcoded on the way
out) — see [WHIP / WHEP](/reference/whip-whep) for the codec and failure-mode
tables.

## Token semantics — re-provision per open

- **Short-lived.** The read token lasts about **5 minutes** (hard-capped at 15).
  Do not cache or share it — it travels in the WHEP request.
- **mediamtx authorizes a WHEP read only at connect time.** An established
  monitor keeps playing after the token expires; a fresh token is only needed to
  **(re)connect**. So the rule is simple: **call `POST /monitor` again every time
  you open (or reopen) the player**, and don't bother refreshing a token for a
  connection that is already up.
- **Single-path scope.** The token authorizes exactly `s/<studioId>/pp` and
  nothing else — it cannot read any other source or studio.

## The program only flows when the studio is live

The endpoint always mints the capability, but **media flows only while the studio
is live** and pushing its program-preview feed. A monitor opened while the studio
is off-air **connects successfully but shows no video yet** — it should start
rendering frames when the studio goes live.

Keep the WHEP peer connection up across go-live (or reconnect on a short retry)
so the monitor lights up the moment the program starts. Treat "connected, no
frames" as a normal pre-live state, not an error.

## Where to go next

1. [WHIP / WHEP](/reference/whip-whep) — the WebRTC publish/play protocol, token
   audiences, and failure modes.
2. [Drive the studio canvas](/guides/drive-the-canvas) — control the layout your
   monitor is showing over the studio WebSocket.
3. [Build a client](/guides/build-a-client) — the transport map and native OAuth
   + PKCE login that issues the user token.
4. [Contribute a camera from a phone (SRT)](/guides/contribute-from-a-phone) —
   the publish side of the same studio.

## Knowing when to connect (and when to stop)

Do not poll `stream-status` to find out whether the program is worth watching.

`GET /v1/studios/{id}/events` is a Server-Sent Events stream that tells you when
the studio goes on air, when it goes off, and when any source's `publishing`
flips — one connection instead of a request every few seconds, which matters on
the same cellular uplink your device may be publishing over.

Open it once, wait for `event: streamStatus` with `"live": true`, then mint your
monitor token and connect WHEP. When `"live"` goes `false`, tear the peer
connection down.

The full event vocabulary, the `Last-Event-ID` reconnect contract and the limits
are in [Go live from a phone](/guides/go-live-from-a-phone#stop-polling-the-events-stream).


<!-- guides/sdk-swift -->


# SDK quickstart: Swift (iOS / macOS)

Generate a typed Swift client for the `/v1` Developer API from its OpenAPI spec
and make your first call.

> No hand-written Swift SDK is published yet — you generate one from the live
> spec. An official SDK is a [roadmap](/reference/roadmap) item.
>
> **Which credential?** A shared **API key** (`sk_live_…`) is right for your own
> automation and server-side jobs. A **first-party iOS app a user logs into**
> should authenticate **as that user** with OAuth 2.0 + PKCE and send the user's
> token — see [Build a client](/guides/build-a-client). The steps below use an
> API key; swap in the user's bearer token for a logged-in app.

## 1. Get the spec

```
https://api-dev.traxstreaming.live/v1/openapi.json
```

## 2. Generate a typed client

Use [`openapi-generator`](https://openapi-generator.tech/):

```bash
brew install openapi-generator      # or: npm i -g @openapitools/openapi-generator-cli
openapi-generator generate \
  -i https://api-dev.traxstreaming.live/v1/openapi.json \
  -g swift5 \
  --additional-properties=responseAs=AsyncAwait,projectName=TraxAPI \
  -o ./TraxAPI
```

Add the generated `TraxAPI` package to your Xcode project (drag it in, or add it
as a local Swift Package).

Prefer Apple's toolchain? The
[Swift OpenAPI Generator](https://github.com/apple/swift-openapi-generator) is a
first-party alternative (add it as an SPM plugin and point it at the same spec).

## 3. Authenticate

**Building an app a user logs into?** Sign them in with OAuth 2.0 + PKCE and
send *their* token — jump to
[Sign the user in (OIDC + PKCE)](#sign-the-user-in-oidc-pkce) below.

**Automating your own account?** Create an API key from your account's
**Developer / API Keys** screen and copy the `sk_live_…` secret once. Store it
in the **Keychain**, never in source or `Info.plist`.

## Sign the user in (OIDC + PKCE)

A first-party iOS app authenticates the user against the TRaX identity provider
with the **Authorization-Code flow + PKCE**, then calls `/v1` with the user's
access token. The user types their password (and MFA / passkey, if enabled) on
the IdP's **hosted login page** shown in an `ASWebAuthenticationSession` — never
in your UI. See [Authentication → User login for mobile & native
apps](/reference/authentication#user-login-for-mobile-and-native-apps-oidc-pkce)
for the concept; this is the concrete Swift.

**Config** (dev shown; swap the issuer + `clientId` for production):

```swift
enum TraxAuth {
    // Dev IdP. Production: https://auth.traxstreaming.live
    static let issuer = "https://auth-dev.traxstreaming.live"
    static let authorize = "\(issuer)/oauth/v2/authorize"
    static let token     = "\(issuer)/oauth/v2/token"
    static let endSession = "\(issuer)/oidc/v1/end_session"

    // Public native client (no secret). Dev value; production has its own id.
    static let clientId = "385862192278274086"

    // Must match a redirect URI registered on the client, exactly.
    static let redirectURI = "live.traxstreaming.ios://oauth/callback"
    static let callbackScheme = "live.traxstreaming.ios"

    static let scope = "openid profile email offline_access"
    static let apiBase = "https://api-dev.traxstreaming.live"
}
```

> Register `live.traxstreaming.ios` as a URL scheme in your target (Info →
> URL Types), or use a Universal Link. The value above is a placeholder — use
> the scheme that matches your registered redirect URI.

**PKCE helper** — a random verifier and its S256 challenge:

```swift
import CryptoKit
import Foundation

struct PKCE {
    let verifier: String
    let challenge: String

    init() {
        var bytes = [UInt8](repeating: 0, count: 32)
        _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
        verifier = Data(bytes).base64URLEncodedString()
        let digest = SHA256.hash(data: Data(verifier.utf8))
        challenge = Data(digest).base64URLEncodedString()
    }
}

extension Data {
    func base64URLEncodedString() -> String {
        base64EncodedString()
            .replacingOccurrences(of: "+", with: "-")
            .replacingOccurrences(of: "/", with: "_")
            .replacingOccurrences(of: "=", with: "")
    }
}
```

**Token models:**

```swift
struct TokenResponse: Codable {
    let accessToken: String
    let refreshToken: String?
    let expiresIn: Int
    let tokenType: String

    enum CodingKeys: String, CodingKey {
        case accessToken = "access_token"
        case refreshToken = "refresh_token"
        case expiresIn = "expires_in"
        case tokenType = "token_type"
    }
}
```

**The login round-trip** — open the hosted page, capture the code, exchange it:

```swift
import AuthenticationServices

final class TraxLogin: NSObject, ASWebAuthenticationPresentationContextProviding {

    func signIn() async throws -> TokenResponse {
        let pkce = PKCE()
        let state = UUID().uuidString

        var comps = URLComponents(string: TraxAuth.authorize)!
        comps.queryItems = [
            .init(name: "response_type", value: "code"),
            .init(name: "client_id", value: TraxAuth.clientId),
            .init(name: "redirect_uri", value: TraxAuth.redirectURI),
            .init(name: "scope", value: TraxAuth.scope),
            .init(name: "code_challenge", value: pkce.challenge),
            .init(name: "code_challenge_method", value: "S256"),
            .init(name: "state", value: state),
        ]

        // Open the IdP's hosted login; the browser redirects to our custom
        // scheme with ?code=…&state=… once the user authenticates.
        let callbackURL: URL = try await withCheckedThrowingContinuation { cont in
            let session = ASWebAuthenticationSession(
                url: comps.url!,
                callbackURLScheme: TraxAuth.callbackScheme
            ) { url, error in
                if let url { cont.resume(returning: url) }
                else { cont.resume(throwing: error ?? URLError(.badServerResponse)) }
            }
            session.presentationContextProvider = self
            session.prefersEphemeralWebBrowserSession = false // keep IdP SSO cookie
            session.start()
        }

        let items = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false)?.queryItems
        guard items?.first(where: { $0.name == "state" })?.value == state,
              let code = items?.first(where: { $0.name == "code" })?.value else {
            throw URLError(.userAuthenticationRequired)
        }

        return try await exchange(code: code, verifier: pkce.verifier)
    }

    private func exchange(code: String, verifier: String) async throws -> TokenResponse {
        var req = URLRequest(url: URL(string: TraxAuth.token)!)
        req.httpMethod = "POST"
        req.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
        req.httpBody = form([
            "grant_type": "authorization_code",
            "client_id": TraxAuth.clientId,
            "code": code,
            "redirect_uri": TraxAuth.redirectURI,
            "code_verifier": verifier,           // PKCE — stands in for a secret
        ])
        let (data, _) = try await URLSession.shared.data(for: req)
        return try JSONDecoder().decode(TokenResponse.self, from: data)
    }

    private func form(_ params: [String: String]) -> Data {
        params.map { k, v in
            "\(k)=\(v.addingPercentEncoding(withAllowedCharacters: .alphanumerics) ?? v)"
        }.joined(separator: "&").data(using: .utf8)!
    }

    func presentationAnchor(for _: ASWebAuthenticationSession) -> ASPresentationAnchor {
        ASPresentationAnchor()   // return your key window's anchor in a real app
    }
}
```

**Silent refresh** — before the access token expires, mint a new one with the
refresh token (no browser):

```swift
func refresh(refreshToken: String) async throws -> TokenResponse {
    var req = URLRequest(url: URL(string: TraxAuth.token)!)
    req.httpMethod = "POST"
    req.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
    let body = [
        "grant_type": "refresh_token",
        "client_id": TraxAuth.clientId,
        "refresh_token": refreshToken,
    ].map { "\($0)=\($1)" }.joined(separator: "&")
    req.httpBody = body.data(using: .utf8)
    let (data, _) = try await URLSession.shared.data(for: req)
    return try JSONDecoder().decode(TokenResponse.self, from: data)
}
```

**Store tokens in the Keychain** (never `UserDefaults` / source):

```swift
import Security

enum Keychain {
    static func set(_ value: String, for key: String) {
        let data = Data(value.utf8)
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrAccount as String: key,
            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
        ]
        SecItemDelete(query as CFDictionary)
        var add = query; add[kSecValueData as String] = data
        SecItemAdd(add as CFDictionary, nil)
    }

    static func get(_ key: String) -> String? {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrAccount as String: key,
            kSecReturnData as String: true,
        ]
        var out: AnyObject?
        guard SecItemCopyMatching(query as CFDictionary, &out) == errSecSuccess,
              let data = out as? Data else { return nil }
        return String(data: data, encoding: .utf8)
    }
}
```

**Log out** — clear stored tokens and, to end the IdP session, open the
end-session endpoint (`\(TraxAuth.endSession)?client_id=…&post_logout_redirect_uri=…`).

The `access_token` you get back is a JWT — send it as
`Authorization: Bearer <access_token>` on your `/v1` calls (this is the
credential `/v1` accepts as the user; the media plane's SRT/WHIP/WHEP surfaces
use a separate session token — see
[the two credential systems](/reference/authentication)). Read the
[note on token type and audience](/reference/authentication#using-the-token-at-v1)
before you swap clients: `/v1` validates the JWT against Zitadel and does not yet
check the audience claim.

## 4. First call

```swift
import TraxAPI
import Foundation

// The generated client exposes the base path; set the auth header globally.
TraxAPIAPI.basePath = "https://api-dev.traxstreaming.live"
TraxAPIAPI.customHeaders = [
    "Authorization": "Bearer \(apiKeyFromKeychain)"   // or the user's OAuth token
]

// List your studios (requires the studios:read scope)
do {
    let page = try await StudiosAPI.listStudios(limit: 50)
    for studio in page.data {
        print(studio.id, studio.name)
    }
    if let cursor = page.nextCursor {
        // pass `cursor:` to fetch the next page — see /reference/pagination
        _ = cursor
    }
} catch {
    // Errors share one envelope: { error: { code, message, requestId } }.
    // Decode the response body to read error.code and branch on it.
    print("request failed:", error)
}
```

Generated method and model names (`listStudios`, `StudiosAPI`, `nextCursor`)
come straight from the spec's `operationId`s and schemas, so they'll match what
you see in the [API reference](/reference/api/v1).

## Next

- [Errors](/reference/errors) — decode `error.code`; retry only transient codes.
- [Pagination](/reference/pagination) · [Rate limits](/reference/rate-limits).
- [Build a client](/guides/build-a-client) — OAuth (PKCE) login, plus WebSocket
  control and WebRTC (WHIP/WHEP) media for a full producing app on iOS.


<!-- guides/set-the-output-format -->


# Set the program resolution and frame rate

Two calls: read what a studio is set to composite and encode at, and change it.

> **Which host.** These endpoints are on dev only for now:
> `https://api-dev.traxstreaming.live/v1` with a dev key. This page will say so
> when they reach production.

1. **`GET /v1/studios/{id}/output`** — the format in three parts.
2. **`PATCH /v1/studios/{id}/output`** — set the resolution and/or frame rate.

Read the GET first, and read all of it. The response deliberately does not
collapse into one number, because one number would be wrong for most studios.

## Three answers, not one

```json
{
  "studioId": "…",
  "selected":  { "width": 2560, "height": 1440, "fpsNum": 60, "fpsDen": 1, "fps": 60 },
  "effective": { "width": 1920, "height": 1080, "fpsNum": 60, "fpsDen": 1, "fps": 60 },
  "caps": {
    "maxWidth": 1920,
    "maxHeight": 1080,
    "cappedBy": "twitch",
    "supported": [
      { "width": 1280, "height": 720,  "available": true,  "status": "available" },
      { "width": 1920, "height": 1080, "available": true,  "status": "available" },
      { "width": 2560, "height": 1440, "available": true,  "status": "available" },
      { "width": 3840, "height": 2160, "available": false, "status": "coming_soon" }
    ],
    "supportedFrameRates": [ { "num": 60000, "den": 1001, "fps": 59.94 }, "…" ]
  },
  "codec": "h264",
  "targetBitrateKbps": 6000,
  "appliesToNextGoLive": true
}
```

`selected` is what the operator picked. `effective` is what the next go-live
will actually run. They differ here because Twitch ingests 1080p, and this
studio has a Twitch destination enabled — so a 1440p selection airs at 1080p.
`caps.cappedBy` names the platform responsible; it is an **empty string** when
nothing is capping, which is the field to check rather than comparing
`maxWidth` against the ladder top.

**Show a user `effective`** when answering "what am I streaming at". `selected`
is their intent and can legitimately be higher than what airs today.

The cap is a fact about the studio's destination set right now, not a rule.
Disable Twitch and the same selection airs at 1440p with no further write.

## Frame rate is a rational

`fpsNum` / `fpsDen`, not a decimal. 59.94 is exactly 60000/1001, and rounding
it to 59.94 or 60 produces drift the encoder cannot correct. The `fps` field is
the decimal rendering for display; there is no way to write it, and sending one
is a 400.

The accepted rates:

| num / den | reads as |
| --- | --- |
| 24000 / 1001 | 23.976 |
| 24 / 1 | 24 |
| 25 / 1 | 25 |
| 30000 / 1001 | 29.97 |
| 30 / 1 | 30 |
| 50 / 1 | 50 |
| 60000 / 1001 | 59.94 |
| 60 / 1 | 60 |

Read them from `caps.supportedFrameRates` rather than hardcoding this table.

## Setting it

```bash
curl -X PATCH https://api-dev.traxstreaming.live/v1/studios/$STUDIO/output \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"width":1920,"height":1080,"fpsNum":60000,"fpsDen":1001}'
```

A PATCH: send only what you are changing. A resolution-only body leaves the
frame rate exactly where it was, which is what lets a phone drop a studio to
720p without disturbing a 59.94 that someone chose deliberately.

**The pairs are pairs.** `width` and `height` move together and `fpsNum` and
`fpsDen` move together; sending half of either is a 400 naming the field. Half a
resolution is not a resolution, and a numerator with no denominator is not a
frame rate.

The response is the whole re-resolved view — the same shape GET returns — so
you never have to model the cap chain yourself to know what your change did.

## It rejects; it does not clamp

An off-ladder resolution is a 400 that names the field and lists what is
allowed:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "width: 1600x900 is not a supported program resolution; supported: 1280x720, 1920x1080, 2560x1440"
  }
}
```

This is the point of the endpoint. Offer `caps.supported` in your picker and
you will never see this error; construct a resolution yourself and you will
find out immediately rather than at the next go-live.

## Coming soon resolutions

Each rung in `caps.supported` carries an `available` flag and a `status`
string. A rung with `"available": false` (`"status": "coming_soon"`) is part of
the ladder but not offered yet — **4K (3840x2160) reads as coming soon today.**
Render it in your picker greyed out rather than hiding it, and do not let it be
selected.

Selecting a coming-soon resolution is rejected the same way an off-ladder one
is — a 400 that names the reason:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "width: 4K (3840x2160) is coming soon and not yet available"
  }
}
```

While 4K is coming soon it is excluded from the destination soft-cap too, so
`caps.maxWidth` tops out at 2560x1440 even with only 4K-capable destinations
(e.g. YouTube) enabled. When 4K ships, its rung flips to `"available": true`
and the cap lifts with no change to your integration.

The one thing reported rather than enforced is the destination cap. Setting
1440p on a Twitch-only studio **succeeds**, and the response tells you it will
air at 1080p. Refusing it would delete the operator's intent to punish a
condition that lifts the moment they disable Twitch. (This is distinct from the
coming-soon gate above, which IS enforced on write — a coming-soon resolution
is a roadmap gap, not a per-destination condition.)

## When it takes effect

`appliesToNextGoLive` is always `true`, and it is in the payload rather than
only in this page because it is easy to get wrong. The encoder does not
renegotiate resolution or frame rate mid-session: a studio that is live right
now keeps the format it started with until it goes offline and live again.

Patching a live studio is safe — it persists and does not disturb the session on
air — but it will not change what viewers are watching until the next go-live.
If your UI can be open during a broadcast, say so there.

## Scopes

`studios:read` to read, `studios:write` to change. Both are in the default
scope set for a new key.

The format rides the studio scopes rather than having a pair of its own because
changing it does not move what is on air — it takes effect at the next go-live,
the same blast radius renaming a studio has. That is a different power from
`canvas:write`, which puts a tile in front of every viewer the instant it lands.

## Related

- [Control the canvas from your app](/guides/control-the-canvas) — the canvas
  read reports the same format as `output`, in the same shape. The canvas
  coordinate space is a fixed 1920x1080 for every studio and is **not** the
  broadcast resolution; scale your miniature by the canvas and label the stream
  by the output.


<!-- guides/media-library -->


# Use the media library from your app

Your app has a file — a sting, a lower-third still, a music bed, a pre-recorded
segment — and it needs to end up on air. This guide is the whole path: get the
bytes into TRaX, watch them become usable, put them on a studio's canvas, and
take them away again.

> **Which host.** These endpoints are on dev only for now:
> `https://api-dev.traxstreaming.live/v1` with a dev key. This page will say so
> when they reach production.

The shape to hold in your head is **three steps, not one**:

1. **`POST /v1/media`** — tell us what is coming. You get back an asset id and a
   plan for pushing the bytes.
2. **You upload the bytes** — straight to storage, not through this API.
3. **`POST /v1/media/{assetId}/complete`** — tell us they landed.

Step 3 is the one that gets skipped, and skipping it is the most expensive
mistake on this page. An upload that stops after step 2 has produced *nothing*:
the asset sits in `UPLOADING` forever, it counts against your user's storage,
and it can be attached to nothing. If you take one thing from this guide, take
that.

## Before you start

- An API key holding **`media:read`** to browse and **`media:write`** to upload
  or delete. `media:write` includes read. Create one under **Developer → API
  keys** in your account. Neither scope is in the default set — tick them when
  you create the key. `media:read` hands out a signed download URL for the
  owner's files, so a key created without choosing scopes does not carry it.
- To put a file on a studio, you also need **`sources:write`**.

Set them up once:

```bash
export TRAX_API_KEY=sk_live_...
export TRAX_API=https://api-dev.traxstreaming.live/v1
```

## Uploading a small file

```bash
curl -s -X POST $TRAX_API/media \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "sting.mp4", "contentType": "video/mp4", "byteSize": 4210688 }'
```

```json
{
  "assetId": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "mode": "single",
  "uploadUrl": "https://s3.../video/0f8fad5b...?X-Amz-Signature=...",
  "objectKey": "video/0f8fad5b-d9cb-469f-a165-70867728950e",
  "kind": "video"
}
```

`byteSize` must be the real size. It is checked against the remaining storage
allowance *before* a URL is issued, which is why an upload that cannot fit is
refused here rather than after you have spent a user's data plan on it.

PUT the file at `uploadUrl`, then complete:

```bash
curl -s -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @sting.mp4

curl -s -X POST $TRAX_API/media/$ASSET_ID/complete \
  -H "Authorization: Bearer $TRAX_API_KEY"
```

No body on `/complete` for a single-file upload. The response is the asset.

`uploadUrl` is a **credential**, not an address: anyone holding it can write to
that object until it expires. Keychain, not log file, not crash report.

## Uploading a big file

**Read `mode` before anything else.** Over a threshold, `POST /v1/media` returns
no `uploadUrl` at all — it returns a plan:

```json
{
  "assetId": "1c2d...",
  "mode": "multipart",
  "partBytes": 67108864,
  "parts": [
    { "partNumber": 1, "offset": 0,         "byteSize": 67108864, "url": "https://s3.../?partNumber=1&..." },
    { "partNumber": 2, "offset": 67108864,  "byteSize": 67108864, "url": "https://s3.../?partNumber=2&..." },
    { "partNumber": 3, "offset": 134217728, "byteSize": 22020096, "url": "https://s3.../?partNumber=3&..." }
  ],
  "kind": "video"
}
```

Why it exists: every request to our storage host crosses a CDN edge that caps a
**single request body at 100 MB**, and it enforces that at the edge. A 150 MB
PUT does not slow down — it dies with a `413` after about two megabytes, from a
server that is not ours. Parts are sized to stay under that cap, so what limits
a file is your user's storage allowance, not the network.

Then:

- **PUT each part's slice at its own URL.** Slice by the plan's `offset` and
  `byteSize` — never by a part size of your own. The server may have grown the
  part size to keep the plan under the storage layer's part-count ceiling, so
  the plan is the only correct description of how the file is cut.
- **Upload parts in any order, a few at a time.** Three in flight is a good
  number; more mostly buys congestion. Give each part two or three retries — a
  failed part is a failed part, not a failed upload.
- **Keep the `ETag` response header** each PUT returns. Send them back on
  `/complete`.

```bash
curl -s -X POST $TRAX_API/media/$ASSET_ID/complete \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "parts": [
        { "partNumber": 1, "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"" },
        { "partNumber": 2, "etag": "\"a1b2c3d4e5f60718293a4b5c6d7e8f90\"" },
        { "partNumber": 3, "etag": "\"0f1e2d3c4b5a69788796a5b4c3d2e1f0\"" }
      ] }'
```

Order does not matter — the server sorts, because parts finish out of order
when several are in flight. **Completeness does.** A partial list is an error,
not a partial completion.

**If you cannot read the ETag header**, which is the normal case in a browser
unless the storage host exposes it through CORS, send no body at all. The server
recovers every ETag from storage itself. That fallback is why a missing ETag is
an inconvenience rather than a dead end.

`/complete` is **idempotent**. If the response never arrives, call it again —
never re-upload.

## Watching it become usable

```bash
curl -s $TRAX_API/media/$ASSET_ID -H "Authorization: Bearer $TRAX_API_KEY"
```

```json
{
  "assetId": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "kind": "video",
  "filename": "sting.mp4",
  "status": "READY",
  "sizeBytes": 4210688,
  "durationSeconds": 8.4,
  "width": 1920,
  "height": 1080,
  "thumbnailUrl": "https://s3.../thumb/...",
  "downloadUrl": "https://s3.../video/...",
  "createdAt": "2026-08-23T00:12:00Z",
  "updatedAt": "2026-08-23T00:12:09Z"
}
```

Poll this until `status` reads `READY`. A large file is assembled and probed
after `/complete` returns, so READY can lag it by a moment. Every second or two
is plenty, and then stop.

`sizeBytes` is what actually landed in storage, not what you declared. The
duration and dimensions come from probing the file; treat them as picker
metadata rather than a guarantee, and expect `0` for a still image or a file we
could not read.

`thumbnailUrl` and `downloadUrl` **expire**. Fetch them when you render and
throw them away. A URL you saved in your database works all through testing and
403s a day later — this is the single most common way this API gets used wrong.
`thumbnailUrl` is also best-effort even on a READY asset: audio files and most
images do not have one, which is a kind icon on your side, not a failure.

## Browsing the library

```bash
curl -s "$TRAX_API/media?limit=50" -H "Authorization: Bearer $TRAX_API_KEY"
```

```json
{
  "data": [
    { "id": "0f8fad5b...", "filename": "sting.mp4", "kind": "video", "byteSize": 4210688,
      "status": "READY", "durationSeconds": 8.4, "width": 1920, "height": 1080,
      "thumbnailUrl": "https://s3.../thumb/..." }
  ],
  "nextCursor": "MGY4ZmFkNWI",
  "quotaUsedBytes": 418447360,
  "quotaLimitBytes": 2147483648
}
```

The library belongs to the **user**, not to a studio, so nothing here names one.
Rows carry a thumbnail so you can draw a grid, and deliberately carry no
download URL — reading a file is a different thing from knowing it exists, and
list responses are what end up in logs. Read one asset when you need the file.

`quotaUsedBytes` / `quotaLimitBytes` ride along so you can show usage and refuse
an over-large pick on the device, instead of discovering the ceiling when an
upload comes back `402`.

## Putting it on a studio

Create a source and pass the asset id. **Do not pass `downloadUrl`.**

```bash
curl -s -X POST $TRAX_API/studios/$STUDIO/sources \
  -H "Authorization: Bearer $TRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Opening sting", "type": "video-file", "mediaAssetId": "'$ASSET_ID'" }'
```

Use the type that matches the file: `video-file`, `image`, `audio-file`, or the
generic `media`.

The reason to pass an id rather than a link: the URL your phone can fetch and
the URL the encoder can fetch are **different signatures of the same object**,
and both expire. Pass the id and the server resolves the one the encoder needs
and re-mints it whenever it goes stale. An asset-backed source keeps working
next month; a source built from a pasted `downloadUrl` stops working tomorrow.

`url` and `mediaAssetId` are mutually exclusive. Sending both is a `400` rather
than a precedence rule you would have to remember.

## Cancelling and deleting

Two different operations, and they are not interchangeable.

**Cancel an upload in flight** — the user backed out, or it failed past
retrying:

```bash
curl -s -X POST $TRAX_API/media/$ASSET_ID/abort \
  -H "Authorization: Bearer $TRAX_API_KEY"
```

Do this. An abandoned upload does not show up in `GET /v1/media` — that lists
finished assets — and it still occupies the storage allowance, so an app that
abandons uploads without aborting them slowly locks its own user out of
uploading anything at all. There is a server-side sweeper, but it works in
hours, not minutes.

`/abort` is idempotent, and it refuses a **finished** asset with `409`. That is
deliberate: a mistimed cancel must not become data loss.

**Delete finished content:**

```bash
curl -s -X DELETE $TRAX_API/media/$ASSET_ID \
  -H "Authorization: Bearer $TRAX_API_KEY"
```

Permanent — the file, its thumbnail, and the storage it held.

It is **refused with `409` while any studio source still uses the asset**, and
the message says how many. Take that seriously: a source pointing at a deleted
file shows a permanent "unavailable" card, and if that studio is live, the
encoder's next read on the file fails and the input drops to a placeholder in
the middle of the show. Delete the sources first.

## What we accept

| Kind | Content types |
|---|---|
| video | `video/mp4`, `video/webm`, `video/quicktime` |
| image | `image/jpeg`, `image/png`, `image/webp`, `image/gif` |
| audio | `audio/mpeg`, `audio/wav`, `audio/ogg`, `audio/aac` |

`contentType` decides the asset's `kind`, which decides how it behaves on a
canvas — a looping video, a still, an audio-only bed. Send the wrong one and
you get an asset that misbehaves in a way nothing later will explain.

## When it does not work

| Response | What happened |
|---|---|
| `400 invalid_request` | An unsupported `contentType`, a `byteSize` of zero or less, a partial part list, or a `mediaAssetId` that is not a READY asset of yours. The message says which |
| `402 storage_quota_exceeded` | The library is full, or this file is larger than any single upload this account may hold. Nothing is wrong with the request — free space or change the plan. The message names which ceiling |
| `403 insufficient_scope` | The key lacks `media:read` (to browse) or `media:write` (to upload or delete). The `requiredScope` field names it |
| `404 not_found` | No such asset, **or** it belongs to someone else. The two are deliberately indistinguishable |
| `409 conflict` | You aborted an upload that already finished, or deleted an asset a studio source still uses |
| `503 unavailable` | Writes are disabled on this deployment, or the service is briefly unreachable. Retry |

## Where to go next

1. [Drive the canvas](/guides/drive-the-canvas) — arrange the source you just
   added.
2. [Control the canvas over /v1](/guides/control-the-canvas) — put a library
   asset on the canvas, then move it.
3. [Control the mixer from your app](/guides/control-the-mixer) — for an audio
   bed, the level is the next thing you want.
4. [The /v1 reference](/reference/public-api) — every endpoint and scope.


<!-- guides/sdk-kotlin -->


# SDK quickstart: Kotlin (Android)

Generate a typed Kotlin client for the `/v1` Developer API from its OpenAPI spec
and make your first call.

> No hand-written Kotlin SDK is published yet — you generate one from the live
> spec. An official SDK is a [roadmap](/reference/roadmap) item.
>
> **Which credential?** A shared **API key** (`sk_live_…`) suits your own
> automation and server-side jobs. A **first-party Android app a user logs into**
> should authenticate **as that user** with OAuth 2.0 + PKCE and send the user's
> token — see [Build a client](/guides/build-a-client). The steps below use an
> API key; swap in the user's bearer token for a logged-in app.

## 1. Get the spec

```
https://api-dev.traxstreaming.live/v1/openapi.json
```

## 2. Generate a typed client

Use [`openapi-generator`](https://openapi-generator.tech/) with the
`kotlin` generator (Retrofit2 + coroutines is a good default for Android):

```bash
npm i -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
  -i https://api-dev.traxstreaming.live/v1/openapi.json \
  -g kotlin \
  --additional-properties=library=jvm-retrofit2,useCoroutines=true,packageName=live.traxstreaming.api \
  -o ./trax-client-kotlin
```

Add the generated module to your Gradle build (`include(":trax-client-kotlin")`
in `settings.gradle`, then depend on it from your app module).

## 3. Authenticate

**Building an app a user logs into?** Sign them in with OAuth 2.0 + PKCE and
send *their* token — jump to
[Sign the user in (OIDC + PKCE)](#sign-the-user-in-oidc-pkce) below.

**Automating your own account?** Create an API key from your account's
**Developer / API Keys** screen and copy the `sk_live_…` secret once. Store it
with **EncryptedSharedPreferences** or the Android Keystore — never hardcoded
in the APK or in `strings.xml`.

## Sign the user in (OIDC + PKCE)

A first-party Android app authenticates the user against the TRaX identity
provider with the **Authorization-Code flow + PKCE**, then calls `/v1` with the
user's access token. The user signs in (password, MFA / passkey) on the IdP's
**hosted login page** in a **Custom Tab** — never in your UI. See
[Authentication → User login for mobile & native
apps](/reference/authentication#user-login-for-mobile-and-native-apps-oidc-pkce)
for the concept; this is the concrete Android.

**Use [AppAuth-Android](https://github.com/openid/AppAuth-Android)** — the
OpenID Foundation's certified client. It drives the Custom Tab, generates the
PKCE pair, and does the token exchange + refresh for you.

```kotlin
// build.gradle.kts
implementation("net.openid:appauth:0.11.1")
implementation("androidx.security:security-crypto:1.1.0-alpha06") // EncryptedSharedPreferences
```

**Config** (dev shown; swap the issuer + `CLIENT_ID` for production):

```kotlin
object TraxAuth {
    // Dev IdP. Production: https://auth.traxstreaming.live
    const val ISSUER = "https://auth-dev.traxstreaming.live"
    const val AUTHORIZE = "$ISSUER/oauth/v2/authorize"
    const val TOKEN = "$ISSUER/oauth/v2/token"
    const val END_SESSION = "$ISSUER/oidc/v1/end_session"

    // Public native client (no secret). Dev value; production has its own id.
    const val CLIENT_ID = "385862192278274086"

    // Must match a redirect URI registered on the client, exactly.
    const val REDIRECT_URI = "live.traxstreaming.android://oauth/callback"

    const val SCOPE = "openid profile email offline_access"
    const val API_BASE = "https://api-dev.traxstreaming.live"
}
```

Register the redirect scheme so the Custom Tab can hand the code back — either
via AppAuth's manifest placeholder, or a verified App Link:

```kotlin
// build.gradle.kts — app module
android {
    defaultConfig {
        manifestPlaceholders["appAuthRedirectScheme"] = "live.traxstreaming.android"
    }
}
```

**The login round-trip** — launch the hosted page, then exchange the returned
code. AppAuth generates and tracks the PKCE `code_verifier`/`code_challenge`
internally, so you never handle them by hand:

```kotlin
import android.content.Intent
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import net.openid.appauth.*
import kotlin.coroutines.resume
import kotlin.coroutines.suspendCoroutine

class LoginActivity : AppCompatActivity() {

    private val authService by lazy { AuthorizationService(this) }

    private val serviceConfig = AuthorizationServiceConfiguration(
        Uri.parse(TraxAuth.AUTHORIZE),
        Uri.parse(TraxAuth.TOKEN),
        /* registrationEndpoint = */ null,
        Uri.parse(TraxAuth.END_SESSION),
    )

    // Registered launcher that receives the Custom Tab result.
    private val authLauncher =
        registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
            val resp = AuthorizationResponse.fromIntent(result.data!!)
            val ex = AuthorizationException.fromIntent(result.data)
            when {
                resp != null -> exchange(resp)               // got ?code — swap for tokens
                else -> onLoginFailed(ex)
            }
        }

    fun startLogin() {
        val request = AuthorizationRequest.Builder(
            serviceConfig,
            TraxAuth.CLIENT_ID,
            ResponseTypeValues.CODE,
            Uri.parse(TraxAuth.REDIRECT_URI),
        )
            .setScope(TraxAuth.SCOPE)                          // includes offline_access
            .build()                                          // PKCE S256 added automatically
        authLauncher.launch(authService.getAuthorizationRequestIntent(request))
    }

    private fun exchange(resp: AuthorizationResponse) {
        // resp.createTokenExchangeRequest() carries the code_verifier for PKCE.
        authService.performTokenRequest(resp.createTokenExchangeRequest()) { tokens, ex ->
            if (tokens != null) {
                TokenStore(this).save(tokens.accessToken!!, tokens.refreshToken)
                onLoggedIn(tokens.accessToken!!)
            } else {
                onLoginFailed(ex)
            }
        }
    }

    override fun onDestroy() {
        authService.dispose()
        super.onDestroy()
    }
}
```

**Silent refresh** — before the access token expires, mint a new one with the
refresh token (no Custom Tab), as a coroutine:

```kotlin
suspend fun refresh(authService: AuthorizationService, refreshToken: String): String =
    suspendCoroutine { cont ->
        val request = TokenRequest.Builder(serviceConfig, TraxAuth.CLIENT_ID)
            .setGrantType(GrantTypeValues.REFRESH_TOKEN)
            .setRefreshToken(refreshToken)
            .build()
        authService.performTokenRequest(request) { tokens, ex ->
            if (tokens?.accessToken != null) cont.resume(tokens.accessToken!!)
            else cont.resumeWith(Result.failure(ex ?: RuntimeException("refresh failed")))
        }
    }
```

**Store tokens with EncryptedSharedPreferences** (never plain `SharedPreferences`
or source):

```kotlin
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey

class TokenStore(context: Context) {
    private val prefs = EncryptedSharedPreferences.create(
        context,
        "trax_tokens",
        MasterKey.Builder(context).setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build(),
        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
    )

    fun save(accessToken: String, refreshToken: String?) = prefs.edit()
        .putString("access", accessToken)
        .putString("refresh", refreshToken)
        .apply()

    fun access(): String? = prefs.getString("access", null)
    fun refresh(): String? = prefs.getString("refresh", null)
    fun clear() = prefs.edit().clear().apply()
}
```

**Log out** — clear stored tokens and, to end the IdP session, launch the
end-session endpoint (AppAuth's `EndSessionRequest`, or open
`${TraxAuth.END_SESSION}?client_id=…&post_logout_redirect_uri=…` in a Custom Tab).

The access token AppAuth hands you is a JWT — attach it as
`Authorization: Bearer <access_token>` on your `/v1` calls (see the OkHttp
interceptor in [step 4](#4-first-call)). This is the credential `/v1` accepts as
the user; the media plane's SRT/WHIP/WHEP surfaces use a separate session token
— see [the two credential systems](/reference/authentication). Read the
[note on token type and audience](/reference/authentication#using-the-token-at-v1)
before you swap clients: `/v1` validates the JWT against Zitadel and does not yet
check the audience claim.

> Prefer to hand-roll it? You can drive a `androidx.browser` **Custom Tab** to
> the authorize URL yourself, generate the PKCE pair, and POST the token
> exchange with OkHttp — the same HTTP calls the Swift guide shows. AppAuth is
> recommended because it gets the redirect handling, PKCE, and refresh right.

## 4. First call

Add the bearer token with an OkHttp interceptor, then call the generated API:

```kotlin
import live.traxstreaming.api.apis.StudiosApi
import okhttp3.OkHttpClient
import retrofit2.Retrofit
import retrofit2.converter.moshi.MoshiConverterFactory

val http = OkHttpClient.Builder()
    .addInterceptor { chain ->
        val req = chain.request().newBuilder()
            .header("Authorization", "Bearer $apiKey")   // or the user's OAuth token
            .build()
        chain.proceed(req)
    }
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://api-dev.traxstreaming.live/")
    .client(http)
    .addConverterFactory(MoshiConverterFactory.create())
    .build()

val studios = retrofit.create(StudiosApi::class.java)

// List your studios (requires the studios:read scope)
val page = studios.listStudios(limit = 50)      // suspend fun (coroutines)
page.data.forEach { println("${it.id} ${it.name}") }
page.nextCursor?.let { cursor ->
    // pass `cursor` to fetch the next page — see /reference/pagination
}
```

Generated method and model names (`listStudios`, `StudiosApi`, `nextCursor`)
come from the spec's `operationId`s and schemas, matching the
[API reference](/reference/api/v1). On a non-2xx response, decode the error body
— it's the one envelope `{ error: { code, message, requestId } }`.

## Next

- [Errors](/reference/errors) — branch on `error.code`; retry only transient codes.
- [Pagination](/reference/pagination) · [Rate limits](/reference/rate-limits).
- [Build a client](/guides/build-a-client) — OAuth (PKCE) login, WebSocket
  control, and WebRTC (WHIP/WHEP) media for a full producing app on Android.


<!-- guides/byo-storage-setup -->


# Bring your own storage (BYO S3-compatible bucket)

TRaX can use **your** S3-compatible bucket — AWS S3, Cloudflare R2,
Backblaze B2, self-hosted MinIO — as a media source and as the destination
for [cloud recordings](/guides/cloud-recording). Your files stay in your
bucket, under your keys, under your retention rules. TRaX accesses the
bucket **server-side only**: credentials are sent write-only, encrypted at
rest, never echoed back (you'll only ever see the last 4 characters of the
access key), and never reach the browser.

Connecting a bucket, updating it, verifying it, and importing files from it
require an **active subscription**. Browsing your existing configs and
removing them always works.

Per-provider recipes (exact endpoint / region / key formats) are in
[BYO storage: provider recipes](/guides/byo-storage-providers).

## Where to set it up

- **Studio Settings → Storage** — add, edit, re-verify, remove buckets.
- **Media library → Add storage** — the same create form, inline, so you
  can connect a bucket and browse it without leaving the picker.

Only the **studio owner** can manage external storage.

## The form fields

| Field | Required | What it is |
|---|---|---|
| Name | yes | A label for you ("My R2 bucket"). |
| Endpoint | yes | The S3 API endpoint, e.g. `https://s3.us-east-1.amazonaws.com`. Bare host or `https://` URL — **no path, no query**. `http://` is rejected. |
| Region | no | The bucket's region, used for request signing. Leave blank only if your provider ignores region (blank is signed as `us-east-1`). |
| Bucket | yes | The bucket name. |
| Prefix | no | A key prefix that jails everything TRaX does — browsing, imports, and recordings all stay under it. Recommended: give TRaX its own prefix (e.g. `trax/`). |
| Force path-style | no (default **on**) | Addresses objects as `endpoint/bucket/key` instead of `bucket.endpoint/key`. Required for MinIO and most self-hosted setups; harmless for AWS/R2/B2. |
| Access key ID | yes | Sent write-only. Shown later only as `••••` + last 4 characters. |
| Secret access key | yes | Sent write-only, never displayed again. |

To rotate credentials, edit the config and enter **both** keys again —
leaving them blank keeps the existing pair. A lone access key without its
secret is rejected.

## Endpoint requirements (why some endpoints are rejected)

TRaX dials your endpoint from its servers, so endpoints get the same
network hardening as any user-supplied URL:

- **HTTPS only.** Plaintext `http://` endpoints are rejected.
- **Publicly resolvable and publicly routable.** Private, loopback,
  link-local, and carrier-NAT IP addresses are rejected — both as literal
  IPs in the endpoint and at connection time if a DNS name resolves to one.
- **Fully-qualified hostnames only.** Bare single-label names
  (`minio`, `nas`) are rejected.

Practical consequence: a **self-hosted MinIO (or similar) must be reachable
from the internet** on a public DNS name with a valid TLS certificate. A
bucket that only exists on your LAN or behind a VPN cannot be connected.
See the [MinIO recipe](/guides/byo-storage-providers#minio-self-hosted).

## Minimal IAM policy

Scope TRaX's key to one bucket (and one prefix, if you set one). This is
the complete set of permissions TRaX uses — nothing else is needed:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TraxObjects",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET/trax/*"
    },
    {
      "Sid": "TraxList",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR-BUCKET",
      "Condition": { "StringLike": { "s3:prefix": "trax/*" } }
    }
  ]
}
```

If you don't use a prefix, change the object resource to
`arn:aws:s3:::YOUR-BUCKET/*` and drop the `Condition`.

What each permission is for:

| Permission | Used for |
|---|---|
| `s3:GetObject` | Reading files you import (playback, thumbnails, going live with them) and reading recording segments during processing. |
| `s3:PutObject` | The verification probe, recording segment uploads, processed recording output, and files you move into the bucket. |
| `s3:DeleteObject` | Cleaning up the tiny verification probe object, and the delete half of an explicit "Move". **Never used on your recordings or library files otherwise.** |
| `s3:AbortMultipartUpload` | Cleaning up interrupted large streaming uploads during recording processing. |
| `s3:ListBucket` | Browsing the bucket in the media picker. |

A **read-only key** (`s3:GetObject` + `s3:ListBucket`) also works: the
config verifies as **Forbidden** with the note "usable as a read-only
library" — you can browse and import, but not record or move files in.

## Your provider must support S3 multipart upload

Anything large TRaX writes into your bucket goes up as an S3 multipart upload:
recording segments, the processed recording output, and files copied in from
the TRaX library. Your provider has to implement the multipart operations the
way the S3 API specifies them:

- `CreateMultipartUpload`
- `UploadPart`
- `CompleteMultipartUpload`
- `AbortMultipartUpload`
- `ListMultipartUploads`

AWS S3, Cloudflare R2, Backblaze B2 and MinIO all do. A cut-down or homegrown
S3 façade may not, and it will fail on the first file too big for a single
request rather than at save time: the verification probe writes one small
object, so it cannot tell you whether multipart works.

`s3:AbortMultipartUpload` is in the [IAM policy](#minimal-iam-policy) above
for the same reason. Without it, an upload interrupted halfway leaves parts
sitting in your bucket that nothing can clean up, and most providers bill for
them.

## CORS: not required, but expose `ETag`

You do **not** need CORS to connect a bucket. Every operation that needs your
credentials runs server-side, and the browser only ever consumes short-lived
presigned links through regular media playback and download — neither of
which is subject to CORS.

If your bucket has a CORS policy, the one thing worth adding is `ETag` in
`ExposeHeaders`:

```json
"ExposeHeaders": ["ETag"]
```

A browser uploading in parts reads each part's `ETag` off the `PUT` response
and sends the list back to finish the upload. A bucket that hides `ETag` hands
it `null` instead. That is **recommended, not required** — TRaX recovers the
part list server-side with `ListObjectParts` when the browser can't report it,
so the upload still completes either way. Exposing the header just saves the
extra round trip, and it is the only response header any browser-side S3 flow
needs.

## The verification probe

On every save (and whenever you hit **Re-verify**) TRaX runs a real
round-trip against your bucket, bounded at 10 seconds:

1. `PUT` a small marker object at `<prefix>/._trax/probe-<random-id>`
2. `GET` it back and compare the bytes
3. `DELETE` it

A failed probe **still saves the config** — it just gets a non-verified
status pill so you can fix the policy/DNS/keys and hit Re-verify.

## Status pills

| Pill | Meaning | What to do |
|---|---|---|
| **Verified** | Probe succeeded. Everything works, including recording. | Nothing. |
| **Unverified** | Saved but not yet successfully probed. | Hit Re-verify. |
| **Unreachable** | Endpoint/bucket couldn't be reached, doesn't exist, or the request was rejected before auth. | See the troubleshooting table below. |
| **Invalid credentials** | The provider rejected the key (unknown key ID or bad signature). | Re-enter both keys; check for copy/paste whitespace. |
| **Forbidden** | The key authenticated but was denied. If reads work, the pill notes the bucket is usable as a **read-only library**. | Widen the key's policy (see the IAM policy above) if you want recording/move. |

Statuses are **event-driven**: a real operation failing later (a browse, an
import) flips the pill; the next successful operation self-heals it back to
Verified. **Re-verify** re-runs the full probe on demand — the pill's
tooltip carries the exact provider error.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Unreachable, detail mentions a region or `AuthorizationHeaderMalformed` | Region field doesn't match the bucket's real region (blank = signed as `us-east-1`). | Set the Region field to the bucket's region (AWS), or `auto` (R2), or the region embedded in the endpoint (B2). |
| Unreachable, `NoSuchBucket` | Bucket name typo — or path-style mismatch making the provider look up the wrong name. | Check the bucket name; toggle **Force path-style** to match your provider (on for MinIO, fine either way for AWS/R2/B2). |
| Invalid credentials, `SignatureDoesNotMatch` | Wrong secret key — or (self-hosted) the storage server's clock is skewed, which breaks request signing. | Re-enter both keys. On self-hosted servers, sync the clock (NTP). |
| "endpoint host … is not allowed" when saving | The endpoint is a private/LAN address, a bare hostname, or `http://`. | Use a public HTTPS endpoint — see [endpoint requirements](#endpoint-requirements-why-some-endpoints-are-rejected). |
| Unreachable, "bucket unreachable — check endpoint, region, and network" | DNS failure, TLS failure, timeout — or a public DNS name that resolves to a private IP (blocked at connect time). | Verify the endpoint resolves publicly and serves valid TLS; check firewall allows inbound from the internet. |
| Forbidden on save, but browsing works | Key has read permissions only. | Fine for a media library. Add write permissions for recording — see the IAM policy. |

## Importing and moving files

- **Browsing is live** — the picker lists your bucket directly (media file
  types only: mp4, webm, mov, jpg/jpeg, png, webp, gif, mp3, wav, ogg, aac;
  up to 5 GiB per file). Nothing is copied or mirrored.
- **Importing** a file registers it in your TRaX media library — the bytes
  stay in your bucket. Deleting an imported item from the library never
  deletes the object in your bucket.
- There is **no direct upload into your bucket through TRaX yet**. To get a
  new file into your bucket, either upload it there yourself with your own
  tools and import it, or upload it to the TRaX library and use
  **Move/Copy** in the media library to transfer it across. The library
  upload takes large files without a size surprise — it splits them into
  parts and shows byte-level progress — up to your library quota, and the
  Move/Copy across to your bucket then runs server-side. Once the file is in
  your bucket it no longer counts against that quota.

## Removing a config

Removing a bucket config never touches the bucket's contents. If imported
library items still reference it, TRaX warns you how many will stop
resolving and asks you to confirm.

## Next

- [Provider recipes: AWS S3, R2, B2, MinIO](/guides/byo-storage-providers)
- [Cloud recording to your bucket](/guides/cloud-recording)


<!-- guides/byo-storage-providers -->


# BYO storage: provider recipes

Exact endpoint / region / credential settings for the providers we see most.
Field meanings, the minimal IAM policy, verification, and troubleshooting
are all in [BYO storage: setup](/guides/byo-storage-setup) — this page is
just the per-provider specifics.

## AWS S3

| Field | Value |
|---|---|
| Endpoint | `https://s3.<region>.amazonaws.com` (e.g. `https://s3.eu-west-1.amazonaws.com`) |
| Region | The bucket's region — **must match** (e.g. `eu-west-1`). |
| Force path-style | Either works. |

Credentials: create a dedicated **IAM user** with programmatic access and
attach the [minimal policy](/guides/byo-storage-setup#minimal-iam-policy)
scoped to your bucket. Use that user's access key pair — never root keys.

Common failure: leaving Region blank for a non-`us-east-1` bucket. Blank is
signed as `us-east-1` and AWS rejects the request with a region error.

## Cloudflare R2

| Field | Value |
|---|---|
| Endpoint | `https://<account-id>.r2.cloudflarestorage.com` (shown on the R2 overview page) |
| Region | `auto` |
| Force path-style | On (the default). |

Credentials: R2 → **Manage R2 API Tokens** → create a token with
**Object Read & Write**, scoped to the one bucket. Cloudflare shows an
S3-style **Access Key ID** and **Secret Access Key** for the token — those
are what go in the form. R2 tokens don't use IAM JSON; the bucket scoping
on the token is the equivalent of the minimal policy.

R2 has no storage-class or region gotchas; it's the lowest-friction option.

## Backblaze B2

| Field | Value |
|---|---|
| Endpoint | `https://s3.<region>.backblazeb2.com` — copy it from the bucket details page (e.g. `https://s3.us-west-004.backblazeb2.com`) |
| Region | The region embedded in the endpoint (e.g. `us-west-004`). |
| Force path-style | Either works. |

Credentials: **App Keys** → create an application key scoped to the one
bucket with read **and** write. The **keyID** goes in Access key ID and the
**applicationKey** in Secret access key.

Note: the B2 **master key does not work** with the S3-compatible API — you
must use a bucket-scoped application key. Keys created before B2's
S3-compatible API launch (May 2020) also won't work; create a fresh one.

## MinIO (self-hosted)

| Field | Value |
|---|---|
| Endpoint | `https://minio.example.com` or `https://minio.example.com:9000` — your public MinIO S3 endpoint |
| Region | Whatever your server is configured with; blank works for a default MinIO install. |
| Force path-style | **On** (required for most MinIO installs). |

**Reachability is the hard requirement.** TRaX connects to your endpoint
from its servers, and private/LAN addresses are rejected outright
(see [endpoint requirements](/guides/byo-storage-setup#endpoint-requirements-why-some-endpoints-are-rejected)).
Your MinIO must have:

- a **public DNS name** (not `192.168.x.x`, not `minio.local`, not a bare
  hostname) that resolves to a **public IP** — a public name resolving to a
  private IP is blocked at connection time,
- a **valid TLS certificate** on that name (Let's Encrypt is fine; TRaX
  will not connect over plain HTTP),
- inbound access from the internet to the S3 API port.

Credentials: create a dedicated user and a policy equivalent to the
[minimal policy](/guides/byo-storage-setup#minimal-iam-policy):

```bash
mc admin user add myminio trax-user 'GENERATED-SECRET'
mc admin policy create myminio trax-policy ./trax-policy.json
mc admin policy attach myminio trax-policy --user trax-user
```

where `trax-policy.json` is the minimal policy JSON with your bucket name.
Don't use the MinIO root credentials.

If the verification probe fails with an invalid-credentials error and the
keys are definitely right, check the server clock — a skewed clock breaks
S3 request signing.

## Anything else S3-compatible

Other S3-compatible stores (Garage, Ceph RGW, Wasabi, DigitalOcean Spaces,
…) generally work with the same three questions: what's the HTTPS endpoint,
what region string does it sign with, and does it want path-style
addressing? Verification tells you immediately whether the combination
works — the probe does a real write/read/delete round-trip.

## Next

- [Cloud recording to your bucket](/guides/cloud-recording)


<!-- guides/cloud-recording -->


# Cloud recording to your bucket

TRaX records your studio's **program output** — the composited feed your
viewers see — straight into your own S3-compatible bucket. The recording is
yours from the first second: it lands under your keys, in your bucket, and
TRaX **never deletes it**. Retention is whatever your bucket's lifecycle
rules say.

## Prerequisites

1. A connected, **Verified** storage config with write access — see
   [BYO storage: setup](/guides/byo-storage-setup). A read-only
   (**Forbidden**) config can't record.
2. An **active subscription** (recording writes to customer storage and
   rides the same entitlement as connecting a bucket).
3. The studio must be **producing** — recording captures the live program.
   Arming recording while off-air records nothing.

Recording currently writes to your **first Verified storage config**; a
per-studio storage picker is planned. Starting and stopping is
owner/admin-gated; the **Record** button lives in the studio control bar
and shows an elapsed timer while recording.

Recording is deliberately **best-effort in one direction only**: a slow or
broken bucket can degrade the *recording*, but can never touch the live
stream.

## What gets written to your bucket

While recording, TRaX writes the program as **8-second fragmented-MP4
segments**, uploaded continuously (each segment lands within seconds of
being captured), plus a running `manifest.json`. After the recording ends,
processing assembles the segments into flat MP4 file(s):

```
<your-prefix>/trax-recordings/<studio-id>/<start-unix>-<recording-id>/pp/
├── 2026-07-10_18-30-05-000000.mp4     ← 8s fMP4 segments, timestamp-named
├── 2026-07-10_18-30-13-000000.mp4
├── …
├── manifest.json                      ← ordered segment list + loss counter
├── final.mp4                          ← the assembled recording
└── final-2.mp4                        ← only if the stream had a discontinuity
```

- `<your-prefix>` is the prefix on your storage config (empty = bucket
  root); everything stays inside it.
- Each **segment is a self-contained fragmented MP4** — individually
  playable, so the recording is durable and usable even before processing
  runs.
- `manifest.json` lists every uploaded segment in order (key, size, upload
  time) and carries a `segmentsLost` counter.
- **`final.mp4`** is the assembled, seekable recording with the index at
  the front (starts playing immediately when streamed). If the recording
  contains a **discontinuity** — the stream restarted, or the video format
  changed mid-recording — each continuous span becomes its own part:
  `final.mp4`, `final-2.mp4`, `final-3.mp4`, …
- Processing runs **asynchronously after the recording ends** and can take
  a while. Re-processing is safe: output names are deterministic and simply
  overwrite.

When you stop recording (or end the stream), the last segments drain to
your bucket over the following minute or so before the session is marked
complete.

## `segmentsLost` and gaps

`segmentsLost` in `manifest.json` counts segments that were **captured but
could not be delivered** to your bucket. TRaX buffers segments locally
while uploading, but the buffer is bounded — if your bucket is unreachable
or too slow for too long, the oldest unuploaded segments are dropped rather
than endangering the live stream, and each drop increments `segmentsLost`.

A non-zero `segmentsLost` means your recording has **gaps**: processing
skips the missing time, so `final.mp4` is continuous but shorter than the
stream. If you see it regularly, check the bucket's write throughput and
the storage config's status pill for decay events.

## Retention: your bucket, your rules

TRaX never deletes recording objects from your bucket — not segments, not
finals, not manifests. If you want automatic cleanup, use your provider's
**lifecycle rules**. Example (AWS S3 / S3-compatible), expiring recordings
after 90 days:

```json
{
  "Rules": [
    {
      "ID": "expire-trax-recordings",
      "Status": "Enabled",
      "Filter": { "Prefix": "trax-recordings/" },
      "Expiration": { "Days": 90 }
    }
  ]
}
```

If your storage config has a prefix, include it:
`"Prefix": "<your-prefix>/trax-recordings/"`. A tighter variant: expire
only the segment spans you no longer need, and keep `final*.mp4` by moving
finals to a different prefix with your own tooling.

## Current limitations (stated plainly)

- **No in-app recordings list yet.** Recordings don't show up for playback
  or download inside TRaX yet — that surface is being built. Today you
  access recordings directly in your bucket with your own tools (provider
  console, `aws s3` / `mc` / rclone).
- **Processing timing.** `final.mp4` appears after asynchronous processing,
  not instantly at stream end. Until it does, the segments plus
  `manifest.json` **are** the durable recording.
- **Gaps are not yet surfaced in-app.** Check `manifest.json` →
  `segmentsLost` for delivery drops.
- **No direct upload into your bucket through TRaX.** To place other files
  there: upload with your own tools and import, or upload to the TRaX
  library and **Move** it across — see
  [importing and moving files](/guides/byo-storage-setup#importing-and-moving-files).
- **Storage choice is implicit** (first Verified config); a per-studio
  picker is planned.

## Next

- [BYO storage: setup](/guides/byo-storage-setup) — form fields, IAM
  policy, verification, troubleshooting
- [Provider recipes](/guides/byo-storage-providers) — AWS S3, R2, B2, MinIO


<!-- guides/connect-ai-agent -->


# Connect an AI agent (hosted MCP)

TRaX runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) (MCP)
server so you can point an AI agent — Claude, or any MCP-capable client — straight
at the TRaX developer API. The agent gets one tool per `/v1` operation: list your
studios, add sources and destinations, read stream status, go live and go offline,
send chat, list connections, and start a media upload — all as first-class tool
calls, generated from the OpenAPI so they stay in step with the API.

No SDK to install and no glue code: connect the endpoint, present your credential,
and the agent can operate your account.

## Endpoints

| Environment | URL |
|---|---|
| Dev preview | `https://mcp-dev.traxstreaming.live` |

The gateway is a **dev preview** — connect to `mcp-dev.traxstreaming.live`. A
production host on `mcp.traxstreaming.live` is not live yet; this page will list
it once it is.

The server speaks the MCP **streamable-HTTP** transport over TLS.

## Connect with Claude Code

Read-only tools (the API reference and OpenAPI browser) need no credential:

```bash
claude mcp add --transport http trax https://mcp-dev.traxstreaming.live
```

To let the agent act on your account, pass your credential as a Bearer header. It
is forwarded to the API on your behalf and scoped to you:

```bash
claude mcp add --transport http trax https://mcp-dev.traxstreaming.live \
  --header "Authorization: Bearer sk_live_your_key_here"
```

Any MCP client works the same way — configure an HTTP MCP server at the URL above
and set an `Authorization: Bearer <token>` header.

## Authentication

The gateway accepts the same two credentials as the [Developer API](/reference/public-api):

- an **API key** (`sk_live_…`), provisioned for you by the TRaX team; or
- an **interactive-login access token** (a user JWT from an OAuth
  Authorization-Code + PKCE sign-in) — the native-app path.

Your token is **forwarded to the API and never stored or logged** by the gateway.
Every call is scoped to you: you only ever see and change your own studios.

## What the agent can do

Once connected, the agent sees:

- **Reference tools** (no credential): browse the OpenAPI, list endpoints, read
  a specific endpoint, and search the developer guides.
- **API tools** (`v1_…`, one per operation): read tools (list studios, sources,
  destinations, stream status, chat messages, connections, media) and write tools
  (create a studio, add a source or destination, go live / go offline, send a chat
  message, start a media upload).

Read tools are marked read-only. Write tools are marked as such, and go-live /
go-offline are highlighted as consequential so an agent asks before it acts.

## Safety notes

- **Writes require a credential.** If the agent tries a write without a token, the
  call is rejected with a clear message — nothing happens on your account.
- **Least privilege.** Give the agent a key scoped to what you want it to do, and
  revoke it from the API Keys screen when you're done.
- **Availability.** The developer API is a **dev preview**; treat it as evolving.

## See also

- [Developer API (`/v1`)](/reference/public-api) — the REST contract behind the tools.
- [Authentication](/reference/authentication) — credentials in detail.
- [Build a client](/guides/build-a-client) — if you'd rather call the API directly.


<!-- guides/embed-chat -->


# Put TRaX chat on your own site

A TRaX broadcast usually has several chat rooms running at once — Twitch,
YouTube, Kick — and TRaX already merges them into one stream of messages. The
embed puts that merged room on **your** website, for **your** members, without
sending anyone to a third-party platform first.

Two pieces:

- **`<trax-chat>`** — a drop-in custom element. One script tag, one element, no
  framework, no iframe. It renders in a shadow root, so your CSS cannot break it
  and its CSS cannot leak into your page.
- **`POST /v1/viewer-tokens`** — the credential exchange your server calls. You
  have already authenticated your own member; this turns that decision into a
  short-lived token that is safe in their browser.

> **Availability.** The token exchange and the viewer chat socket are live in
> production. The `embed.js` bundle is not yet published at a public URL — TRaX
> gives you the script URL when your account is switched on for the embed.
> Everything else on this page is the real contract and does not change when
> that URL turns on.

## The one idea to get right

**TRaX never sees your users, and your API key never reaches a browser.**

```
  browser (your page)          your server              TRaX
  ───────────────────          ───────────              ────
  <trax-chat> needs a
  token → calls .auth()
        │
        ├── POST /my/viewer-token ──►
        │   (your session cookie)    │
        │                            │ you decide: is this member
        │                            │ entitled? may they post?
        │                            │
        │                            ├── POST /v1/viewer-tokens ──►
        │                            │   Authorization: Bearer      │ mints a
        │                            │   sk_live_…                  │ 15-min token
        │                            │◄── { token, expiresAt, caps }┤
        │◄── { token, expiresAt, caps }
        │
        └── opens the chat socket with the viewer token ────────────►
```

The member reference you send (`memberRef`) is an opaque string. TRaX stores it,
rate-limits on it, and never resolves it to a person — it has no idea who your
users are, and holds nothing about them beyond that string.

Revocation is **token expiry**. When someone's membership ends, your endpoint
stops vouching, and their current token dies within the hour. That is why the
ceiling on token lifetime is short and non-negotiable.

## Before you start

You need two things:

1. **An API key with the `viewer:tokens` scope.** Create it in your TRaX
   account under **Developer → API keys**; the scope is listed under **Embed**
   as *Mint viewer tokens*. It is opt-in — no other scope implies it, and no
   default key has it. Keys are `sk_live_…` and are **server-side only**.
2. **The studio id** of the broadcast whose chat you want to show.

## Step 1 — mint a token from your server

One endpoint on your own backend, behind your own login. It authenticates your
member the way it already does, then calls TRaX.

```js
// Node / Express. Your framework, your session — this part is yours.
app.post('/my/viewer-token', async (req, res) => {
  const member = req.session.member          // however YOU authenticate
  if (!member) return res.status(401).json({ error: 'sign in first' })

  const upstream = await fetch('https://api.traxstreaming.live/v1/viewer-tokens', {
    method: 'POST',
    headers: {
      authorization: `Bearer ${process.env.TRAX_API_KEY}`,  // sk_live_… — server only
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      studioId: process.env.TRAX_STUDIO_ID,
      memberRef: `member:${member.id}`,   // opaque to TRaX
      displayName: member.name,           // PUBLIC — see step 4
      caps: ['chat.read'],                // read-only to start
      ttlSeconds: 900,
    }),
  })

  if (!upstream.ok) {
    // Log the body. It names what is wrong with the request.
    return res.status(502).json({ error: 'could not mint a viewer token' })
  }
  res.json(await upstream.json())          // { token, expiresAt, caps }
})
```

Pass the response through to the browser unchanged. The client reads `expiresAt`
to schedule its own refresh and `caps` to decide what to draw.

Full field-by-field contract:
[Embed chat reference → the token endpoint](/reference/embed-chat#post-v1viewer-tokens).

## Step 2 — drop in the widget

```html
<script type="module" src="https://play.traxstreaming.live/embed.js"></script>

<trax-chat studio="YOUR-STUDIO-ID"></trax-chat>
```

`<trax-chat>` fills its container, so give it a height:

```css
trax-chat { height: 480px; display: block; }
```

Set `studio` in the markup. Changing the attribute after the element is in the
page does nothing — the element reads it once, when it starts.

## Step 3 — wire the auth callback

The element takes a **function**, not a token. This is the load-bearing design
decision: tokens last minutes and broadcasts last hours, so a token-shaped API
would work perfectly in your testing and then die mid-stream.

```html
<script type="module">
  const chat = document.querySelector('trax-chat')

  chat.auth = async () => {
    const r = await fetch('/my/viewer-token', { method: 'POST' })
    if (!r.ok) throw new Error('not entitled')
    return r.json()          // { token, expiresAt, caps }
  }
</script>
```

Assigning `.auth` is what **starts** the element, and you can assign it at any
time — including long after the element is in the DOM, which is the normal case
when your script runs after the markup. It is a property, never an attribute: an
attribute would mean a credential sitting in your HTML.

The element calls `auth` again before each expiry, using the `expiresAt` the
server returned. If your endpoint starts refusing, the chat stops. That is
revocation working.

That is the whole read-only integration. Messages from every platform the
broadcaster has connected now appear on your page, tagged with where they came
from.

## Step 4 — letting your visitors post (read this part twice)

Add `chat.send` to `caps` and the widget grows a composer. Before you do,
understand exactly what happens to the words:

> **A visitor's message leaves on the broadcaster's platform account.**
> TRaX relays it to Twitch, YouTube and Kick over the broadcaster's own
> connections, because those are the only credentials in the system. There is no
> per-visitor platform identity and there cannot be one.

So every relayed message carries an attribution prefix, and it is not
decoration:

```
Ava (web): when does the second set start?
```

Without it, a stranger's words are published under the broadcaster's name, to
the broadcaster's audience. That is a reputational problem for them and a
platform-terms problem for everyone. The prefix is not configurable, and a
visitor cannot forge it — colons, newlines and control characters are stripped
from both the name and the message.

Two consequences to design around:

- **`displayName` is public by construction.** It is published to the
  broadcaster's Twitch/YouTube/Kick audience. Send a display name — never an
  email, an internal id, or anything your member would not want on a public
  channel. It is attested by *your* server, so a visitor cannot choose it.
- **`memberRef` becomes mandatory.** A write capability with no member behind it
  is refused at mint. There is no anonymous path to the broadcaster's accounts,
  by design: you vouch, so you can stop vouching.

```js
caps: ['chat.read', 'chat.send'],
displayName: member.name,     // required with chat.send, and public
memberRef: `member:${member.id}`,  // required with chat.send
```

Messages are budgeted to the **tightest** platform limit (200 characters,
YouTube's), minus the attribution prefix — so a message is whole everywhere or
refused before it leaves, never truncated on one service and complete on
another.

### Render from what the server granted

Requesting a capability does not grant it. The response's `caps` is the truth,
and it can be narrower than you asked for — a viewer the broadcaster has blocked
gets `chat.send` stripped at mint, and revoked live on an open socket if the
block lands mid-conversation.

`<trax-chat>` already does the right thing: it hides the composer unless the
server granted `chat.send`, and hides it again the moment a block arrives. If
you build your own UI, do the same. A control that is visible and always fails is
worse than no control.

## Styling

Theme through CSS custom properties on the element — that is the whole surface:

```css
trax-chat {
  --trax-bg: #14110f;
  --trax-fg: #ece4d9;
  --trax-muted: #a1948a;
  --trax-rule: #322b27;
  --trax-accent: #e0913c;
  --trax-accent-fg: #1a1207;
  --trax-platform-bg: #221e1b;
  --trax-platform-fg: #a1948a;
  --trax-warn: #d4715a;
  --trax-font: 'Public Sans', system-ui, sans-serif;
  --trax-size: 15px;
}
```

## Watching what it is doing

The element emits `trax-state` whenever the connection or the granted
capabilities change:

```js
chat.addEventListener('trax-state', (ev) => {
  const { state, caps, host } = ev.detail
  // state: 'connecting' | 'live' | 'reconnecting' | 'closed'
  console.log(state, caps, host)
})
```

`host` is the embed plane the element actually connected to. It is reported
rather than left implicit so an embed pointed at the wrong environment is
visible instead of mysterious.

## When it does not work

| What you see | Almost always |
|---|---|
| `Not configured: a studio is required.` | No `studio` attribute on the element. |
| `Waiting for the auth callback…` and it stays | `.auth` was never assigned, or your script never ran. |
| Connects, then disconnects in a loop | Your `/my/viewer-token` endpoint is throwing, or returning something that is not `{ token, expiresAt, caps }`. |
| Connects, but no composer | The server did not grant `chat.send`. Check `caps` in the mint response — you may have omitted `displayName` or `memberRef`, or the viewer is blocked. |
| Mint returns 401 | The key is wrong, or missing. |
| Mint returns 403 | The key exists but lacks the `viewer:tokens` scope. The response names the scope it wants in `requiredScope`. |
| Mint returns 404 | The studio id is wrong, or the key's owner does not own that studio — deliberately the same answer. **Also** what a blocked viewer gets if you asked for `chat.send` and nothing else; ask for `['chat.read','chat.send']` instead. |
| Mint returns 400 | A mint rule was violated, but the message is generic — the specific reason is not passed through. The [complete checklist is in the reference](/reference/embed-chat#errors); usually it is `chat.send` without a `displayName` or without a `memberRef`. |
| Messages arrive with no sender name | The upstream platform gave us no display name. TRaX renders no name rather than a made-up one. |

## Building your own interface instead

The same package ships a headless client with no DOM opinions —
`TraxChatClient`, plus the `shouldRemove` rule so your own message log applies
moderation removals exactly the way the widget does. See
[Embed chat reference → headless SDK](/reference/embed-chat#headless-sdk).

## Also worth knowing

- Token lifetime is capped at **1 hour** and defaults to **15 minutes**, whatever
  you ask for. Schedule from the `expiresAt` you got back, never from the
  `ttlSeconds` you sent.
- Moderation flows **inbound** too: a message deleted on YouTube or Twitch, or a
  ban on any of the three, stops being displayed on your site. Coverage is
  uneven because the platforms are — the exact matrix, including a Kick gap we
  cannot close, is in the
  [reference](/reference/embed-chat#inbound-moderation).
- Chat only, for now. Video playback on the same viewer token is a separate,
  later phase and is not available.


<!-- guides/youtube-broadcast-settings -->


# Set YouTube broadcast settings from your app

A YouTube destination can carry a **broadcast template** — the settings TRaX
stamps on the broadcast it auto-creates for you at go-live: title, privacy,
latency, DVR, and the handful of YouTube switches that are only settable through
the API. This guide is how a mobile client reads and writes that template over
`/v1`, so the app can offer the same broadcast controls the studio does.

> **Which host.** These endpoints are on dev only for now:
> `https://api-dev.traxstreaming.live/v1` with a dev key. This page will say so
> when they reach production.

## The one field

The template rides on the destination as `broadcastConfig`. You set it when you
create a destination:

```http
POST /v1/studios/{studioId}/destinations
Authorization: Bearer sk_live_…
Content-Type: application/json

{
  "name": "YouTube main",
  "platform": "youtube",
  "connectionId": "…",
  "broadcastConfig": {
    "mode": "create",
    "title": "Tonight's show",
    "privacy": "unlisted",
    "latency": "low",
    "autoStart": true,
    "autoStop": true,
    "dvr": true,
    "madeForKids": false
  }
}
```

…or change it later without touching anything else on the destination:

```http
PATCH /v1/studios/{studioId}/destinations/{destinationId}
Authorization: Bearer sk_live_…
Content-Type: application/json

{ "broadcastConfig": { "mode": "create", "title": "New title", "privacy": "public" } }
```

Both need the **`destinations:write`** scope — the same scope that creates the
destination. A `broadcastConfig` on a non-YouTube destination is stored and
ignored; only YouTube reads it at go-live.

## The fields

| Field | What it sets |
|---|---|
| `mode` | `create` = auto-create a fresh broadcast at go-live from this template. `pick` = you chose a specific existing broadcast; auto-create is off. |
| `title` | Title stamped on the auto-created broadcast. |
| `privacy` | `public`, `unlisted`, or `private`. **There is no members-only** — YouTube's live API does not expose it. |
| `description` | Broadcast description body. |
| `latency` | `normal`, `low`, or `ultraLow`. `ultraLow` disables closed captions and caps resolution at 1080p. |
| `autoStart` / `autoStop` | The broadcast goes live / stops automatically with your ingest. |
| `dvr` | Viewers can rewind the live stream. |
| `madeForKids` | The COPPA "made for kids" self-declaration. |
| `enableEmbed` | May the watch page be embedded off YouTube. |
| `recordFromStart` | Archive records from the first frame. |
| `enableMonitorStream` | The preview/monitor stream that parks the broadcast in "testing" before it goes live. |
| `streamDelayMs` | Intentional broadcast delay, in milliseconds. `0` = none. |
| `projection` | `rectangular` or `360`. |

## Two rules worth knowing

**Tri-state fields.** `enableEmbed`, `recordFromStart`, and
`enableMonitorStream` are three-way: send `true`, send `false`, or **omit the
key entirely** to leave it unset. Omitting means YouTube applies its own
default — and omitting `enableMonitorStream` specifically preserves the standard
behaviour where an auto-starting broadcast goes straight to live instead of
parking in "testing". Set `enableMonitorStream: true` under `autoStart` only if
you deliberately want that testing hold.

**Immutable once live.** YouTube freezes most of the broadcast body (embed, DVR,
record-from-start, monitor stream, delay, projection) the moment the broadcast
enters *testing* or *live*. Edit the template while you are off air; a change
sent after go-live applies to the *next* broadcast, not the running one.

## Round-trip

A read of the destination shows the template back to you (the stream key is
never returned):

```http
GET /v1/studios/{studioId}/destinations
```

The `broadcastConfig` you get back is exactly what a future go-live will use.
Omitted tri-state fields stay omitted — the read never invents a `false` you did
not send.

## Work with broadcasts directly (#665)

The template above tells go-live what to *create*. Three more endpoints let
your app skip the template entirely and deal in actual YouTube broadcasts —
the same three moves the studio's Stream Setup panel makes.

### List what you can pick from

```http
GET /v1/studios/{studioId}/destinations/{destinationId}/broadcasts
```

Requires **`destinations:read`**. Returns the destination's platform-side
broadcasts — recent, upcoming and active — each with its `id`, `title`,
lifecycle `status` and, on YouTube, the broadcast's live settings (privacy,
latency, DVR, …) so an editor can seed from actual values instead of guesses.
Platforms with no broadcast concept (Twitch, Kick, Trovo) and pasted-key
destinations answer an **empty list**, not an error.

### Create a broadcast now

```http
POST /v1/studios/{studioId}/destinations/{destinationId}/broadcast
Content-Type: application/json

{ "title": "Tonight's show", "description": "…" }
```

Requires **`destinations:write`**. This inserts the broadcast on YouTube
**immediately** — not at go-live — seeded from the destination's saved
`broadcastConfig` (privacy, latency, DVR, contentDetails), with your `title`/
`description` overriding the template's copies. Omit `scheduledStartTime` to
start now; pass an RFC 3339 time to schedule it. The created broadcast is
**adopted as the destination's pick** (`mode` flips to `pick`), so going live
binds the stream to it. `201` returns the broadcast; its `id` is what the
edit, thumbnail and pick endpoints take.

### Pick an existing broadcast — or clear the pick

```http
POST /v1/studios/{studioId}/destinations/{destinationId}/broadcast/pick
Content-Type: application/json

{ "broadcastId": "dQw4w9WgXcQ", "title": "Tonight's show" }
```

Requires **`destinations:write`**. Points the destination at one existing
broadcast from the list above; go-live then binds the stream to it. Send
`{ "broadcastId": null }` to **clear** the pick — the destination returns to
`create` mode and go-live auto-creates from the template again. This is a
pointer write: nothing is validated against YouTube here, so a deleted
broadcast id surfaces at go-live, not at pick time.

Rounding out the set, the `PATCH …/broadcast` edit and the thumbnail upload
from the Broadcast Manager wave apply to whichever broadcast id you name —
see the API reference for `updateDestinationBroadcast` and
`setDestinationBroadcastThumbnail`.

## Which broadcast am I on? `activeBroadcastId`

Every one of the calls above takes a broadcast id, and until now there was no
supported way to *get* one for a destination you did not just create. Every
destination read now carries it:

```http
GET /v1/studios/{studioId}/destinations
```

```json
{
  "id": "…",
  "platform": "youtube",
  "activeBroadcastId": "dQw4w9WgXcQ"
}
```

`activeBroadcastId` is the broadcast this destination is **currently operating
on**. It is what you pass to `PATCH …/broadcast` and to the thumbnail upload.
It rides the SSE destination event too, so a client watching
`GET /v1/studios/{studioId}/events` learns a new id the moment go-live mints
one instead of polling for it.

The field is **always present** and empty when there is no broadcast: a
channel-scoped platform (Twitch, Kick, Trovo) has no broadcast concept at all,
a create-mode YouTube destination that has never gone live has nothing yet, and
a cleared pick leaves nothing behind.

**Two cases, and they do not age the same.** Treat this difference as part of
the contract, not a detail:

| How the id was obtained | How long it stays valid |
| --- | --- |
| **Picked** — you called `…/broadcast/pick`, or created one with `POST …/broadcast` | Stable until the pick changes or is cleared. Names a real broadcast whether or not anything is streaming. |
| **Auto-created** — no pick; the destination mints a fresh broadcast at each go-live | The one minted for the **current or most recent** session. **Goes stale once that broadcast completes** — a completed YouTube broadcast cannot be edited or restreamed, and the next go-live mints a different one. |

So: read it again after going live. Do not cache it across sessions and assume
an edit will land where you expect — between sessions, a create-mode id can
name a broadcast the next go-live will not touch. We would rather ship a field
that tells you when not to trust it than one that quietly lies.

### Do not read `settings`

Destinations also carry a `settings` blob, and the id does appear inside it.
**That is not a contract.** `settings` is opaque: its schema is not part of
this API, we reshape it when the studio needs to, and a client parsing it will
break on a release that changes nothing you can see. `activeBroadcastId` exists
precisely so you never have to.

A typical flow, end to end: [list the broadcasts](#list-what-you-can-pick-from)
you can pick from, [pick one](#pick-an-existing-broadcast--or-clear-the-pick)
or [create one now](#create-a-broadcast-now), then read `activeBroadcastId` off
the destination whenever you need to name it again.


<!-- guides/account-and-api-keys -->


# Account & API keys over the API

Your TRaX **account** is now on `/v1`: read and update your own profile,
manage your developer API keys, and — if it comes to that — delete the account
of the account itself. This is the surface a native app uses to build its
"Account" screen without ever touching a browser.

> **Which host.** These endpoints are on dev only for now:
> `https://api-dev.traxstreaming.live/v1`. This page will say so when they
> reach production.

Two rules shape everything on this page:

1. **The profile works with either credential** — a user JWT or an
   `sk_live_` API key (the key needs the opt-in `account:read` /
   `account:write` scopes).
2. **Everything else is sign-in only.** Managing API keys and requesting
   deletion require an interactive OIDC login (a user JWT). An API key —
   *no matter what scopes it holds* — is refused with
   `403 interactive_auth_required`. There is no scope that unlocks these
   routes for a key, and that is the point: a leaked key must never be able
   to mint itself broader successors, enumerate its owner's other
   credentials, or erase the account that owns it.

## Your profile

```
GET /v1/account
```

```json
{
  "userId": "312778367937681292",
  "username": "ejbev",
  "usernameSet": true,
  "createdAt": "2026-07-16T18:22:04Z",
  "updatedAt": "2026-08-30T11:02:51Z"
}
```

The profile is your **@username identity** — the handle other users find you
by. A user who has never claimed one gets `usernameSet: false`, which is a
normal state, not an error.

Deliberately **not** here: your display name and email. Those are OIDC claims
on the identity token your app already holds from login — read them from the
IdP, not from `/v1`. An API key has no claims at all, which is exactly why the
profile carries only what the account service itself records.

### Claim or change your username

```
PATCH /v1/account
{ "username": "@EjBev" }
```

Mixed case and a leading `@` are fine — the handle is canonicalized to
lowercase (`ejbev`). The rules are the same ones the TRaX account app
enforces: 3–20 characters of `a-z 0-9 _`, no leading/trailing/double
underscore, and a reserved blocklist. Refusals are typed so your UI can react
precisely:

| Status | `error.code` | Meaning |
| --- | --- | --- |
| 422 | `invalid_username` | Can never be a handle; the message names the rule that failed (`too_short`, `charset`, …). |
| 409 | `username_taken` | Held by another user (decided race-safely server-side). |
| 409 | `username_reserved` | Well-formed but spoken for (`admin`, `support`, …). |
| 429 | `username_cooldown` | You changed your handle too recently. Honor the `Retry-After` header. |

Re-saving the handle you already hold is an idempotent no-op — it succeeds
and does **not** burn the change cooldown.

## API keys — the full lifecycle

All four operations require a user JWT (see rule 2 above).

### List

```
GET /v1/account/api-keys
```

Returns metadata only, newest first, revoked keys included (with
`revokedAt` set): id, label, the display `prefix` (`sk_live_7Qm2xB`), the
scope ceiling, created / last-used / expiry timestamps. **The full secret is
never in any list.** It cannot be — only a peppered hash of it is stored.

### Create — and the one-time secret

```
POST /v1/account/api-keys
{ "name": "CI uploader", "scopes": ["studios:read", "media:write"] }
```

The `201` response carries `key`: the full `sk_live_` secret, **shown exactly
once, ever**. It is not stored, cannot be recovered, and no later call will
repeat it. Hand it to the user with copy-to-clipboard UI, or write it
straight into your secret manager — then drop it.

Omit `scopes` for the safe read-only default set. An unknown scope refuses
the **whole** request with a 400 naming the offending value — you never get a
key silently missing a grant. An optional `expiresAt` (RFC 3339) bounds the
key's lifetime; omitted means it never expires.

### Revoke

```
DELETE /v1/account/api-keys/{keyId}
```

`204`. The key stops verifying within seconds (the gateway holds a short
verification cache) and stays listable as history with `revokedAt` set.
Idempotent; a key id that is not yours is the same `404` as one that does
not exist.

## Delete your account

```
DELETE /v1/account
{ "reason": "optional, in the user's words" }
```

**This executes the deletion — immediately, and it cannot be undone.** It is the same legally recorded flow as
"Delete my account" in the TRaX account app: a row is opened in the
append-only deletion record *first*, then all account data is erased and the
identity deleted last. There is no undo and no grace period — your app must
present its own confirmation step before calling.

The response is the user's receipt:

```json
{
  "requestId": "8c33d2f1-…",
  "alreadyDeleted": false,
  "ok": true,
  "retained": { "billing": "…", "deletionRecord": "…" },
  "confirmationEmailSent": false
}
```

- **Show `requestId` to the user.** No confirmation email is sent on this
  path (the API hop carries no email address), so the id on screen is their
  only reference.
- `retained` carries the deletion record's own wording for the few
  categories kept for legal reasons — render it verbatim rather than
  paraphrasing a legal statement.
- Repeating the call is safe: it returns the **original** `requestId` with
  `alreadyDeleted: true` instead of recording a second erasure.
- `503 unavailable` means deletion is not armed on this deployment and
  nothing was deleted. `500 erasure_incomplete` means the account still
  exists — retry.

There is also a public, no-login form at
<https://traxstreaming.live/delete> for people who cannot sign in; that path
confirms by email before erasing anything.

## What is *not* on /v1, and why

Passwords, passkeys, MFA, and sign-in itself are **not** API endpoints and
never will be. They are OIDC ceremonies performed directly against the TRaX
identity provider — the flows where the human proves who they are on a
surface we (and the browser's WebAuthn machinery) control. Your app gets a
user in and out via the standard **Authorization Code + PKCE** login
described in [Build a client](/guides/build-a-client); once that returns a
JWT, everything on this page works. A REST endpoint that accepted a password
or enrolled a passkey on the user's behalf would turn every integration into
a credential-phishing surface, so no such endpoint exists.

Email and display name changes live in the TRaX account app for the same
reason: they are identity-provider records, verified through the IdP's own
flows (email confirmation among them), not `/v1` resources.


<!-- guides/link-a-platform-account -->


# Link a platform account from a mobile app

Linking a platform account means a human consenting on that platform's own
consent screen. No server-to-server call can stand in for it, so every client —
web, iOS, Android — does the same three things: ask TRaX for a URL, put that URL
in front of the user, then find out what happened.

On a phone the middle step is where it goes wrong, and it goes wrong in ways
that are invisible until you test on a real device. This page is the shape that
works.

**Which platforms this covers.** Production has OAuth applications configured
for **Twitch, YouTube, Kick, Facebook and LinkedIn**. `trovo` is accepted by the
schema but has no credentials provisioned — asking to link it is a `400`, not an
empty URL. Facebook has an adapter but is handled as a manual stream-key
integration in the product while its platform app review is outstanding.

> Instagram, Rumble, X/Twitter, TikTok and anything custom have no OAuth link at
> all and take a pasted stream key instead — see
> [Manual stream-key connections](/guides/manual-connections). None of the
> browser handling below applies to those.

## 1. Ask for the URL

```http
POST /v1/connections/link
Authorization: Bearer sk_live_…
Content-Type: application/json

{
  "platform": "youtube",
  "returnTo": "https://account.traxstreaming.live/settings/integrations"
}
```

Requires **`connections:write`**. You get back an `authorizationUrl` to open and
a `state` string.

Two things to know about the response:

**`state` is how you tell attempts apart.** If a user taps Connect twice, or
links two platforms in a row, you will have more than one flow in flight. Keep
the `state` you were handed alongside whatever your UI is waiting on.

**`returnTo` must be a TRaX-owned https host.** Anything else is rejected, not
followed — this value is a redirect target reached carrying the user's session,
so an app cannot point it at itself or at a third-party host. `returnTo` is
optional; leaving it out is the normal choice for a phone, and section 3
explains where the user lands then.

**Leave `scopes` out.** Omitting it requests the platform's default set, which
is what TRaX's own features need. Requesting less links *successfully* and then
silently fails later at whichever feature needed the missing scope — chat that
never attaches, a title that won't save. If you do narrow it, read
`grantedScopes` on the resulting connection to see what the platform actually
handed over, which is not always what you asked for.

**To repair a broken connection, send `reconnectConnectionId`.** That refreshes
the grant in place and keeps the connection id. Without it you get a *second*
connection row, and every destination bound to the old one is orphaned — still
listed, still failing at go-live. This is the single most common way a
re-link makes things worse.

## 2. Open it in a system browser session — not a webview

### iOS

```swift
let session = ASWebAuthenticationSession(
    url: authorizationUrl,
    callbackURLScheme: nil        // see §3 — set this to auto-dismiss the sheet
) { _, _ in
    // The user dismissed the sheet. This tells you the flow ENDED,
    // not that it SUCCEEDED. Go to step 4.
    Task { await self.refreshConnections() }
}
session.presentationContextProvider = self
session.prefersEphemeralWebBrowserSession = false   // share Safari's cookies
session.start()
```

`ASWebAuthenticationSession` presents a browser sheet *over* your app, shares
Safari's cookie jar — so a user already signed into YouTube is often one tap
from done — and shows the real domain in the chrome, which is the property that
makes it phishing-resistant.

Leave `prefersEphemeralWebBrowserSession` at `false` unless you have a reason:
turning it on throws away the shared cookie jar and forces a full sign-in every
time.

### Android

The Android equivalent is a **Chrome Custom Tab**. Same properties — real
browser engine, shared cookie jar, visible origin — presented over your app:

```kotlin
CustomTabsIntent.Builder()
    .setShowTitle(true)
    .build()
    .launchUrl(context, Uri.parse(authorizationUrl))
```

There is no completion callback. A Custom Tab is a browser, not a modal you
`await`: control comes back to you when your activity resumes, either because
the user pressed Back or because something navigated into your app (§3). Do the
step-4 refresh from `onResume()`, and make it idempotent — it will fire on
ordinary app switches too:

```kotlin
override fun onResume() {
    super.onResume()
    viewModel.refreshConnections()   // cheap, idempotent; see step 4
}
```

Add `androidx.browser:browser` for `CustomTabsIntent`. If no Custom
Tabs–capable browser is installed, `launchUrl` falls back to a plain
`ACTION_VIEW` — the user leaves your app for a full browser. That still
completes the link; they just have to come back by hand. Worth handling
gracefully, not worth blocking on.

### Both platforms

**Never an embedded `WKWebView`/`WebView`.** Google rejects them outright with
`disallowed_useragent`, so YouTube linking simply cannot work that way. The
others mostly tolerate it, which is worse — you ship, and only the YouTube path
is broken. On Android this means *not* `WebView.loadUrl(authorizationUrl)`, no
matter how much more controllable it looks.

**Never a hand-off to an external browser either.** That's the version that
prompts "which browser do you want to use?", drops the user out of your app,
and leaves them holding a tab they have to clean up themselves.

## 3. Where the user lands

After the platform hands the user back, `trax-connect` finishes the exchange and
sends the browser somewhere. Which somewhere depends on what you sent:

| You sent | The browser ends on |
|---|---|
| A safe `returnTo` | That URL, with `?connected=<platform>` appended |
| No `returnTo` | `https://connect.traxstreaming.live/oauth/return` |

The `/oauth/return` page is a small self-contained confirmation — "YouTube
connected", or the error state naming what went wrong — with no scripts and no
network calls, so it paints instantly on a bad connection. It is the last frame
of a flow the user is already waiting on.

> **This page is why you can omit `returnTo`.** Before it existed the no-`returnTo`
> path fell through to a raw JSON body, and a user who linked from a phone
> watched a wall of `{"status":"ok",…}` in a browser they then had to dismiss by
> hand. Live in production since 1 September 2026.

**The JSON is still there for non-browsers.** To be precise about what is gated:
`/oauth/return` is a page and always renders HTML — fetch it yourself and you
get markup. What the `Accept` header governs is the **callback**
(`/oauth/{platform}/callback`), which redirects the caller here only when
`Accept` contains `text/html`. `curl`'s default `Accept: */*`, an empty
`Accept`, and every programmatic client get the exact JSON body from the
callback they got before this page existed — the polarity opts *in*, so
scripted callers are unchanged by construction.

**The page never links to the TRaX website, by design.** An earlier build
offered a "Back to TRaX" button. Inside `ASWebAuthenticationSession` there is no
address bar, so a user who tapped it was left browsing the site in a modal
browser they could not navigate — the stranded-in-a-tab problem the sheet exists
to prevent, moved one step later. The page's job is to *end* the flow, so the
exit instruction is the primary content, and it names the control the sheet
actually shows: **Cancel**, with the reassurance that Cancel closes the window
without undoing the link. (Found on a real device, 1 September 2026; fixed the
same day.)

### Getting the user back into your app

**By default nothing closes the browser for you.** On iOS the user taps
*Cancel*, which fires your completion handler with
`ASWebAuthenticationSessionError.canceledLogin` — an outcome that means "the
sheet is gone", never "the link failed". Treat it as the cue to go to step 4,
not as an error to surface. On Android the user presses Back and your activity
resumes. Build this path first on both platforms: it is the one that always
works, on every OS version, with no configuration on our side.

Everything below is an improvement on top of it, not a replacement.

**Custom-scheme return (iOS live in production, Android off).** When the operator
sets the per-platform scheme for the requesting device (see the note below), the
page renders its return control as
`<scheme>://oauth/linked?connected=<platform>` (or `?error=…&error_provider=…`
on the failure leg). **The user taps it — the page never navigates on its own.**
That is deliberate: a scripted navigation to a scheme the device cannot open
produces an OS error dialog and strands the user, whereas an unopenable link
simply does nothing when tapped, with the *Cancel* instruction still beside it.
So treat this as a shortcut for the manual dismissal above, not as a mechanism
you can wait on. Both platforms can act on the tap — by different mechanisms.

*iOS* — pass the same value as `callbackURLScheme` and the session intercepts
the navigation and closes its own sheet. No association file, no entitlement:

```swift
let session = ASWebAuthenticationSession(
    url: authorizationUrl,
    callbackURLScheme: "live.traxstreaming.ios"   // == OAUTH_RETURN_APP_SCHEME_IOS
) { callbackURL, error in
    // callbackURL is live.traxstreaming.ios://oauth/linked?connected=youtube
    // when the interception fired; nil + canceledLogin when the user tapped
    // Cancel. Either way the flow ENDED — go to step 4.
    Task { await self.refreshConnections() }
}
```

*Android* — there is **no `callbackURLScheme` equivalent**; a Custom Tab does
not hand navigations back to its opener. Instead you register the scheme as a
deep link, and the navigation launches your activity, which brings your app
back to the front over the tab:

```xml
<!-- AndroidManifest.xml — on the activity that handles the return -->
<activity
    android:name=".OAuthReturnActivity"
    android:launchMode="singleTask"
    android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="live.traxstreaming.android" android:host="oauth" />
  </intent-filter>
</activity>
```

```kotlin
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    // intent.data == live.traxstreaming.android://oauth/linked?connected=youtube
    viewModel.refreshConnections()   // step 4 — the params are a hint, not proof
}
```

`singleTask` is what makes this reuse your existing activity instead of stacking
a second copy. The Custom Tab is left behind in the task stack rather than
destroyed — acceptable, and the reason the page still tells the user how to
close it themselves.

The query parameters are a *hint*, not a receipt, on both platforms: they say
what the page displayed, and the page displays what the callback told it.
Confirm against `GET /v1/connections` regardless — step 4 is not optional
because the browser closed politely.

> **The two platforms are independent.** `OAUTH_RETURN_APP_SCHEME_IOS` and
> `OAUTH_RETURN_APP_SCHEME_ANDROID` are separate values, and the page picks
> between them from the request's User-Agent — so you do not have to agree on a
> shared string with the other platform's team, and whichever app ships first
> can be switched on immediately without lighting up a dead control on the
> other. `OAUTH_RETURN_APP_SCHEME_IOS` is set in production as of 2026-09-01
> (`live.traxstreaming.ios`); Android is still unset. Tell us your scheme when
> the release that registers it is out; turning it on is one environment
> variable, no redeploy, reversible
> if a release slips. (A single legacy `OAUTH_RETURN_APP_SCHEME` still works and
> seeds both — only correct if both apps really did register the same string.)

**Universal Links / App Links (the eventual fix).** Claiming
`connect.traxstreaming.live/oauth/return` as a Universal Link (iOS
`apple-app-site-association` + associated-domains entitlement) or an App Link
(Android `assetlinks.json` + `android:autoVerify="true"`) returns the user to
your app without any custom scheme, works when the link is opened from outside
your app, and — because it is an `https://` URL — is per-app rather than a
first-come-first-served global namespace. It needs an association file on our
side for each app, and is not shipped yet; the custom-scheme route above makes
it a nice-to-have rather than a blocker.

## 4. Find out what actually happened

**There is no completion callback and no push.** Your completion handler firing
means the sheet closed — the user may have consented, cancelled, or given up.

So read the state instead:

```http
GET /v1/connections
Authorization: Bearer sk_live_…
```

A successful link shows up as a **new row** for that platform, or — on a repair
with `reconnectConnectionId` — as the **existing row's `status` flipping back to
`active`**. Poll on your completion handler, and again when the app returns to
the foreground; those two together cover the user who backgrounds the app
mid-consent.

Match on `state` if you had more than one attempt open.

## What to check before you call it done

- A browser never sees JSON — success or failure. Cancel at the consent screen
  and confirm you land on the error page, not on a raw error body.
- `curl` still gets the JSON it always got.
- The flow works on a device with **no** platform app installed and on one where
  the user is **already signed in** — those take different paths through the
  consent screen.
- **Kick specifically**, because it is the one platform using PKCE. The verifier
  never leaves the server, so nothing changes for your app, but it is the flow
  most likely to expose a wrong assumption about who completes the exchange.
- Re-linking an existing connection keeps the same connection id and does not
  orphan its destinations.


<!-- guides/manual-connections -->


# Save a stream key as a connection

Some platforms have no OAuth link — Facebook and Instagram today (pending
platform app review), plus Rumble, X/Twitter, TikTok and anything custom. For
those, TRaX stores the RTMP URL + stream key you paste from the platform's
own dashboard as a **manual connection**, and destinations bind to it exactly
like they bind to a linked YouTube or Twitch account.

> **Which host.** These endpoints are on dev only for now:
> `https://api-dev.traxstreaming.live/v1` with a dev key. This page will say
> so when they reach production.

## Save the key once

```http
POST /v1/connections/manual
Authorization: Bearer sk_live_…
Content-Type: application/json

{
  "platform": "facebook",
  "label": "My Facebook Page",
  "rtmpUrl": "rtmps://live-api-s.facebook.com:443/rtmp",
  "streamKey": "FB-…"
}
```

Requires **`connections:write`**. `platform` is free-form (`facebook`,
`instagram`, `rumble`, `twitter`, `tiktok`, `custom`, …; empty defaults to
`custom`) — it drives icons and labels, not behaviour. `201` returns the
connection; its `id` is what `CreateDestination.connectionId` takes, so the
flow is: save the key once, then create destinations against it from any
studio.

**The stream key is write-only.** It is stored encrypted and never returned
by any read on this API — not on create, not on the list, not on the patch.
If you lose it, get it from the platform's dashboard, not from TRaX.

## Update it later

```http
PATCH /v1/connections/{connectionId}
Content-Type: application/json

{ "streamKey": "FB-NEW-…" }
```

A PATCH: only the fields you send change. Rename with `label`, repoint with
`rtmpUrl`, rotate with `streamKey` — and an absent or empty `streamKey`
**keeps the stored key**, so a rename never has to re-enter the secret.
Destinations bound to the connection pick the new key up at the next
go-live. Only manual connections accept this PATCH; an OAuth row answers
400 (its credentials are managed by the platform link). Unlinking is the
same `DELETE /v1/connections/{connectionId}` as any other connection.

## What you give up vs OAuth

A stream key authorizes exactly one thing: pushing video. So on stream-key
platforms:

- **Chat is not available.** There is no API grant to read the platform's
  chat with, so nothing shows up in unified chat for these destinations.
- No broadcast management — the list/create/pick endpoints in the YouTube
  guide need a linked account.
- The key never self-heals. If the platform rotates it, streams fail at
  go-live until you PATCH the new key in.


<!-- guides/delete-your-account -->


# Delete your account or remove your data

You can delete your TRaX account, or remove parts of your data while keeping
the account. Both are self-serve, both are permanent, and neither requires you
to email anyone and wait.

The public, no-login-required versions of these pages live at
**<https://traxstreaming.live/delete>** and **<https://traxstreaming.live/remove>**.
Those two URLs are the ones registered with app stores and platform consoles, so
they are stable and will not move.

## Delete your account

Signed in, go to **Account → Privacy → Delete account**. You type your username
to confirm, and it runs immediately. A confirmation email follows with a
**request id** — keep it, it is your reference if you ever need to ask us about
the deletion.

Behind the button, `DELETE /api/account/me` runs a fixed cascade and deletes
your login identity **last**, so your identity only disappears once the data
behind it is gone:

1. **Chat** — every chat message we stored, across every platform.
2. **Platform connections** — each connected platform is disconnected, its
   stored tokens deleted, and the authorization revoked at the platform itself.
3. **Studios and media** — studios with their layouts, scenes, overlays,
   rundowns, sources and destinations; your media library; recording metadata
   and storage settings; paired mobile devices.
4. **Identity** — the account itself.

If a step fails, the others still run and the failure is recorded rather than
hidden. Retrying is safe: every step is idempotent, and a second delete returns
the original request id instead of creating a second record.

### What we keep, and why

Two things survive an account deletion. Both are listed on the public page and
repeated in your confirmation email.

**Billing and invoice records.** Kept for the period tax and accounting law
requires. GDPR Article 17(3)(b) allows retention where we have a legal
obligation; CCPA 1798.105(d)(8) is the equivalent carve-out.

**One line in our deletion log.** A request id, timestamps, which categories
were deleted, what was retained and under what basis. It holds no name, no email
and no account id — the subject is stored as a one-way HMAC. We keep it
indefinitely because it is the evidence the deletion happened (GDPR Article 5(2),
accountability). See [the deletion log](#the-deletion-log) below.

## Remove data without closing your account

Signed in, go to **Account → Privacy → Remove some of your data**. Four things
can be removed independently, each with its own confirmation:

| Scope | What goes | What stays |
|---|---|---|
| `connections` | Every platform connection, its stored tokens deleted and revoked at the platform | Studios, media, chat you keep separately |
| `chat` | Every chat message we stored, all platforms | Your connections |
| `media` | Media library files, recording metadata, storage settings | Your studios |
| `studios` | Every studio with its layouts, scenes, overlays, rundowns, sources and destinations | Your account, connections and media |

Each is `DELETE /api/account/me/data/{scope}`. The scope comes from the URL and
the account comes from your session — there is no request shape that lets one
person name another person's account. None of these close your account.

Each removal gets its own entry in the deletion log. A partial removal is as
much a data-subject request as a full one, and "show me everything you deleted
for this person" has to have a complete answer.

## If you cannot sign in

Both public pages carry a request form. Give us the email address on the account
and pick what to delete.

We then email a **verification link** to the address on file. Nothing is deleted
until you open it. If you did not make the request, ignoring that email is
enough — no action is taken.

The form's response is deliberately the same whether or not an account exists
for the address you typed, and we send no mail at all when there is no matching
account. That is not evasiveness: an unauthenticated form that answered
differently would be a way to test whether any given email has a TRaX account.

The link is good for 24 hours and works once. We answer every request within 30
days (GDPR: one month; CCPA: 45 days), and in practice far sooner — the
verified self-serve path runs immediately.

You can also email <privacy@traxstreaming.live> directly.

## Platform deauthorization

If you revoke TRaX from a connected platform's own settings — YouTube, Twitch,
Kick — we delete the chat history collected under that connection without
waiting to be asked. That deletion is recorded in the same log as everything
else, under the `platform_deauth` channel.

## The deletion log

Every deletion TRaX performs writes one row to an append-only table. It is the
answer to "prove you deleted this person's data."

Each row records: when it was requested, verified and completed; how it arrived
(self-serve, request form, platform deauthorization, or an operator); which
scopes were asked for and what happened to each one; what was retained and the
legal basis; and which law the request was made under.

What it does **not** record is who you are. The subject is an HMAC of your
account id under a server-held key, so the log can be kept forever without being
a store of personal data. If you come back and ask us to prove your deletion
happened, we recompute that hash from the account id you present and find the
row.

The table refuses `DELETE`, `TRUNCATE`, and any edit to a recorded fact at the
database level, not by convention. Timestamps and outcomes can be written once
and never rewritten.

## In the mobile app

The TRaX mobile app links to the same flow. Apple requires apps that create
accounts to offer account deletion in-app (App Store Review Guideline 5.1.1(v)),
and Google Play requires a publicly reachable URL explaining how to request it.
Both point at the pages above.

## For developers

| Method | Path | Auth | Notes |
|---|---|---|---|
| `GET` | `/api/account/me/privacy` | Bearer | Is the surface armed, and what is retained |
| `DELETE` | `/api/account/me` | Bearer | Full erasure. Returns `requestId` |
| `DELETE` | `/api/account/me/data/{scope}` | Bearer | `connections` \| `chat` \| `media` \| `studios` |
| `POST` | `/api/account/data-deletion/request` | None | Public form. Always `202` |
| `GET` | `/api/account/data-deletion/verify` | Signed link | Redeems and runs the erasure |

Every one of these returns `503` when the deletion log is not writable. That is
deliberate and it is the rule the whole feature is built on: **an erasure we
cannot record is an erasure we must not perform.**


<!-- reference/public-api -->


# Developer API (`/v1`)

The TRaX Developer API is a stable, versioned **HTTP + JSON** contract for
driving the platform from your own code — manage your studios, sources and
destinations, take a studio live or offline, read and send chat, manage linked
platform accounts, and work with your media library. It's separate from the web
studio's internal backend, so it doesn't move under you when the app changes.
Everything lives under a `/v1` prefix with a written compatibility promise:
additive changes within a major version, breaking changes only under a new
version with an overlap window.

> **Live on dev.** The API is **live now** on the development edge at
> `https://api-dev.traxstreaming.live/v1`. **Phases 1–3 are shipped:** reads +
> go-live/go-offline (Phase 1), studio / source / destination CRUD + connections
> (Phase 2), and chat + media library (Phase 3). Every mutating (write) endpoint
> is gated behind the deployment's `PUBLIC_API_WRITE_ENABLED` flag and returns
> `503 write_disabled` while off. A production base URL
> (`api.traxstreaming.live`) follows once the surface is stable — build against
> `/v1` today and only the host changes later.

**Fastest way in:** open the **[interactive API console](/reference/api-console)** —
paste your `sk_live_` key once, autofill real IDs from your account, run live
requests, and copy the exact `curl` / JavaScript / Swift for each endpoint.
Building with an AI agent? Point it at **[llms.txt](/llms.txt)** (index) or
**[llms-full.txt](/llms-full.txt)** (the whole API + guides in one file), or use
the per-endpoint **Copy for AI** button in the console.

## Base URL

```
https://api-dev.traxstreaming.live/v1
```

Every response carries an `X-Request-Id`. Errors share one envelope:

```json
{ "error": { "code": "…", "message": "…", "requestId": "…" } }
```

List endpoints are cursor-paginated: `{ "data": [ … ], "nextCursor": "…" }`
(pass `?cursor=…&limit=…` to page).

## Authenticating

`/v1` accepts **two kinds of Bearer credential**, and every route works with
either:

- an **API key** (`sk_live_…`) you create yourself — for server-to-server
  automation and integrations, and
- a **user access token (JWT)** from an interactive OAuth Authorization-Code +
  PKCE login — the path for a first-party mobile / desktop app that logs a user
  in.

The gateway tells them apart by the `sk_live_` prefix; anything else is
validated as a user JWT against the TRaX IdP. Both are sent the same way:
`Authorization: Bearer <credential>`.

### API keys

The API is authenticated with an **API key you create yourself**. From your
account's **Developer / API Keys** screen you can:

1. Create a key with a name and a set of **scopes**.
2. Copy the secret **once** — it's shown a single time and never again.
3. See your keys listed by prefix and last-used time, and revoke any of them.

A key acts as **you**, limited to the scopes you gave it, and can only ever
touch your own account's resources. Send it on each request as a Bearer token:

```bash
curl -sS "https://api-dev.traxstreaming.live/v1/studios" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

`X-API-Key: sk_live_…` is accepted as an alias for tools that reserve the
`Authorization` header:

```bash
curl -sS "https://api-dev.traxstreaming.live/v1/studios" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

### User access tokens (OAuth PKCE)

A **first-party app that logs a user in** can skip API keys and call `/v1`
directly with the user's access token — the same JWT the app already holds for
the WebSocket and WebRTC surfaces:

```bash
curl -sS "https://api-dev.traxstreaming.live/v1/studios" \
  -H "Authorization: Bearer <user-jwt>"
```

The token acts as **that user** with their full access — including `go-live` —
and, exactly like a key, can only ever reach that user's own resources
(per-tenant ownership is always enforced). Get the token from an Authorization
Code + PKCE login; [Build a client](/guides/build-a-client) walks the whole
flow (authorize URL, code exchange, refresh) and shows how the WebSocket +
WebRTC surfaces fit in. This is the recommended path for native mobile /
desktop clients.

The `meta` endpoints (`/v1/health`, `/v1/openapi.json`) need no auth. Every
other route requires a credential with the matching scope (a user JWT holds
every scope): a **401** means the credential is missing / unknown / revoked /
expired / an invalid token; a **403** names the scope you're missing.

## Endpoint reference

All routes are relative to the base URL above. `{id}` is a studio id.
**Write** rows (POST / PATCH / DELETE) are gated behind `PUBLIC_API_WRITE_ENABLED`
and return `503 write_disabled` while off.

| Method | Path | Scope | Returns |
|---|---|---|---|
| GET | `/v1/health` | — (public) | Liveness probe: `{ "status": "ok", "writeEnabled": … }` |
| GET | `/v1/openapi.json` | — (public) | This OpenAPI 3.0 document |
| GET | `/v1/studios` | `studios:read` | A page of the caller's studios |
| POST | `/v1/studios` | `studios:write` | Create a studio |
| GET | `/v1/studios/{id}` | `studios:read` | One studio |
| PATCH | `/v1/studios/{id}` | `studios:write` | Update a studio (name / auto-go-live) |
| GET | `/v1/studios/{id}/sources` | `sources:read` | A page of the studio's sources |
| GET | `/v1/studios/{id}/sources/{sourceId}` | `sources:read` | One source, with `publishing` — is anything arriving on this input right now. The endpoint to poll after an encoder dials in; see [Confirm you are live](/guides/stream-to-a-live-input#step-4--confirm-you-are-live) |
| POST | `/v1/studios/{id}/sources` | `sources:write` | Add a source |
| PATCH | `/v1/studios/{id}/sources/{sourceId}` | `sources:write` | Update a source |
| DELETE | `/v1/studios/{id}/sources/{sourceId}` | `sources:write` | Remove a source |
| POST | `/v1/studios/{id}/sources/{sourceId}/ingest` | `sources:ingest` | The SRT / RTMP(S) publish URLs for an input (a live credential; dev only today) — see [Stream to a live input](/guides/stream-to-a-live-input) |
| POST | `/v1/studios/{id}/sources/{sourceId}/ingest/rotate` | `sources:ingest` | Replace an input's publish credential and return the new URLs. The old ones stop working immediately; `kickPublishers` also cuts whoever is publishing right now — see [Rotate the key](/guides/stream-to-a-live-input#rotate-the-key) |
| GET | `/v1/studios/{id}/destinations` | `destinations:read` | A page of the studio's destinations |
| POST | `/v1/studios/{id}/destinations` | `destinations:write` | Add a destination (stream key is write-only) |
| PATCH | `/v1/studios/{id}/destinations/{destId}` | `destinations:write` | Update a destination |
| DELETE | `/v1/studios/{id}/destinations/{destId}` | `destinations:write` | Remove a destination |
| GET | `/v1/studios/{id}/audio` | `audio:read` | The studio's whole audio mix — the master strip plus one strip per source — in one read; see [Control the mixer](/guides/control-the-mixer) |
| PATCH | `/v1/studios/{id}/audio/sources/{sourceId}` | `audio:write` | Mute, unmute, or set level / pan / solo / trim on one source. A PATCH: omitted fields keep their value, so muting never moves the fader |
| PATCH | `/v1/studios/{id}/audio/master` | `audio:write` | Set the master level or mute. Muting silences the program on every destination |
| GET | `/v1/studios/{id}/stream-status` | `stream:read` | The studio's live / offline status + health |
| POST | `/v1/studios/{id}/go-live` | `stream:golive` | Take the studio live |
| POST | `/v1/studios/{id}/go-offline` | `stream:golive` | Take the studio offline |
| GET | `/v1/studios/{id}/chat/messages` | `chat:read` | Recent unified-chat messages |
| POST | `/v1/studios/{id}/chat/messages` | `chat:send` | Send a chat message (fans out to enabled platforms) |
| GET | `/v1/connections` | `connections:read` | The caller's linked platform accounts |
| DELETE | `/v1/connections/{connectionId}` | `connections:write` | Unlink a connection |
| GET | `/v1/media` | `media:read` | A page of the caller's media-library assets |
| POST | `/v1/media` | `media:write` | Initiate an upload (returns a presigned PUT) |

### Scopes

Scopes are the ceiling on what a key can do; you can only grant scopes you hold,
and access is always limited to your own tenant.

| Scope | Grants |
|---|---|
| `studios:read` / `studios:write` | List and manage your studios |
| `sources:read` / `sources:write` | List and manage sources |
| `sources:ingest` | Read an input's publish URLs (stream key included). Not implied by `sources:write`, and in no default set: the response is a live credential |
| `audio:read` / `audio:write` | Read a studio's audio mix, and move its faders and mutes. Not in any default set: the mix says who is muted and how loud each person is — a picture of the show, so you ask for it by name |
| `canvas:read` / `canvas:write` | Read a studio's canvas — who is on air, where each tile sits, which preset or scene is running — and change it. Not in any default set, and NOT implied by `studios:write`: a layout change is visible on air the instant it lands, with no undo |
| `destinations:read` / `destinations:write` | List and manage destinations |
| `stream:read` | Read live stream status / health |
| `stream:golive` | Take a studio live / offline |
| `connections:read` / `connections:write` | Manage linked platform accounts |
| `chat:read` / `chat:send` | Read and send chat |
| `media:read` / `media:write` | Read and upload media library assets (neither is a default — opt in when creating the key) |
| `webhooks:manage` | Register stream-event webhooks |

Phases 1–3 (live on dev) implement every route above: studios / sources /
destinations / stream (Phase 1 + 2 CRUD), connections (Phase 2), and chat +
media (Phase 3). `webhooks:manage` and OAuth-on-behalf-of client apps
(Phase 4+) are still on the [roadmap](/reference/roadmap) — the scopes are
listed so you can request keys that stay valid as those ship.

## OpenAPI spec & client generation

The live, machine-readable contract is served straight from the API:

**[`https://api-dev.traxstreaming.live/v1/openapi.json`](https://api-dev.traxstreaming.live/v1/openapi.json)**

Point Postman, Insomnia, or any OpenAPI tool at that URL. To generate a typed
client for a native app, feed the spec to
[`openapi-generator`](https://openapi-generator.tech/):

```bash
# iOS (Swift)
openapi-generator-cli generate \
  -i https://api-dev.traxstreaming.live/v1/openapi.json \
  -g swift5 -o ./trax-client-swift

# Android (Kotlin)
openapi-generator-cli generate \
  -i https://api-dev.traxstreaming.live/v1/openapi.json \
  -g kotlin -o ./trax-client-kotlin
```

Set the generated client's bearer token to your `sk_live_…` key and its base
path to `https://api-dev.traxstreaming.live/v1`.

Prefer a step-by-step SDK walkthrough? See the language quickstarts:
**[TypeScript / JS](/guides/sdk-typescript)** ·
**[Swift (iOS)](/guides/sdk-swift)** ·
**[Kotlin (Android)](/guides/sdk-kotlin)**. For a browsable, endpoint-by-endpoint
rendering of the spec, see the **[API reference (`/v1`)](/reference/api/v1)**.

## Cross-cutting contract

These behaviors are identical on every `/v1` endpoint — read them once:

- **[Errors & status codes](/reference/errors)** — the `{ error: { code, message,
  requestId } }` envelope and every stable `code`.
- **[Pagination](/reference/pagination)** — keyset `{ data, nextCursor }` and the
  `cursor` / `limit` parameters.
- **[Rate limits](/reference/rate-limits)** — per-key token bucket, `429` +
  `Retry-After`.
- **[Versioning & compatibility](/reference/versioning)** — what `/v1` promises
  and how to write a forward-compatible client.
- **[Webhooks](/reference/webhooks)** — *planned*; poll stream-status until they ship.
- **[Roadmap & status](/reference/roadmap)** — what's live on dev vs. planned.

## Beyond REST

The `/v1` REST API is the right surface for **headless read and automation**
(dashboards, bots, server-to-server jobs). A rich client that also **produces a
show** — controls a studio in real time, publishes camera/mic, watches the
program — combines REST with the WebSocket control plane and WebRTC media
plane. See **[Build a client](/guides/build-a-client)** for the full transport
map and how to authenticate each one.

Tell us what you want to build — it shapes what ships first.


<!-- reference/api-console -->


# API console — try `/v1` live

Run real, authenticated requests against the TRaX Developer API (`/v1`) right
here, then copy the exact `curl`, JavaScript, or Swift you need. Every panel
below is generated from the live [OpenAPI spec](https://api-dev.traxstreaming.live/v1/openapi.json)
(version rendered in the toolbar), so it always matches the real contract.

## Set your key once

The `/v1` gateway authenticates with a **user-scoped API key** — send it as
`Authorization: Bearer sk_live_…`. The docs login (your staff session) is a
*different* credential and is **not** accepted by `/v1`, so paste your
`sk_live_` key in the **API key** box below one time. It is stored in this
browser only (localStorage), masked on screen, sent only to the API at request
time, and never logged. API keys are operator-provisioned today — ask the TRaX
team for one.

## Autofill from your account

Click **Load my account** (or **Autofill from my account** on any endpoint) and
the console fetches your real studios, sources, destinations and connections and
turns path parameters like `{id}` into pickers of your actual IDs — so a real
call is one click away.

## Try it, or take the snippet

- **Send** makes the real request and shows the live status, timing, headers,
  and JSON response.
- Prefer to run it yourself? Every endpoint emits copy-paste **curl / JS fetch /
  Swift** built from your current values, plus a **Copy for AI** button that
  yields the whole endpoint spec + example as one markdown blob to hand an LLM.
- Building a client end-to-end? See **[Build a client](/guides/build-a-client)**,
  the full **[/v1 reference](/reference/api/v1)**, and the machine-readable
  **[llms.txt](/llms.txt)** / **[llms-full.txt](/llms-full.txt)**.

> **Live requests need CORS.** Because Send runs from your browser, the `/v1`
> gateway must allow this docs origin (an `Access-Control-Allow-Origin` header +
> `OPTIONS` preflight). If Send reports a network error, that hasn't been
> enabled yet — the copy-paste snippets work from your terminal or app in the
> meantime. Write endpoints (`POST`/`PATCH`/`DELETE`) return `503 write_disabled`
> until the deployment turns writes on.

---


<!-- reference/authentication -->


# Authentication & session tokens

TRaX has **two separate credential systems** — don't mix them up:

| System | Credential | Used on |
|---|---|---|
| **Media plane** | A short-lived **ES256 session JWT** (`iss: trax-studio-api`), or a stream key | SRT / RTMP / WHIP / WHEP publish + read — see below |
| **`/v1` Developer API** | An **`sk_live_…` API key**, *or* a **Zitadel user access token** (the OIDC + PKCE login token) | `Authorization: Bearer …` on `/v1` — see [User login](#user-login-for-mobile-and-native-apps-oidc-pkce) and [Using the token at /v1](#using-the-token-at-v1) |

They are minted by different issuers and validated by different code. A
media-plane session JWT does **not** authenticate `/v1`, and a `/v1` credential
does **not** authorize a media publish. This page starts with the media-plane
session JWT; the `/v1` login token is the last section.

## Media-plane session JWTs

Every authenticated surface on the TRaX media plane accepts a **session JWT**:
a short-lived, ES256-signed token minted by the TRaX platform. There are no
long-lived shared secrets in the media path.

> **Access is operator-provisioned today.** TRaX does not yet offer self-serve
> API-key or token issuance for third parties — session tokens are minted by the
> platform for its own applications, and for partners by hand. Self-serve
> issuance is a separate, tracked design effort. Until it ships, contact the
> TRaX team to get credentials.

## Token shape

Session JWTs are compact JWS tokens, signed with **ES256** (ECDSA P-256 + SHA-256).

Key claims:

| Claim | Meaning |
|---|---|
| `iss` | `trax-studio-api` — the minting service |
| `aud` | The consuming surface. Media-plane audiences: `trax-mediamtx` (SRT/RTMP publish + read), `trax-mediamtx-talk` (WebRTC talk/publish), `trax-mediamtx-read` (single-path WebRTC read) |
| `action` | What the token authorizes: `publish` or `read` |
| `path` | The exact stream path the token is bound to |
| `exp` | Short TTL — tokens are minted per session/purpose, not stored |

The `action` + `path` claims bind a token **1:1 to one operation on one path**. A
publish token for one path cannot read another path; token reuse across paths is
rejected at the media edge.

## Verifying TRaX tokens (JWKS)

The platform publishes its current signing keys at:

```
https://<trax-api-host>/.well-known/jwks.json
```

Standard JWKS semantics apply: match the token's `kid` header to a key in the
set, verify the ES256 signature, then validate `exp`, `iss`, and the `aud` you
expect. Keys are stable across service restarts; rotate-tolerant verifiers
should refetch the JWKS on an unknown `kid`.

## Where the token goes, per protocol

| Protocol | Credential placement |
|---|---|
| SRT | Inside the `streamid`: `publish:<path>:<stream-key>:<stream-key>` — see [SRT streamid contract](/reference/srt-streamid) |
| RTMP / RTMPS | URL query string: `rtmp://host:1935/<path>?user=<stream-key>&pass=<stream-key>` — see [RTMP contract](/reference/rtmp) |
| WHIP / WHEP | `Authorization: Bearer <jwt>` header — see [WHIP / WHEP](/reference/whip-whep) |

## Stream keys

Publishing to an input over SRT or RTMP is authenticated by the input's
**stream key**, not by a JWT. The key is minted when the input is created and
is handed to you already embedded in a publish URL: by
[`POST /v1/studios/{id}/sources/{sourceId}/ingest`](/guides/stream-to-a-live-input)
or by the studio's Connection Information panel. It occupies both credential
positions of the SRT streamid and both RTMP query parameters. Treat stream keys
like passwords: they do not expire on their own, and a deleted input's key
stops authenticating. RTMP credentials in the URL's userinfo
(`rtmp://user:pass@host/…`) are not read by the ingest server.

## User login for mobile and native apps (OIDC + PKCE)

The tokens above are **media-plane session JWTs** the platform mints for a
specific publish/read operation. A **first-party app a user signs into** — a
native iOS or Android app — needs something different: a token that says *who
the user is*, so the app can call the [`/v1` Developer API](/reference/api/v1)
**as that user**. That token is an **OIDC access token (JWT)** minted by the
TRaX identity provider (Zitadel), obtained with the standard **OAuth 2.0
Authorization-Code flow with PKCE**.

This is the login path for user-facing mobile apps. It is platform-agnostic;
the platform-specific code lives in the SDK guides:

- **iOS / Swift** — [SDK quickstart: Swift](/guides/sdk-swift#sign-the-user-in-oidc-pkce)
  (`ASWebAuthenticationSession`)
- **Android / Kotlin** — [SDK quickstart: Kotlin](/guides/sdk-kotlin#sign-the-user-in-oidc-pkce)
  (AppAuth / Custom Tabs)

> **Why PKCE against the hosted login?** The app opens the identity provider's
> **hosted login page** in a system browser, so the user's password (and MFA /
> passkeys, when enabled) is entered in the IdP — never in your app. PKCE
> (Proof Key for Code Exchange, S256) replaces a client secret, which a shipped
> mobile binary can't keep secret anyway. This is a **public client**: no
> secret is embedded in the app.

### Endpoints

The IdP is a plain OIDC provider — every value below also appears in its
discovery document at `<issuer>/.well-known/openid-configuration`.

| | Development | Production |
|---|---|---|
| Issuer | `https://auth-dev.traxstreaming.live` | `https://auth.traxstreaming.live` |
| Authorize | `…/oauth/v2/authorize` | `…/oauth/v2/authorize` |
| Token | `…/oauth/v2/token` | `…/oauth/v2/token` |
| JWKS | `…/oauth/v2/keys` | `…/oauth/v2/keys` |
| End session (logout) | `…/oidc/v1/end_session` | `…/oidc/v1/end_session` |

**Client id (dev):** `385862192278274086` — a **public native client** (no
secret). The production client id is issued separately when the app is
registered in the production IdP; request it with your production credentials.

**Scopes:** `openid profile email offline_access`. The `offline_access` scope is
what gets you a **refresh token** for silent re-login.

**Redirect URI:** the app registers a **custom URI scheme** (or a verified
https App Link / Universal Link) that the browser hands the authorization code
back on — e.g. `live.traxstreaming.ios://oauth/callback` on iOS and
`live.traxstreaming.android://oauth/callback` on Android. These are placeholders
until the real app identifiers exist; the registered value must match what the
app sends **exactly**.

### The flow

1. **Generate a PKCE pair** — a random `code_verifier`, and
   `code_challenge = BASE64URL(SHA256(code_verifier))`.
2. **Open the authorize URL** in a system browser
   (`ASWebAuthenticationSession` / Custom Tab — never an embedded webview) with
   `response_type=code`, your `client_id`, `redirect_uri`, `scope`,
   `code_challenge`, `code_challenge_method=S256`, and a random `state`. The
   user signs in on the hosted page.
3. **Capture the callback** on your custom scheme — you receive
   `?code=<authorization_code>&state=…`. Verify `state` matches what you sent.
4. **Exchange the code** at the token endpoint (`grant_type=authorization_code`,
   with `code`, `redirect_uri`, `client_id`, and the `code_verifier` — no
   secret). You get back an **`access_token` (JWT)**, a **`refresh_token`**, and
   `expires_in`.
5. **Call `/v1`** with `Authorization: Bearer <access_token>`.
6. **Refresh silently** with `grant_type=refresh_token` before the access token
   expires — no browser round-trip.
7. **Log out** by clearing stored tokens and, to end the IdP session, redirecting
   to the end-session endpoint.

### Using the token at `/v1`

`/v1` accepts this user access token directly: send
`Authorization: Bearer <access_token>` and the request runs **as the user**,
with their full scope set. `/v1` accepts exactly two credential types,
discriminated by prefix:

- an **`sk_live_…` / `sk_test_…` API key**, verified against the account service, or
- **anything else** — treated as a **Zitadel user access token** and validated
  against the identity provider's JWKS.

The token is validated by running **OIDC discovery against the Zitadel issuer**
(`https://auth-dev.traxstreaming.live` in dev, `https://auth.traxstreaming.live`
in prod) and checking **issuer + signature + expiry** against Zitadel's keys.
The mobile PKCE token drops straight onto `/v1` with **no special claim
required** — no custom scope, no audience value to set.

> **`/v1` trusts Zitadel only.** It does **not** accept the media-plane
> `trax-studio-api` ES256 session JWT described at the top of this page — that
> is a different subsystem (media surfaces + the studio browser session), not a
> `/v1` credential. For `/v1`, use an API key or a Zitadel user token.

> **The access token must be a JWT**, not an opaque bearer token. `/v1`
> validates it by *parsing* it against Zitadel's JWKS; an opaque token fails to
> parse and returns `401`. The `trax-mobile` client is configured to mint JWT
> access tokens, so this is already correct — just don't repoint the app at a
> client that issues opaque tokens.

> **Audience is not checked (yet).** `/v1` verifies **issuer, signature, and
> expiry**, but **not** the `aud` (audience) claim — so *any* valid user token
> the TRaX Zitadel instance issued is accepted, regardless of which client
> minted it. Audience pinning is a tracked hardening follow-up (#382). Two
> consequences: (1) your mobile token needs no special `aud`/scope to work, and
> (2) because it is not audience-scoped, treat the access token as a
> first-class credential — keep it in the Keychain / Keystore, keep it
> short-lived, and refresh rather than stashing a long-lived copy.

### Token storage

Store the refresh token — and the access token — in the platform secure store,
never in plain app storage or source:

- **iOS** — the **Keychain** (`kSecClassGenericPassword`, with an appropriate
  `kSecAttrAccessible` such as `…WhenUnlockedThisDeviceOnly`).
- **Android** — **EncryptedSharedPreferences** or a key from the **Android
  Keystore**.

Treat the refresh token like a password: it is long-lived and can mint new
access tokens. Wipe both on logout.


<!-- reference/srt-streamid -->


# SRT: the streamid contract

SRT is the recommended contribution protocol for TRaX: encrypted, loss-tolerant,
low-latency. All routing and authentication for an SRT connection rides in the
**streamid** field.

## Format

```
<action>:<path>:<user>:<pass>
```

| Field | Values |
|---|---|
| `action` | `publish` (send a feed) or `read` (pull a feed) |
| `path` | The stream path (see [path grammar](/reference/path-grammar)); `inputs/generic-input-<id>` for an input created over `/v1` |
| `user` / `pass` | The credential. For publishing to an input, the input's **stream key** in both positions |

Complete publish URL:

```
srt://<trax-media-host>:8890?streamid=publish:<path>:<stream-key>:<stream-key>
```

You do not assemble this yourself. The `complete` field of the
[ingest endpoint](/guides/stream-to-a-live-input#step-2--get-the-publish-urls)
(or the studio's Connection Information panel) hands you the whole URL; the
studio may also append `&latency=` and `&oheadbw=` tuning to it, which the
sender applies.

Reading uses the same grammar with `action` = `read` and a read credential the
platform issues for that path.

## Hard rules

1. **Do not URL-encode the streamid.** The SRT library and the TRaX edge parse the
   raw string with literal `:` delimiters. Encoders that percent-encode the
   streamid fail authentication.
2. **512-byte cap.** libsrt hard-caps the streamid at 512 bytes. A stream-key
   streamid is well under that; never append extra fields to it or wrap it in
   anything. Overflow does not fail cleanly: the sender typically dies within
   the first second with an unhelpful `Bad parameters` / rejected-handshake
   error.
3. **One key, one path, one action.** The key authenticates publishing to the
   path it was issued for, and nothing else. A key from one input does not open
   another.

## Failure modes

| Symptom | Likely cause |
|---|---|
| Immediate disconnect (<1s), `Bad parameters` | streamid over 512 bytes, or edited |
| Handshake rejected | URL-encoded streamid, a mangled or revoked key, or a key used against a different `path` |
| Connects, no media routed | Wrong `path`: the connection authenticated but the path isn't the input you expect |

## Encoder quick reference

ffmpeg:

```bash
ffmpeg -re -i input.mp4 -c copy -f mpegts \
  "srt://<trax-media-host>:8890?streamid=publish:<path>:<stream-key>:<stream-key>"
```

OBS: Settings → Stream → Service *Custom*, server
`srt://<trax-media-host>:8890?streamid=publish:<path>:<stream-key>:<stream-key>`,
stream key empty. libsrt: set `SRTO_STREAMID` to everything after `streamid=`.
See the [OBS / ffmpeg quickstart](/guides/obs-ffmpeg-quickstart).


<!-- reference/rtmp -->


# RTMP / RTMPS: the query-string credential contract

RTMP is the maximum-compatibility ingest path. TRaX authenticates RTMP with
credentials in the URL **query string**: `?user=` and `?pass=`. Not a
`/live/<key>` path suffix, and not the URL's userinfo section.

## Format

```
rtmp://<trax-media-host>:1935/<path>?user=<stream-key>&pass=<stream-key>
rtmps://<trax-media-host>:1936/<path>?user=<stream-key>&pass=<stream-key>
```

The stream key fills both parameters. The `<path>` is the input's stream path
(`inputs/generic-input-<id>` for an input created over `/v1`), the same grammar
as [SRT](/reference/srt-streamid) and [WHIP/WHEP](/reference/whip-whep). You
do not assemble this URL yourself: the `complete` field of the
[ingest endpoint](/guides/stream-to-a-live-input#step-2--get-the-publish-urls),
or the studio's Connection Information panel, hands it to you whole.

## Hard rules

1. **Credentials go in the query string.** The ingest server reads `user` and
   `pass` from the query and nowhere else. `rtmp://host/live/<key>` does not
   authenticate. `rtmp://<user>:<pass>@host/<path>` (userinfo) does not
   authenticate either: the server reads an empty user and refuses the connect.
   Older TRaX material showed the userinfo form; it is dead.
2. **Encoders with a split Server / Stream Key field.** OBS, Streamlabs and vMix
   publish to `<Server>/<Stream Key>`, so split the URL at its last `/`:
   Server `rtmp://<host>:1935/inputs`, Stream Key
   `generic-input-<id>?user=<key>&pass=<key>`. The query string travels with the
   key, which is where the server expects it. ffmpeg and other single-URL
   encoders take the whole URL as-is.
3. **RTMPS for anything you would not say out loud.** Plain RTMP (1935) is
   unencrypted; the key is visible on the wire. Prefer RTMPS (1936) or SRT.
4. **The key does not expire.** Authentication happens at connect time and the
   stream key is static for the life of the input, so an encoder's
   auto-reconnect can redial the same URL indefinitely. Revocation is
   [rotating the key](/guides/stream-to-a-live-input#rotate-the-key) (once
   that endpoint is live) or deleting the input.

## Failure modes

| Symptom | Likely cause |
|---|---|
| Connection refused / auth error at connect | Credentials in userinfo or the path instead of the query string; a mangled or revoked key |
| Auth OK but stream not visible | Wrong `<path>`: authenticated to an input that is not the one you think |
| Works in ffmpeg, refused from OBS | The split is wrong. The query string must be on the Stream Key side of the `/`, and Server must end at `/inputs` |


<!-- reference/whip-whep -->


# WHIP / WHEP: WebRTC publish and play

WHIP (publish) and WHEP (play) are the standard HTTP-signaled WebRTC ingest and
egress protocols. They are the lowest-latency way in and out of TRaX and work
natively from a browser.

## Endpoints

```
POST https://<trax-media-host>:8889/<path>/whip     # publish
POST https://<trax-media-host>:8889/<path>/whep     # play
```

Standard WHIP/WHEP semantics: POST an SDP offer (`Content-Type: application/sdp`),
receive an SDP answer, ICE via the returned resource. TRaX also returns TURN
servers in the signaling response where relay is required.

## Authentication

Send the session token as a Bearer header:

```
Authorization: Bearer <jwt>
```

Two token audiences exist for the WebRTC plane:

| Token | Purpose |
|---|---|
| talk token (`aud: trax-mediamtx-talk`) | Publish-capable, scoped to your provisioned session; carries a `can_publish` claim |
| read token (`aud: trax-mediamtx-read`) | Single-path, short-TTL playback |

Where a Bearer header is impossible (some players), the token is also accepted
as an `access_token` query parameter on the WHIP/WHEP URL. Prefer the header —
query strings end up in logs.

## Hard rules

1. **One token per path.** The token's `path` claim must match the URL path.
2. **Short TTLs.** Read tokens especially are minted per playback session —
   don't cache them.
3. **Audio codec:** WebRTC audio is Opus. Feeds contributed over SRT/RTMP with
   AAC audio are transparently transcoded for WHEP playback; expect Opus on the
   receiving side.

## Failure modes

| Symptom | Likely cause |
|---|---|
| `401` on the POST | Missing/expired token, wrong audience for the operation |
| `404` | Path not provisioned (or a typo — paths are exact-match) |
| Connects, video but no audio in browser | Player expecting AAC — WebRTC delivers Opus |


<!-- reference/api/v1 -->

> **GENERATED** from `trax-public-api /v1 openapi.json (baked copy: scripts/specs/v1-openapi.json)` by `scripts/sync-generated.sh` — do not edit by hand.
> Baked copy. Refresh with: `cp ../trax-public-api/internal/openapi/openapi.json scripts/specs/v1-openapi.json && npm run sync`.

# TRaX Developer API — `/v1` reference

> **This page is generated from the `/v1` OpenAPI 3.0 spec.** The live, machine-readable contract is served at [`https://api.traxstreaming.live/v1/openapi.json`](https://api.traxstreaming.live/v1/openapi.json) — point Postman, Insomnia, or a codegen tool at that URL. This page is a browsable rendering of the same spec (version `1.16.0`).

The versioned public developer API for TRaX. Authenticate one of two ways: (1) a user-scoped API key — `Authorization: Bearer sk_live_...` (or the `X-API-Key` alias) — for server-to-server integrations; or (2) an interactive-login user JWT — `Authorization: Bearer <oidc-jwt>` — obtained from an OAuth Authorization-Code + PKCE login against the TRaX IdP, the path for native iOS/Android apps. A user JWT acts as that user with their full access; per-tenant ownership is always enforced. Every response carries an `X-Request-Id`. Errors share one envelope: `{ "error": { "code", "message", "requestId" } }`. List endpoints are cursor-paginated: `{ "data": [ ... ], "nextCursor": "..." }`. Phases 1-3 are LIVE: reads + gated go-live (Phase 1), studio/source/destination CRUD + connections (Phase 2), and chat + the media library (Phase 3) — including the full upload lifecycle, large files in presigned parts, and attaching a library asset to a studio by id. The audio mixer and the CANVAS are live too: read the whole canvas in one conditional call, move a tile, pick a preset, recall a scene, or hand the arrangement back to the auto planner. Phase 8 (#597) adds the phone go-live path: `POST /v1/studios/{id}/contribute` provisions a device's input and its publish credential in one idempotent call, and `POST /v1/studios/{id}/monitor` mints the return feed. The reads a client polls — stream-status, the source list, and a single source — support `ETag` / `If-None-Match` and answer 304, which matters on a cellular link. Mutating endpoints are gated behind PUBLIC_API_WRITE_ENABLED and return 503 write_disabled while off. See trax-dev/docs/public-api-platform-design.md.

## At a glance

- **Base URL:** `https://api.traxstreaming.live` — every path below is absolute (e.g. `GET /v1/studios`).
- **Authentication:** `Authorization: Bearer sk_live_...` (or the `X-API-Key` header), or an interactive-login user JWT (`Authorization: Bearer <oidc-jwt>`, the native-app OAuth + PKCE path) — see [Authentication](/reference/authentication). The `meta` endpoints (`/v1/health`, `/v1/openapi.json`) need no auth.
- **Errors:** one envelope, `{ "error": { "code", "message", "requestId" } }` — see [Errors & status codes](/reference/errors).
- **Lists:** cursor-paginated, `{ "data": [ … ], "nextCursor": "…" }` — see [Pagination](/reference/pagination).
- **Rate limits:** per-key token bucket, `429 + Retry-After` — see [Rate limits](/reference/rate-limits).

## Endpoints

### meta

Health + spec (unauthenticated)

#### `GET /v1/health`

Liveness probe (unauthenticated).

**Auth:** none (public).

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | Service is up. | `Health` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/openapi.json`

This OpenAPI 3.0 document (unauthenticated).

**Auth:** none (public).

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The OpenAPI spec. | `object` |
| `default` | Error envelope. | `Error` |

### studios

Studios, sources, destinations, stream status

#### `GET /v1/studios`

List the caller's studios.

Requires scope studios:read.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `cursor` | query | no | Opaque pagination cursor from a prior response's nextCursor. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A page of studios. | `StudioList` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios`

Create a studio.

Requires scope studios:write. Gated behind PUBLIC_API_WRITE_ENABLED.

**Auth:** API key required.

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | The created studio. | `Studio` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}`

Get one studio.

Requires scope studios:read.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The studio. | `Studio` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}`

Update a studio (name / auto-go-live settings).

Requires scope studios:write. Gated behind PUBLIC_API_WRITE_ENABLED. There is no studio delete on the public API.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The updated studio. | `Studio` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/audio`

Read the studio's audio mix.

Requires scope `audio:read`.

The whole mix in one call: the master strip plus one strip per source. One call, not one per source, because a mixer surface draws every fader at once and asking per source would let the strips disagree with each other mid-render.

Every source row gets a strip, including sources with no audio track. The strip is per-source state that persists and replays to the encoder, so hiding rows here would make this API's idea of "the mix" narrower than the operator's own panel. Read `active` and `type` to decide what your UI draws.

A source nobody has touched in the mixer reports the RUNNING defaults — volume 1.0, unmuted, centre, trim 1.0, no groups — not an absence. Those are the values the encoder is applying to it, so reporting them is a measurement rather than a guess.

`volume` is a LINEAR gain, not decibels: 0.0 silent, 1.0 unity (0 dB), above 1.0 amplifies, ceiling 10.0. `pan` is -1.0 full left … +1.0 full right. `trim` is the pre-fader input gain, linear, 1.0 nominal.

MUTE IS NOT VOLUME ZERO. `muted` is an independent gate and the fader keeps its position underneath it, so unmuting returns to exactly the level the operator was at.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The studio's mix. | `StudioAudio` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}/audio/master`

Set the master level or mute.

Requires scope `audio:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

A PATCH: send only the fields you are changing, and the rest keep their current values. Sending `{"muted": true}` does not move the master fader.

Muting the master silences the program for every viewer on every destination while leaving each source's own strip untouched. To silence one contributor, patch that source instead.

`volume` is the same LINEAR scale as a channel fader: 0.0 silent, 1.0 unity, ceiling 10.0. A value outside the range is a 400, not a clamp — a client that believed it was sending decibels should find out.

The master strip has a fader and a mute and nothing else, which is the actual shape of the master strip in the studio.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The updated master strip. | `AudioMaster` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}/audio/sources/{sourceId}`

Set one source's level, mute, pan, solo or trim.

Requires scope `audio:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

A PATCH: send only the fields you are changing. `{"muted": true}` mutes the channel and leaves the level, pan, solo and trim exactly where they were — which is what lets a phone mute a mic without knowing, or clobbering, the mix an operator set on a laptop.

SET `muted`; DO NOT write `volume: 0` and call it mute. Mute is an independent gate and the fader keeps its position underneath, so unmuting returns to the level the operator was at. Collapsing the two loses that position.

This reaches the same control path the TRaX studio's own mixer uses. On a live studio the change is immediate and audible, and every open studio tab re-renders the fader. On an idle studio it persists and applies at the next go-live.

Units: `volume` LINEAR 0.0–10.0 (1.0 = unity, 0 dB — not decibels), `pan` -1.0–1.0, `trim` LINEAR 0.1–16.0. Anything outside those ranges is a 400 rather than a silent clamp.

`soloed` is a mixing-desk intent flag synced across the studio's operators; it does not by itself mute the other channels.

`muteGroups` is read-only — it is returned by the mix read but cannot be set here, because the group MASTER button that gives membership its meaning lives in the studio's mixer panel.

A `sourceId` from a studio you cannot see answers 404 `studio not found`, identical to a source that does not exist.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `sourceId` | path | yes | Source id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The updated channel strip, in full. | `AudioSourceStrip` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/contribute`

Put a device on a studio and get its publish credential.

Requires scopes `sources:ingest` AND `sources:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

This is the one call a phone cannot go live without. It provisions — or re-finds — this device's input on the studio and hands back the credential to publish into it, in a single round trip. If it succeeds you can start pushing video; if it fails there is no stream, and nothing else on this API changes that.

It needs BOTH scopes because it does two separable things: it CREATES an input on the studio (`sources:write`) and it hands back a LIVE PUBLISH CREDENTIAL (`sources:ingest`). Those two deliberately do not imply each other in either direction, so a key holding only one would be doing half of this without having asked for that half. Tick both when you mint the key.

IDEMPOTENT per (owner, studio, `deviceId`) — and that is a contract, not an implementation detail you should avoid relying on. Send the same `deviceId` and you get the same input, the same media path and the same credential, every time. **201** the first time, **200** on every call after. A phone on a bad uplink can send this three times and end up with one input.

Retrying is SAFE, including after a timeout where you never saw the response. Nothing here rotates a credential, so a retry cannot invalidate the key the timed-out attempt already issued. That is why rotation is a separate endpoint with its own name: `POST /v1/studios/{id}/sources/{sourceId}/ingest/rotate` destroys the old credential deliberately, and this call never does it by accident.

Same writer as the TRaX app's own contribute flow, so an input provisioned here and one provisioned in the app are the same row with the same reconnection behaviour — there is no second provisioning path to drift from.

`ingestHost` and `ingestMetro` tell your user where they are publishing. `ingestMetro` is `"auto"` today because the nearest point of presence is chosen in DNS when your device resolves the hostname, not by this call — display it, do not branch on it.

Rate limited in the credential-handout class, roughly 5 per minute per caller with a small burst. A real client calls this once per session and again on reconnect. On 429 the response carries `Retry-After`; wait that long rather than guessing.

Answers **503 `contribute_disabled`** when the deployment has the device-contribute path switched off. That is not a transient failure and it carries no `Retry-After` — retrying will never make it succeed.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | This device already had an input on this studio. Same input, same credential — your earlier call created it. | `Contribution` |
| `201` | The input was created by this call. | `Contribution` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/destinations`

List a studio's destinations.

Requires scope destinations:read.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `cursor` | query | no | Opaque pagination cursor from a prior response's nextCursor. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A page of destinations. | `DestinationList` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/destinations`

Add a destination to a studio.

Requires scope destinations:write. Gated behind PUBLIC_API_WRITE_ENABLED. The stream key is write-only and never returned.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | The created destination. | `Destination` |
| `default` | Error envelope. | `Error` |

#### `DELETE /v1/studios/{id}/destinations/{destId}`

Remove a destination.

Requires scope destinations:write. Gated behind PUBLIC_API_WRITE_ENABLED.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `destId` | path | yes | Destination id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The destination was removed. | `Ok` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}/destinations/{destId}`

Update a destination.

Requires scope destinations:write. Gated behind PUBLIC_API_WRITE_ENABLED.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `destId` | path | yes | Destination id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The updated destination. | `Destination` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/events`

Stream studio state changes (Server-Sent Events).

The push channel that replaces polling. Open it once and you are told when something changes, instead of asking every few seconds whether anything did — which is what a phone on cellular should not be spending its uplink on while it is also publishing.

Requires scopes stream:read, sources:read and destinations:read — the same three permissions the three reads it carries require. No new scope: a stream that carries exactly what those GETs return needs exactly what they need.

**Format.** `text/event-stream`, one event per frame:

```
id: 9f2c1a4b7e3d-12
event: source
data: {"id":"...","publishing":true, ...}
```

**Event types and their `data`, which are the SAME shapes the equivalent GETs return:**

| `event` | `data` |
| --- | --- |
| `snapshot` | `{ sources: Source[], streamStatus: StreamStatus, destinations: Destination[], chatConnectors: ChatConnector[] }` |
| `source` | a `Source` — created, changed, or its `publishing` flipped |
| `streamStatus` | a `StreamStatus` |
| `destination` | a `Destination` |
| `chatConnector` | a `ChatConnector` — a linked platform's reconnect pill state changed |
| `chatConnectorRemoved` | `{ platform }` — a platform was unlinked; drop its connector |
| `canvas` | a `CanvasState` — the layout mode, active preset/scene, and per-source placements all in one; replace your whole canvas |
| `audio` | a `StudioAudio` — the master strip plus one strip per source; replace your whole mixer |
| `sourceRemoved` | `{ id }` — drop that source |
| `destinationRemoved` | `{ id }` — drop that destination |

Apply an event by replacing the row it names. There is no partial-update form: a client that applies every event ends up identical to one that re-read the collections.

**Snapshot first.** The first event on a fresh stream is a `snapshot` of full current state, so opening this stream IS your initial read — you do not need to GET anything to prime yourself.

**Resuming.** Every event carries an opaque `id`. Reconnect with the standard `Last-Event-ID` header (or `?lastEventId=`) set to the last id you processed and the server replays what you missed. The replay window is bounded, so an id the server cannot honour is NOT an error: you get a fresh `snapshot` and carry on. Always send your last id; never fall back to re-GETting the collections. Treat the id as opaque — do not parse or compare it.

**Keepalives.** On an idle studio the server sends SSE comment lines (`: heartbeat <RFC3339>`), which keep cellular NATs and proxies from reaping the connection. Comments are not events; a standard EventSource client ignores them for you. If you write your own client, use them to reset a dead-stream timer.

**Limits.** At most 5 concurrent event streams per credential (429 with `Retry-After` beyond that), and at most 32 concurrent watchers on one studio. The stream ENDS when your access does — deleting the studio or revoking the key terminates it rather than leaving a socket attached to something that is gone.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `Last-Event-ID` | header | no | The id of the last event you processed, to resume after a dropped connection. An id the server cannot honour yields a fresh snapshot rather than an error, so it is always safe to send. |
| `lastEventId` | query | no | Query alias for the Last-Event-ID header, for clients that cannot set it. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The event stream. Stays open until the client disconnects or access ends. | — |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/monitor`

Get the return feed — watch the program while you publish into it.

Requires scope `viewer:tokens`. Gated behind PUBLIC_API_WRITE_ENABLED.

Issues a short-lived, read-only credential for the studio's PROGRAM output: what the show is actually sending, right now. It is the app's version of the operator's program monitor, and it is what tells the person holding the camera that their shot is on air.

The scope is `viewer:tokens` rather than a `:read` scope for a reason worth knowing before you mint a key. This hands back a credential that PLAYS THE PROGRAM — a media credential, not a row of JSON — and `stream:read` is a DEFAULT scope that every casually created key carries forever. `viewer:tokens` is the scope this platform already uses for minting media playback credentials, it is opt-in by name, and any key holding it can already mint a `video.play` token for the same studio through `POST /v1/viewer-tokens`. So requiring it here grants nothing your key could not already do; it just refuses to give this power away to a key that never asked for it.

SHORT-LIVED and re-mintable: 300 seconds by default, 900 maximum, clamped rather than refused. That costs less than it sounds. The media server authorises a read once, at session ESTABLISHMENT, and never re-checks — so a monitor that is already playing keeps playing past `expiresAt`. Mint again to (re)CONNECT, not to keep watching, and schedule from `expiresAt` rather than from the TTL you requested.

Take the WHEP path: `whep.url` with `Authorization: Bearer whep.token` on the signaling POST. WebRTC survives a lossy cellular uplink far better than the alternative. `srt` is there for clients that cannot speak WHEP and is `null` when a dialable URL cannot be built — the credential rides inside SRT's 512-byte streamid cap, and a URL over it is rejected by the client's own SRT library before it reaches the network, so the server declines to hand back one that cannot work.

The credential is always issued when you may hold it. Whether FRAMES flow depends on the studio being live with its program preview published — a monitor opened off-air simply shows nothing yet. That is a state to render, not an error to report.

Same rate-limit class as the credential endpoints, roughly 5 per minute per caller with a small burst.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The return-feed credential. | `Monitor` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/sources`

List a studio's sources.

Requires scope sources:read.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `cursor` | query | no | Opaque pagination cursor from a prior response's nextCursor. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A page of sources. | `SourceList` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/sources`

Add a source to a studio.

Requires scope `sources:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

To put a library file on the canvas, send `mediaAssetId` with a library-backed `type` (`video-file`, `image`, `audio-file`, `media`) and no `url` — the server resolves the encoder-facing URL itself and refreshes it as it expires, so you never hold a storage credential. `url` and `mediaAssetId` are mutually exclusive; sending both is a 400.

For a live input (`generic-input`, `srt`, `rtmp`) send neither and read the publish endpoints back from `POST /v1/studios/{id}/sources/{sourceId}/ingest`.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | The created source. | `Source` |
| `default` | Error envelope. | `Error` |

#### `DELETE /v1/studios/{id}/sources/{sourceId}`

Remove a source.

Requires scope sources:write. Gated behind PUBLIC_API_WRITE_ENABLED.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `sourceId` | path | yes | Source id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The source was removed. | `Ok` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/sources/{sourceId}`

Read one source.

Requires scope `sources:read`.

The same object `GET /v1/studios/{id}/sources` returns, for one input. It exists to be POLLED: after a device dials the URLs from `POST .../ingest`, this is how the device confirms the media actually arrived.

Read `publishing`, not `status`. `status` is the control-plane provisioning state and says `OK` for a perfectly configured input that nobody is publishing to — it has never meant "live". `publishing` is media-plane truth: is a publisher attached to this input's path right now. It is the same signal the TRaX studio's own source LEDs burn, so the API and the UI cannot disagree.

`publishing` is nullable, and null is a THIRD answer. It means the liveness tracker could not be reached on this request: unknown, not offline. A poll loop must keep asking; treating null as "my stream is down" is exactly the wrong move during a blip.

`publishedAt` is when the CURRENT publish began, not when we last noticed it — it holds still while the publisher stays connected, so you can render "live for 4m" from it, and a NEW value means the publisher dropped and came back.

A sensible poll is every 2 seconds while waiting to go live, then stop. Liveness normally appears within a couple of seconds of the encoder's handshake, and it clears within about 15 seconds of the publisher going away.

A `sourceId` from a studio you cannot see answers 404 `studio not found`, identical to a studio that does not exist.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `sourceId` | path | yes | Source id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The source. | `Source` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}/sources/{sourceId}`

Update a source.

Requires scope sources:write. Gated behind PUBLIC_API_WRITE_ENABLED.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `sourceId` | path | yes | Source id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The updated source. | `Source` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/sources/{sourceId}/ingest`

Get the publish endpoints for a source.

Requires scope `sources:ingest`. Gated behind PUBLIC_API_WRITE_ENABLED.

Returns the URLs an encoder — the TRaX phone app, OBS, a hardware unit — dials to put video INTO a source that already exists. Nothing is provisioned here. The input is the durable object and you point a device at it, so calling this twice hands two devices the same endpoint rather than creating a second input. Create the input first with `POST /v1/studios/{id}/sources` (type `generic-input`), then call this whenever a device needs to know where to publish.

Treat the response like a password. Every `complete` URL is a live credential to broadcast on this studio's input: keychain, not log file, not analytics event, not a crash report. That is also why this is a POST — a GET URL ends up in browser history, proxy logs and `Referer` headers, and this response has no business in any of them.

`protocols` is a REQUEST, not a guarantee. Read `granted` off the response and configure from that: it may be narrower than what you asked for and it may be empty. Today `srt`, `rtmp` and `rtmps` are grantable. `webrtc` is not — the WHIP URL for a plain input carries no publish token, so returning it would hand you an endpoint that fails at the handshake — and `rtsp` and `hls` have no publish form at all. Asking for one of those is not an error; it simply does not appear in `granted`. An unrecognised protocol NAME is a 400, because a silently dropped one leaves your client waiting for an endpoint that is never coming.

Rate limited separately from the rest of `/v1`, at roughly 5 per minute per caller with a small burst. A client fetches an input's endpoints once when the operator picks that input and again on reconnect; anything sustained above that is a script pulling publish credentials in a loop.

`GET /v1/studios/{id}/sources` deliberately carries none of this — list responses are what people log.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `sourceId` | path | yes | Source id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The publish endpoints actually granted. Nothing was created; these already existed. | `SourceIngest` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/sources/{sourceId}/ingest/rotate`

Rotate a source's publish credential.

Requires scope `sources:ingest`. Gated behind PUBLIC_API_WRITE_ENABLED.

Replaces the stream key behind this input and returns the NEW endpoints, in exactly the shape `POST .../ingest` returns — so a client that can configure an encoder from a mint result needs no second code path for a rotate result. This is the answer to "that stream key got out": pasted into a support chat, on a laptop that walked off, in the hands of a contributor who no longer works here.

DESTRUCTIVE, and there is no overlap window. The old URLs stop authenticating the moment this returns, because an overlap window is precisely the interval in which the leaked key is still useful. Every device still configured with the old URL will fail its next handshake until you re-point it, so rotate when you can re-provision — not in the sixty seconds before a show.

`kickPublishers` decides what happens to a session that is publishing RIGHT NOW. The media server authorises a publish once, at handshake, and never re-checks, so an in-flight publisher survives the rotation until its socket drops. Send `true` to cut it — that is what "revoke" usually means — or `false` (the default) to let a broadcast in progress finish on the old credential while every NEW connection requires the new one.

`protocols` scopes what comes BACK, not what is invalidated. Rotation always replaces the single underlying stream key, so asking only for `srt` still kills the old `rtmp` URL. Read `granted` off the response and configure from that, exactly as with the mint endpoint. An unrecognised protocol NAME is a 400 and the credential is NOT rotated — a typo must not cost you a working key.

Same rate-limit class as the mint endpoint, roughly 5 per minute per caller with a small burst.

The studio's own operators see this without asking: open studio tabs re-render the Connection Information panel with the new URLs.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `sourceId` | path | yes | Source id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The publish endpoints built from the NEW credential. The previous ones no longer authenticate. | `SourceIngest` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/stream-status`

Get a studio's live/offline stream status.

Requires scope stream:read.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The stream status. | `StreamStatus` |
| `default` | Error envelope. | `Error` |

### stream

Go-live / go-offline lifecycle

#### `POST /v1/studios/{id}/go-live`

Take a studio live.

Requires scope stream:golive. Gated behind PUBLIC_API_WRITE_ENABLED; returns 503 write_disabled while off.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The studio is going live. | `GoLiveResult` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/go-offline`

Take a studio offline.

Requires scope stream:golive. Gated behind PUBLIC_API_WRITE_ENABLED; returns 503 write_disabled while off.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The studio is going offline. | `GoOfflineResult` |
| `default` | Error envelope. | `Error` |

### chat

Unified live-chat messages

#### `GET /v1/studios/{id}/chat/messages`

List a studio's recent unified-chat messages.

Requires scope chat:read. Returns the most recent messages (bounded by limit); no cursor.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | Recent chat messages. | `ChatMessageList` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/chat/messages`

Send a message into the studio's unified chat.

Requires scope chat:send. Gated behind PUBLIC_API_WRITE_ENABLED. Fans out to the enabled platforms.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | The message was accepted for fan-out. | `ChatSendResult` |
| `default` | Error envelope. | `Error` |

### connections

Linked platform accounts

#### `GET /v1/connections`

List the caller's linked platform accounts.

Requires scope connections:read. Metadata only — never tokens or stream keys.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `cursor` | query | no | Opaque pagination cursor from a prior response's nextCursor. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A page of connections. | `ConnectionList` |
| `default` | Error envelope. | `Error` |

#### `DELETE /v1/connections/{connectionId}`

Unlink a connection.

Requires scope `connections:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Revokes the grant at the platform and THEN deletes the stored tokens. The revoke is best-effort: a provider that is down or slow does not block the delete, and two providers (LinkedIn, Trovo) expose no revoke endpoint at all, so for those the token remains valid at the provider until it expires naturally. The row and the tokens are gone from TRaX either way.

Destructive beyond the connection itself: destinations bound to it lose their credential source and will fail to resolve at the next go-live. Find them first with `connectionId` on `GET /v1/studios/{id}/destinations`.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `connectionId` | path | yes | Connection id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The connection was unlinked. | `Ok` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/connections/{connectionId}`

Read one linked account.

Requires scope `connections:read`. A connection that is missing and one that belongs to another user are both 404 — the two are deliberately indistinguishable.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `connectionId` | path | yes | Connection id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The connection. | `Connection` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/connections/{connectionId}`

Update a manual connection's label, URL or stream key.

Requires scope `connections:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Patches a MANUAL connection in place: only the fields sent are applied, and an absent or empty `streamKey` leaves the stored key untouched — so a label rename never has to re-enter the key. Rotating a key on the platform is a PATCH with the new `streamKey`; existing destinations bound to this connection pick it up at the next go-live.

Only valid on `connectionType: "manual"` rows — an OAuth connection answers 400 `invalid_request` (its credentials are managed by the platform link, not by hand). A connection that is missing and one that belongs to another user are both 404, deliberately indistinguishable.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `connectionId` | path | yes | Connection id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The updated connection. No key material. | `Connection` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/connections/link`

Start linking a platform account.

Requires scope `connections:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Returns a URL to HAND TO A BROWSER. This is the whole of what an API can do here: the authorization itself is a human consenting on the platform's own consent screen, which no server-to-server call can stand in for. Do not follow `authorizationUrl` from your backend.

There is no completion callback and no push when it lands. After the user consents they are returned to a TRaX page; POLL `GET /v1/connections` and watch for the new row to appear, or for an existing row's `status` to flip back to `active`. `state` is returned so a caller with several attempts in flight can tell which one completed.

`returnTo` must be a TRaX-owned https host — anything else is rejected rather than followed, because this value is a redirect target reached with the user's session. A third-party application cannot receive this redirect.

TO REPAIR A BROKEN CONNECTION, set `reconnectConnectionId` to the existing connection's id. That refreshes the grant IN PLACE and KEEPS THE ID. Without it you get a second connection row, and every destination bound to the old one is orphaned — it will still be listed and will still fail at go-live.

**Auth:** API key required.

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A URL to open in a browser. | `LinkStart` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/connections/manual`

Save a stream key as a manual connection.

Requires scope `connections:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Stores a pasted RTMP URL + stream key as a MANUAL connection — the path for platforms with no OAuth link (Facebook and Instagram today, plus rumble/twitter/tiktok/custom). The returned connection's `id` is what `CreateDestination.connectionId` takes, so the flow is: save the key here once, then create destinations against it from any studio.

The stream key is WRITE-ONLY: it is stored encrypted and never returned by any read on this API — the response carries no key material. Note that chat is NOT available on stream-key connections: with no API grant there is nothing to read the platform's chat with.

Not idempotent — a retry saves a second connection.

**Auth:** API key required.

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | The saved manual connection. No key material. | `Connection` |
| `default` | Error envelope. | `Error` |

### media

Media library assets + uploads

#### `GET /v1/media`

List the caller's media-library assets.

Requires scope `media:read`.

The library belongs to the USER, not to a studio, so nothing here names one. Rows are cursor-paginated and carry a thumbnail; the file itself is read one asset at a time through `GET /v1/media/{assetId}`, because handing out object access on a list response is a different grant from saying what exists — and list responses are what end up in logs.

`quotaUsedBytes` / `quotaLimitBytes` ride along so you can render usage and refuse an over-large pick client-side, instead of finding the ceiling when an upload comes back 402.

Only READY assets appear. An upload in flight is not listed — poll it by id.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `cursor` | query | no | Opaque pagination cursor from a prior response's nextCursor. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A page of media assets, plus the storage allowance. | `MediaAssetList` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/media`

Start an upload — returns a presigned PUT or a multipart plan.

Requires scope `media:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Step 1 of THREE. This reserves the asset row and hands back the plan for pushing the bytes; you upload them yourself, straight to storage; then `POST /v1/media/{assetId}/complete` makes the upload real. An upload that stops after step 2 has produced nothing anybody can use — the row sits in UPLOADING, holding quota, attachable to nothing.

BRANCH ON `mode`.

* `single` — PUT the whole file to `uploadUrl`, then call `/complete` with no body.
* `multipart` — no `uploadUrl` at all. PUT each entry of `parts` at its own `offset`/`byteSize` to its own `url`, keep the `ETag` response header each PUT returns, then call `/complete` with the full list. Parts may go up in any order; three in flight is a good number, and each is worth a couple of retries. Cut the file by the plan, never by a part size of your own — the server may have grown it to stay under the storage layer's part-count ceiling.

The reason large files come back as a plan: every request to our storage host crosses a CDN edge that caps ONE request body at 100 MB, and it enforces that at the edge — a 150 MB single PUT dies at 413 after about 2 MB. Parts are sized to stay under that cap, so the ceiling on a file is the account's quota, not the edge. The single/multipart split point is server policy and it moves; that is why you branch on `mode` rather than on a size of your own.

Not idempotent: calling this twice creates two assets and reserves quota twice. There is no dedupe on filename or content.

`byteSize` is checked against the remaining quota BEFORE any URL is issued, so an upload that cannot fit is refused here (402 `storage_quota_exceeded`) rather than after the bytes are sent. `contentType` decides the asset's `kind` and must be one we accept — `video/mp4`, `video/webm`, `video/quicktime`, `image/jpeg`, `image/png`, `image/webp`, `image/gif`, `audio/mpeg`, `audio/wav`, `audio/ogg`, `audio/aac`.

**Auth:** API key required.

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | An upload was reserved. Read `mode` before anything else. | `MediaUpload` |
| `default` | Error envelope. | `Error` |

#### `DELETE /v1/media/{assetId}`

Delete an asset and release its storage.

Requires scope `media:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

DESTRUCTIVE and not undoable: the stored file and its thumbnail go with the row, and the quota comes back.

It is REFUSED with 409 `conflict` while any studio source still uses the asset, and the message says how many. That is not politeness — a source pointing at a deleted file renders a permanent "unavailable" card, and if that studio is live the encoder's next read on the file fails and the input drops to a placeholder mid-show. Delete the sources first, then the asset.

For an upload still in flight use `/abort` instead; this endpoint is about finished library content.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `assetId` | path | yes | Media asset id, as returned by `POST /v1/media` or `GET /v1/media`. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The asset is gone and its storage is released. | `Ok` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/media/{assetId}`

Read one asset, with its playback URLs.

Requires scope `media:read`.

This is the read you POLL after completing an upload, and the only place on `/v1` that hands out access to the stored file. Watch `status`: an asset is usable when it reads READY. A large upload is assembled and probed server-side, so READY can lag `/complete` by a moment — poll every second or two, and stop.

`thumbnailUrl` and `downloadUrl` are presigned for the PUBLIC storage host, so they resolve from a phone. Both are absent unless the asset is READY, and `thumbnailUrl` is best-effort even then — an image or an audio file may simply not have one, which is a kind icon on your side, not an error.

Every URL here EXPIRES. Treat them as render-time values: fetch, use, discard. Storing one in your database produces a link that works in testing and 403s a day later.

An assetId belonging to anyone else answers 404 `not_found`, identical to one that does not exist.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `assetId` | path | yes | Media asset id, as returned by `POST /v1/media` or `GET /v1/media`. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The asset. | `MediaAssetDetail` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/media/{assetId}/abort`

Cancel an upload in flight and give the quota back.

Requires scope `media:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Call it when a user cancels, or when an upload has failed past retrying. Every part already written is discarded and the reserved row is deleted.

The quota is the reason this matters. An abandoned upload does not appear in `GET /v1/media` — that lists finished assets — and it still occupies the ceiling, so a client that abandons uploads without aborting them slowly locks its own user out of uploading anything. There is a server-side sweeper, but it runs on the order of hours.

IDEMPOTENT, and NOT a delete: an upload that is already gone is a success, while a FINISHED asset is refused with 409 `conflict`. Removing finished content is `DELETE /v1/media/{assetId}`; a mistimed cancel must not become data loss.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `assetId` | path | yes | Media asset id, as returned by `POST /v1/media` or `GET /v1/media`. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The upload is discarded and its quota released. | `Ok` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/media/{assetId}/complete`

Finish an upload — the step that makes it real.

Requires scope `media:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Step 3 of three, and the one that is easy to skip. Until it runs the asset stays UPLOADING, counts against quota, and can be attached to nothing; on the multipart path it is also the ASSEMBLY call — the parts are held separately and no whole object exists until this reassembles them.

Single-file upload: send no body.

Multipart upload: send every part with the `ETag` its PUT returned. Order does not matter; completeness does. If you could not read the ETags — a browser cannot unless the storage host exposes the header through CORS — send the parts with empty etags, or send no body at all, and the server recovers them from storage itself. That fallback is why a missing ETag is not fatal.

IDEMPOTENT. An already-completed asset comes back unchanged, so a client that lost the response to a dropped connection should simply call again rather than re-uploading.

The response is the asset. `status` may read READY immediately or lag by a moment while the file is probed and a thumbnail is made — poll `GET /v1/media/{assetId}` rather than assuming.

The bytes in storage are the authority, not what you declared: an upload larger than the `byteSize` you reserved is rejected and deleted here rather than quietly eating the quota.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `assetId` | path | yes | Media asset id, as returned by `POST /v1/media` or `GET /v1/media`. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The finished asset. | `MediaAssetDetail` |
| `default` | Error envelope. | `Error` |

### canvas

The studio canvas: tile placement, presets, scenes

#### `GET /v1/studios/{id}/canvas`

Read the studio's whole canvas.

Requires scope `canvas:read`.

The whole canvas in ONE call: layout mode, active preset and scene, the coordinate space the rectangles live in, the program output format, and one placement row per source. Everything a phone needs to draw a miniature of what is on air, without a second request.

One call rather than a layout read plus a source list, on purpose. A tile is a source AND a rectangle; fetching those separately gives you two answers taken at two moments, and the picture drawn from them can show a tile that no longer exists or omit one that just appeared.

GEOMETRY IS THE SAME IN BOTH MODES. The server persists the auto planner's resolved rectangles into the same store advanced mode writes, so what you read here is what the encoder is compositing whichever mode the studio is in. You do not have to re-implement the planner to draw the picture.

`canvasWidth` x `canvasHeight` is the COORDINATE SPACE — a fixed 1920x1080 for every studio — and is NOT the broadcast resolution. `output` is. They differ constantly (a 720p60 program still composites on a 1920x1080 canvas), so scale your miniature by the canvas and label the stream by `output`.

CONDITIONAL. The response carries an ETag; send it back as `If-None-Match` and an unchanged canvas answers 304 with no body. The tag is computed over the whole snapshot, not just the layout revision, so a source renamed or deleted invalidates it too — a 304 always means your picture is still correct.

Hold `layoutRev` and send it back as `baseRev` on your next write.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `If-None-Match` | header | no | An ETag from a previous read. An unchanged canvas answers 304 with no body. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The studio's canvas. | `CanvasState` |
| `304` | The canvas has not changed since the ETag you sent. No body. | — |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}/canvas`

Set the layout mode or the canvas-wide settings.

Requires scope `canvas:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

A PATCH: send only what you are changing. Returns the WHOLE canvas, so the answer to your change is the new picture rather than an acknowledgement.

`layoutMode` is the field that matters. **auto** hands geometry to the server's planner: you express intent (which preset, which source is focused) and the studio computes every rectangle, overriding whatever you last wrote. **advanced** hands geometry to you: each tile stays exactly where it was last put and the planner keeps its hands off. Sending a rectangle while the studio is in auto is not an error and not a no-op either — it lands, and the next re-plan overwrites it. Flip to advanced first if you mean it to stick.

Flipping auto -> advanced is SEAMLESS by construction: the studio seeds the freeform geometry from what auto is displaying at that instant, in the same write as the mode flip, so nothing on the program moves. Flipping back re-plans and DOES move things — that is the point of going back to auto.

Send `baseRev` (the `layoutRev` you read) to make a stale write a 409 instead of a clobber. Omit it for last-write-wins.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The canvas after the change. | `CanvasState` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/canvas/capabilities`

Discover the preset catalog and the canvas vocabularies.

Requires scope `canvas:read`.

What this studio's canvas supports: the encoder-declared preset catalog — each preset's id, display name, slot count, normalized slot geometry, and an SVG schematic you can render as a picker thumbnail — plus the layout modes, fit modes and scene transitions a picker needs to enumerate, and the canvas coordinate space.

DISCOVER, DO NOT HARDCODE. The catalog is the encoder's, not this API's; ids come and go with encoder releases and a client with a baked-in list quietly loses the ones it never heard of. Cache on `libraryVersion` and refetch when it changes.

`slots` are normalized 0.0-1.0 fractions, not canvas units — they describe the SHAPE of an arrangement independent of resolution, which is what makes them drawable as a thumbnail. The rectangles a preset actually produces for the current source set come back from the canvas read.

DEGRADES RATHER THAN FAILS: an unreachable encoder yields an empty `presets` with an empty `libraryVersion`, never an error. That is a state to render — fall back to what you cached, or hide the picker — and it is the honest answer, because we do not know what that encoder offers right now. The vocabularies are never degraded; they are the gateway's own.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | What the canvas supports. Possibly a degraded preset half — see the description. | `CanvasCapabilities` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}/canvas/placements/{sourceId}`

Move, resize, re-stack, crop, hide or show one tile.

Requires scope `canvas:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

EVERY FIELD IS OPTIONAL AND OMITTED MEANS PRESERVE. That is what makes `{"zIndex": 3}` a legal call: bring a tile forward without knowing its rectangle; hide one without knowing its crop. A source with NO stored placement is the one exception — there is nothing to preserve, so a first placement must carry a `rect`, and the 400 says so.

THIS FLIPS THE STUDIO TO ADVANCED MODE. Per-source geometry IS the mode: the server writes the mode alongside the rectangle, atomically, because a rectangle sitting under auto mode is geometry the next re-plan is about to erase. If you wanted to nudge one tile inside an auto arrangement, you wanted the preset endpoint instead — or this, then a replan to put auto back.

Rectangles are in CANVAS units (the 1920x1080 space the canvas read reports), not output pixels and not fractions. A tile may hang off an edge but must intersect the canvas; width and height must be positive and no larger than the canvas. Values outside their ranges are 400s rather than silent clamps, for the same reason a mixer refuses a fader position in decibels: a client that guessed the units should find out.

SAFE TO RETRY. A stale `baseRev` is normally 409 — but a request that describes the tile EXACTLY AS IT ALREADY IS comes back 200, because the write it asks for is in effect and there is nothing left to do. That exception exists for the case this endpoint was built for: a phone sends a move, the write lands, the response never arrives, and the phone retries with the `baseRev` it started from. Without it that retry gets a conflict for a change it successfully made, and a client that trusts conflicts would undo the user's own edit.

NOT A DRAG PATH. Every call here persists, re-asserts to the encoder and fans out to every open studio tab. For real-time motion the studio WebSocket carries an ephemeral high-frequency transform frame that does none of those things; REST has no equivalent. Move the tile locally, then commit the final rectangle here — once.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `sourceId` | path | yes | Source id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The canvas after the move — or unchanged, when a retried write was already in effect. | `CanvasState` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/canvas/preset`

Pick the auto-mode arrangement.

Requires scope `canvas:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

The auto-mode counterpart to a placement patch: there you name pixels, here you name INTENT and the planner produces the pixels. For a phone this is almost always the better call — "put Dana big and everyone else in a strip" survives a guest joining, where six hand-placed rectangles do not.

The server persists the intent, re-resolves every rectangle from it, seats any source the new preset made room for, and pushes the result at a live encoder. Returns the whole canvas.

`presetId` must come from the capabilities endpoint. Do not hardcode the catalog. `tileOrder`, `traySourceIds` and `slotAssignments` are WHOLE-SET replacements when present and untouched when absent — send the complete list, because a partial one would silently drop the members it omitted.

LAST-WRITE-WINS, not revision-gated, deliberately: picking a preset is a discrete human action taken a few times a show, not the high-frequency optimistic path a revision clock exists to protect. Two people picking two presets a second apart should end on the second one, not on a conflict.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The canvas after the arrangement changed. | `CanvasState` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/canvas/replan`

Hand the arrangement back to the auto planner.

Requires scope `canvas:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Re-runs the planner over the studio's CURRENT sources and preset, persists the rectangles it resolves, seats anything the plan now places, pushes the result at a live encoder, and returns the whole canvas. It changes no intent — same preset, same focus, same tray — it just recomputes.

This is the "put it back the way the studio would arrange it" button, and the way OUT of advanced mode: send `layoutMode: "auto"` and the row flips and re-plans in one call, so hand-placed rectangles are replaced by the planner's.

Sent without a mode against an ADVANCED studio it is a no-op, and reports that honestly by returning the unchanged canvas rather than an error: the planner does not own geometry in advanced mode, and quietly re-planning a studio whose operator took manual control would move tiles on air that nobody asked to move.

You should rarely need it. Membership changes — a guest joins, a camera goes live, a preset is picked — already re-plan on their own.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The canvas after the re-plan — or unchanged, when the studio is in advanced mode and no mode flip was asked for. | `CanvasState` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/scenes`

List the studio's saved scenes.

Requires scope `canvas:read`.

The looks an operator captured and can recall. A scene is a SNAPSHOT OF THE CANVAS, not a channel: it holds the source rectangles, the layout mode and the active-source set as they were at capture time.

`hasComposition` false means the scene is a label with no saved canvas behind it — recalling it will change nothing. Grey the row rather than offering a recall that silently does nothing.

Not paginated: a studio's scene list is a handful of rows an operator made by hand.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The studio's scenes. | `SceneList` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/scenes/active`

Recall a saved scene onto the program.

Requires scope `canvas:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Restores the scene's captured composition through the same geometry authority every other canvas write goes through, re-pushes each source's audio so levels do not snap back to encoder defaults, and tells every open studio tab. Returns the resulting canvas.

ON A LIVE STUDIO THIS CHANGES WHAT VIEWERS SEE, IMMEDIATELY. There is no preview bus here to rehearse it on: scene rows carry an is-preview flag, but no second canvas is composited from it, so exposing a "preview" would name a rehearsal that does not happen. Program is the only destination a scene has.

A metadata-only scene — `hasComposition` false — recalls cleanly and changes no geometry. The returned canvas will look identical to the one you read before the call. That is success, not a silent failure.

A `sceneId` from a studio you cannot see answers 404, identical to a scene that does not exist.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The canvas after the scene was recalled. | `CanvasState` |
| `default` | Error envelope. | `Error` |

### destinations

#### `GET /v1/studios/{id}/broadcast-templates`

List a studio's broadcast templates.

Requires scope `destinations:read`.

Returns the studio's saved broadcast templates, the pinned default first then newest-updated. A template is a named snapshot of the create-mode broadcast settings that prefills the create form; it creates nothing on YouTube. Each row carries its full `config` object.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `cursor` | query | no | Opaque pagination cursor from a prior response's nextCursor. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A page of broadcast templates. | `BroadcastTemplateList` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/broadcast-templates`

Save a broadcast template.

Requires scope `destinations:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Saves a new named template from a `name` and a `config` JSON object. `isDefault: true` pins it as the studio's default in the same transaction (at most one default per studio). `config` is stored verbatim and never interpreted server-side.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | The created template. | `BroadcastTemplate` |
| `default` | Error envelope. | `Error` |

#### `DELETE /v1/studios/{id}/broadcast-templates/{templateId}`

Delete a broadcast template.

Requires scope `destinations:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Deletes one template, studio-scoped by id. Deleting the pinned default just leaves the studio with no default. A `templateId` that is not this studio's answers 404.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `templateId` | path | yes | The broadcast template id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The template was deleted. | `Ok` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}/broadcast-templates/{templateId}`

Overwrite a broadcast template.

Requires scope `destinations:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Overwrites the template's `name` and `config` in place, leaving its default pin untouched. A `templateId` that is not this studio's answers 404.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `templateId` | path | yes | The broadcast template id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The updated template. | `BroadcastTemplate` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/broadcast-templates/{templateId}/default`

Pin a broadcast template as the default.

Requires scope `destinations:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Pins one template as the studio's default and clears any other default, atomically. Returns the now-default row. A `templateId` that is not this studio's answers 404.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `templateId` | path | yes | The broadcast template id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The now-default template. | `BroadcastTemplate` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/destinations/{destId}`

Read one destination.

Requires scope `destinations:read`.

Same shape the list returns. Read `lastError` whenever `status` is ERROR or STALLED, and `connectionId` to find which linked account a failing leg depends on.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `destId` | path | yes | Destination id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The destination. | `Destination` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/studios/{id}/destinations/{destId}/broadcast`

Edit a destination's picked YouTube broadcast.

Requires scope `destinations:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Edits the mutable fields of the YouTube broadcast this destination has PICKED and pushes them to the platform, exactly as the studio's Broadcast Manager does. `broadcastId` is required and names the broadcast to edit, so the change never lands on the wrong stream. `title` and `description` are applied to the same picked broadcast; the status/contentDetails fields go through YouTube's liveBroadcasts.update.

YouTube FREEZES contentDetails (dvr, embed, recordFromStart, latency, delay, projection, monitorStream) once a broadcast enters testing/live. Any such field the platform refused comes back in `rejectedFields` — the call still succeeds, so read it to learn which edits did not apply. YouTube-only: other platforms answer 400 `invalid_request` "operation not supported on this platform".

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `destId` | path | yes | Destination id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The edit outcome, including any fields the platform locked. | `BroadcastEditResult` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/destinations/{destId}/broadcast`

Create a broadcast on the platform now and adopt it as the pick.

Requires scope `destinations:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Creates a broadcast on the destination's platform IMMEDIATELY (YouTube liveBroadcasts.insert — an absent `scheduledStartTime` stamps a near-immediate start; Facebook's legacy scheduled path wants a future time), seeded from the destination's SAVED broadcastConfig — the same template-aware seeding go-live's create mode uses, so privacy/latency/DVR/contentDetails match what going live would have minted. `title`/`description` here override the config's copies.

The created broadcast is then ADOPTED as the destination's pick (mode → "pick"), so the next go-live binds the stream to it. Returns the created broadcast; its `id` is what the edit and pick endpoints take. Platforms with no broadcast create answer 400 `invalid_request`.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `destId` | path | yes | Destination id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | The broadcast now created on the platform (and adopted as the pick). | `Broadcast` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/destinations/{destId}/broadcast/pick`

Point the destination at an existing broadcast, or clear the pick.

Requires scope `destinations:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Points the destination at ONE existing platform broadcast so go-live binds the stream to it — the same choice the studio's "Use existing" tab makes. `broadcastId` comes from `GET .../broadcasts`. Sending `broadcastId: null` (or empty) CLEARS the pick: the destination returns to create mode and go-live auto-creates a fresh broadcast from its saved config.

This is a POINTER write: the platform is not called to validate the id here, and sibling destination settings are never touched (the write is a targeted merge). A dead or foreign broadcast id surfaces at go-live.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `destId` | path | yes | Destination id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The destination's resulting broadcast targeting. | `BroadcastPickResult` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/studios/{id}/destinations/{destId}/broadcast/thumbnail`

Upload a custom broadcast thumbnail.

Requires scope `destinations:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

Uploads a custom thumbnail image for a YouTube broadcast on a connection-backed destination and returns the URL YouTube now serves. The image is the RAW request body and its `Content-Type` header is the image MIME type (`image/jpeg` or `image/png`); the broadcast is named by the `broadcastId` query parameter. YouTube caps thumbnails at 2 MB. An unverified channel answers 400 `invalid_request`.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `destId` | path | yes | Destination id. |
| `broadcastId` | query | yes | The YouTube broadcast/video id to set the thumbnail on. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The thumbnail URL YouTube now serves. | `ThumbnailResult` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/studios/{id}/destinations/{destId}/broadcasts`

List the platform broadcasts a destination can pick from.

Requires scope `destinations:read`.

Returns the platform-side broadcasts on the destination's linked connection (YouTube liveBroadcasts / Facebook live_videos) — recent, upcoming and active — exactly what the studio's own "pick an existing broadcast" panel shows. Each row's `id` is what `POST .../broadcast/pick` and `PATCH .../broadcast` take. On YouTube the rows carry the broadcast's LIVE settings (privacy, latency, DVR, ...) so an editor can seed from actual values.

Channel-scoped platforms (Twitch, Kick, Trovo) and pasted-key destinations have no broadcast concept and answer an EMPTY list, not an error.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Studio id. |
| `destId` | path | yes | Destination id. |
| `cursor` | query | no | Opaque pagination cursor from a prior response's nextCursor. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A page of platform-side broadcasts. | `BroadcastList` |
| `default` | Error envelope. | `Error` |

### embed

#### `POST /v1/viewer-tokens`

Mint a browser-safe credential for one of your own members.

Requires scope viewer:tokens. Gated behind PUBLIC_API_WRITE_ENABLED.

Call this from YOUR SERVER, never from a browser — it is authenticated with your secret API key. You have already authenticated your own member and decided what they may do; this exchanges that decision for a short-lived token you hand to that member's page, where it is safe.

`memberRef` is YOUR identifier for the person and stays opaque to TRaX: it is never resolved to anyone, and exists only so the token can be rate-limited and revoked. It is REQUIRED whenever `caps` contains a write capability, because a relayed chat message reaches the broadcaster's connected platform accounts and must be attributable to someone you vouched for and can stop vouching for.

`ttlSeconds` is clamped server-side (default 900, maximum 3600) and the response carries the real expiry. Revocation of a cancelled membership IS token expiry, so re-mint on a schedule rather than asking for a longer life.

The response echoes the capabilities actually GRANTED, which may be narrower than requested. Render your interface from those — a composer drawn from a capability you merely hoped for is a control that fails on submit.

**Auth:** API key required.

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | A viewer token was minted. | `ViewerToken` |
| `default` | Error envelope. | `Error` |

### storage

#### `GET /v1/storage-configs`

List your connected object-storage buckets.

Requires scope `storage:read`, which is NOT in the default key scope set — a key must ask for it by name.

Owner-scoped, like connections: a bucket belongs to a person and is usable from any of their studios, so nothing here names one. Credentials are never returned.

503 `storage_disabled` when object storage is not configured on this deployment. That is deliberately not an empty list: "you have no buckets" and "we cannot answer" are different claims.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `cursor` | query | no | Opaque pagination cursor from a prior response's nextCursor. |
| `limit` | query | no | Max items per page (default 50, max 200). |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | A page of storage configs. | `StorageConfigList` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/storage-configs`

Connect a bucket.

Requires scope `storage:write`. Gated behind PUBLIC_API_WRITE_ENABLED, and requires an active subscription.

Stores the config and probes the bucket inline. A FAILING PROBE STILL CREATES THE ROW and still answers 201 — read `status`, not the HTTP code. That is deliberate: a typo'd endpoint should leave you something editable rather than nothing.

Credentials are encrypted before they touch storage and cannot be read back through any surface.

**Auth:** API key required.

**Responses:**

| Status | Description | Body |
|---|---|---|
| `201` | Created. Check `status` for whether the bucket actually answered. | `StorageConfig` |
| `default` | Error envelope. | `Error` |

#### `DELETE /v1/storage-configs/{configId}`

Disconnect a bucket.

Requires scope `storage:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

SOFT delete: TRaX stops using the bucket and it disappears from every list, but NOTHING IN YOUR BUCKET IS TOUCHED and the stored credentials are retained encrypted rather than scrubbed.

GUARDED: 409 `conflict` when imported media assets still resolve through this config, naming how many would be stranded. Pass `?force=true` to delete anyway — those assets degrade to unresolvable rather than disappearing.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `configId` | path | yes | Storage config id. |
| `force` | query | no | Delete even though imported media still references this config. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The config was disconnected. | `Ok` |
| `default` | Error envelope. | `Error` |

#### `GET /v1/storage-configs/{configId}`

Read one storage config.

Requires scope `storage:read`. A config that is missing and one belonging to another user are both 404.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `configId` | path | yes | Storage config id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The storage config. | `StorageConfig` |
| `default` | Error envelope. | `Error` |

#### `PATCH /v1/storage-configs/{configId}`

Edit a storage config.

Requires scope `storage:write`. Gated behind PUBLIC_API_WRITE_ENABLED, and requires an active subscription.

Partial: an omitted field is left alone. Credentials are BOTH-OR-NEITHER — send `accessKeyId` and `secretAccessKey` together to rotate, or send neither. Re-probes after writing, with the same rule as create: the row survives a failed probe and the verdict lands in `status`.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `configId` | path | yes | Storage config id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The updated storage config. | `StorageConfig` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/storage-configs/{configId}/verify`

Re-probe a stored bucket.

Requires scope `storage:write`. Gated behind PUBLIC_API_WRITE_ENABLED, and requires an active subscription.

Re-runs the probe and writes the fresh verdict onto the row. The way to clear a stale `forbidden` after fixing a bucket policy, without re-entering credentials nobody can read back.

As with create, a failed probe is reported in `status`, not as an error.

**Auth:** API key required.

**Parameters:**

| Name | In | Required | Description |
|---|---|---|---|
| `configId` | path | yes | Storage config id. |

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The config with its refreshed status. | `StorageConfig` |
| `default` | Error envelope. | `Error` |

#### `POST /v1/storage-configs/probe`

Test credentials without storing them.

Requires scope `storage:write`. Gated behind PUBLIC_API_WRITE_ENABLED.

The dry run behind a "test connection" button: no row is created, nothing is encrypted, nothing is persisted, and the credentials are discarded when the call returns. Use it before create so a bad bucket is caught BEFORE a row exists.

A bucket that refuses the credentials is a 200 with a non-ok `status`, not a 4xx — the probe SUCCEEDED, it found out the answer. Only malformed input is a client error.

**Auth:** API key required.

**Responses:**

| Status | Description | Body |
|---|---|---|
| `200` | The probe verdict. Read `status`. | `StorageProbeResult` |
| `default` | Error envelope. | `Error` |

## Schemas

### `AudioMaster`

| Field | Type | Required | Description |
|---|---|---|---|
| `muted` | `boolean` | yes | The master GATE. True silences the program for every viewer on every destination. INDEPENDENT of volume — the fader keeps its position underneath, so unmuting returns to exactly the level it was at. |
| `volume` | `number` | yes | The master fader, LINEAR: 0.0 silent, 1.0 unity (0 dB), above 1.0 amplifies. Not decibels. |

### `AudioSourceStrip`

| Field | Type | Required | Description |
|---|---|---|---|
| `active` | `boolean` | yes | Whether the operator has put this source on the canvas. INTENT, and a different question from `muted`: an inactive source still has a strip. Deactivating a source auto-mutes it and reactivating restores the prior mute, so `active` is what explains a strip that reads muted because it was switched off. |
| `muteGroups` | `integer[]` | yes | Mute-group ids (1..4) this channel belongs to. READ-ONLY on this API: the group MASTER button that gives membership its meaning lives in the studio's mixer panel. Always an array — an empty membership is [], never null. |
| `muted` | `boolean` | yes | This channel's GATE, independent of `volume` — the fader keeps its position underneath. |
| `name` | `string` | yes | Display name, echoing the source's. Present so a fader can be labelled without a second call. |
| `pan` | `number` | yes | Stereo position: -1.0 full left, 0.0 centre, +1.0 full right. |
| `soloed` | `boolean` | yes | The operator's solo latch, synced across every operator in the studio. A mixing-desk intent flag — it does NOT by itself mute the other channels, so do not read it as "everything else is off". |
| `sourceId` | `string` | yes | The source this strip belongs to — the same id the sources endpoints use. |
| `trim` | `number` | yes | Pre-fader input gain, where a hot or quiet input is brought to a nominal level before the fader. LINEAR, 1.0 nominal (-20 dB … +24 dB). |
| `type` | `string` | yes | Source kind, echoing the source's. Every source row carries a strip, including ones with no audio track; read this to decide what to draw. |
| `volume` | `number` | yes | Channel fader, LINEAR: 0.0 silent, 1.0 unity (0 dB). Not decibels. |

### `Broadcast`

| Field | Type | Required | Description |
|---|---|---|---|
| `description` | `string` | no | — |
| `enableAutoStart` | `boolean` | no | — |
| `enableAutoStop` | `boolean` | no | — |
| `enableDvr` | `boolean` | no | — |
| `enableEmbed` | `boolean` | no | — |
| `enableMonitorStream` | `boolean` | no | — |
| `id` | `string` | yes | The platform's broadcast id. On YouTube this is also the video id — the value the pick and edit endpoints take. |
| `latency` | `string` | no | normal \| low \| ultraLow (YouTube). |
| `madeForKids` | `boolean` | no | An absent boolean here and below means "false or not reported", never a guarantee. |
| `privacy` | `string` | no | public \| unlisted \| private (YouTube). Live current-state so an editor can seed from actual values; absent on platforms that don't report it. |
| `projection` | `string` | no | rectangular \| 360 (YouTube). |
| `recordFromStart` | `boolean` | no | — |
| `scheduledStartTime` | `string` | no | The platform-side planned start, RFC 3339. Absent when none is set. |
| `status` | `string` | yes | Lifecycle status as the platform reports it: created \| ready \| testing \| live \| complete \| ... (Facebook uses its own vocabulary). Only broadcasts not yet complete/revoked are worth picking. |
| `thumbnailUrl` | `string` | no | — |
| `title` | `string` | yes | — |

### `BroadcastConfig`

| Field | Type | Required | Description |
|---|---|---|---|
| `autoStart` | `boolean` | no | enableAutoStart — the broadcast goes live automatically once ingest begins. |
| `autoStop` | `boolean` | no | enableAutoStop — the broadcast stops automatically when ingest ends. |
| `description` | `string` | no | — |
| `dvr` | `boolean` | no | enableDvr — viewers can rewind the live stream. |
| `enableEmbed` | `boolean` | no | contentDetails.enableEmbed. Tri-state: omit to leave unset. |
| `enableMonitorStream` | `boolean` | no | contentDetails.monitorStream.enableMonitorStream. Tri-state: omit to preserve the legacy auto-start derivation; set true under autoStart to park the broadcast in testing. |
| `latency` | `string (enum)` | no | ultraLow disables closed captions and caps resolution at 1080p. (one of: `normal`, `low`, `ultraLow`) |
| `madeForKids` | `boolean` | no | status.selfDeclaredMadeForKids (COPPA). |
| `mode` | `string (enum)` | no | create = auto-create a fresh broadcast at go-live from this template; pick = the operator chose a specific existing broadcast. (one of: `create`, `pick`) |
| `privacy` | `string (enum)` | no | Privacy of the auto-created broadcast. (one of: `public`, `unlisted`, `private`) |
| `projection` | `string (enum)` | no | contentDetails.projection. Empty omits the field. (one of: `rectangular`, `360`) |
| `recordFromStart` | `boolean` | no | contentDetails.recordFromStart. Tri-state: omit to leave unset. |
| `streamDelayMs` | `integer` | no | contentDetails.broadcastStreamDelayMs. 0 = no delay. |
| `title` | `string` | no | Title stamped on the auto-created broadcast. |

### `BroadcastEditResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `lifecycleStatus` | `string` | no | The broadcast's lifecycle status after the edit (created \| ready \| testing \| live \| complete \| …), as YouTube reported it. Absent if the platform did not return one. |
| `rejectedFields` | `string[]` | yes | The fields YouTube refused because the broadcast is already testing/live (contentDetails freezes then). Empty when everything applied. |

### `BroadcastList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `Broadcast[]` | yes | — |
| `nextCursor` | `string` | no | — |

### `BroadcastPickResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `broadcastId` | `string` | no | The picked broadcast id; absent after a clear. |
| `mode` | `string` | yes | "pick" when a broadcast is now picked; "create" after a clear. |
| `title` | `string` | no | The stored pick title; absent after a clear. |

### `BroadcastTemplate`

| Field | Type | Required | Description |
|---|---|---|---|
| `config` | `object` | yes | The BroadcastConfig snapshot, stored verbatim. The client owns the shape. |
| `createdAt` | `string` | no | — |
| `id` | `string` | yes | — |
| `isDefault` | `boolean` | yes | Whether this is the studio's pinned default (at most one per studio). |
| `name` | `string` | yes | — |
| `studioId` | `string` | yes | — |
| `updatedAt` | `string` | no | — |

### `BroadcastTemplateList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `BroadcastTemplate[]` | yes | — |
| `nextCursor` | `string` | no | — |

### `CanvasBackground`

| Field | Type | Required | Description |
|---|---|---|---|
| `color` | `string` | yes | CSS colour string, e.g. "#000000". |

### `CanvasCapabilities`

| Field | Type | Required | Description |
|---|---|---|---|
| `canvasHeight` | `integer` | yes | Canvas coordinate-space height. |
| `canvasWidth` | `integer` | yes | Canvas coordinate-space width, repeated here so a client can size a picker thumbnail before it has read a canvas. |
| `fitModes` | `string[]` | yes | The fit modes a tile or the frame may take. |
| `layoutModes` | `string[]` | yes | The layout modes a write accepts. |
| `libraryVersion` | `string` | yes | Catalog version. Cache on it; refetch when it changes. Empty means the preset half is degraded. |
| `presets` | `CanvasPreset[]` | yes | The presets on offer, or empty when the encoder is unreachable. |
| `transitions` | `string[]` | yes | The scene transition names the studio UI offers. ADVISORY, not a closed enum: a scene stores its transition as free text, so a scene made elsewhere may report a name this list does not contain. Render it as the picker's options, not as a validator. |

### `CanvasCrop`

| Field | Type | Required | Description |
|---|---|---|---|
| `panX` | `number` | yes | Horizontal centre of the visible rect, 0.0 (left edge) to 1.0 (right edge) of the uncropped frame. 0.5 is centred. Meaningless at zoom 1.0. |
| `panY` | `number` | yes | Vertical centre of the visible rect, 0.0 (top) to 1.0 (bottom). |
| `zoom` | `number` | yes | Punch-in factor. 1.0 is the whole frame; above 1.0 is zoomed in. |

### `CanvasPlacement`

| Field | Type | Required | Description |
|---|---|---|---|
| `active` | `boolean` | yes | Whether the source itself is enabled. An inactive source is off the canvas whatever its rectangle says. |
| `alpha` | `number` | yes | Opacity. 1.0 is fully opaque. |
| `broughtIn` | `boolean` | no | True for an EXTRA leg the operator pulled out of its owner's folded person-unit so it gets its own cell. Only meaningful under the person-grid presets. |
| `crop` | `CanvasCrop` | no | — |
| `fitMode` | `string (enum)` | no | Per-source fit inside the rectangle. Absent means unset — the encoder default, which is contain. (one of: `contain`, `stretch`) |
| `inTray` | `boolean` | yes | True when this is an ACTIVE, canvas-eligible input that did not get a seat — an input waiting, not an input on the program. The exact complement of onCanvas over the sources that could hold one.  An INACTIVE source is NEITHER on canvas nor in the tray: it is an input that exists. Calling it 'in the tray' would say it is one action from air when it is two. |
| `name` | `string` | yes | Display name, so a tile can be labelled without a second call. |
| `onCanvas` | `boolean` | yes | True when the canvas is compositing this source RIGHT NOW. Resolved PER MODE, from the same state the encoder is driven from, so you never reimplement either rule.  AUTO: the source holds a seat in the server planner's CURRENT resolution of activePreset. A source the preset displaced is false here AND carries no rect, even though the layout row still holds the rectangle it had under the previous preset.  ADVANCED: the source has a stored, visible, non-degenerate rectangle. traySourceIds is NOT consulted — nothing maintains that list in advanced mode, so a tile you dragged onto the canvas reads true here while still appearing in it.  An INACTIVE source is always false: deactivating removes it from the encoder canvas whatever geometry survives. See membershipBasis for how this answer was reached. |
| `ownerSub` | `string` | no | The person a DEVICE source belongs to (browser camera, shared screen, phone leg); absent for every other kind. It is what lets a client fold one person's several legs into one tile the way the studio's own seating does. Absent on a shared input, whose sharer's identity is stripped upstream. |
| `rect` | `CanvasRect` | no | — |
| `sourceId` | `string` | yes | The source this tile is — the same id the sources endpoints use. |
| `type` | `string` | yes | Source kind (webcam, srt, rtmp, video-file, ...). Decides what to draw for a tile that has no picture yet. |
| `visible` | `boolean` | yes | Whether the tile is drawn. False hides it while keeping its rectangle, so showing it again does not make it jump. |
| `zIndex` | `integer` | yes | Stacking order. Higher draws in front; ties break on source id. |

### `CanvasPreset`

| Field | Type | Required | Description |
|---|---|---|---|
| `displayName` | `string` | yes | Human label, e.g. "Two up". |
| `id` | `string` | yes | The id to send as presetId. Show displayName, send this. |
| `overflowToTray` | `boolean` | yes | Whether sources beyond slotCount go to the tray rather than being dropped. |
| `schematicSvg` | `string` | no | An SVG schematic of the arrangement, ready to render as a picker thumbnail. May be empty. |
| `slotCount` | `integer` | yes | How many sources this preset seats. Actives beyond it go to the tray. |
| `slots` | `CanvasPresetSlot[]` | yes | The slot geometry, normalized. |

### `CanvasPresetSlot`

| Field | Type | Required | Description |
|---|---|---|---|
| `h` | `number` | yes | Height as a fraction of canvas height. |
| `index` | `integer` | yes | Slot index, 0-based. Slot 0 is the focus/hero seat where a preset has one. |
| `rect` | `CanvasSlotRect` | yes | — |
| `w` | `number` | yes | Width as a fraction of canvas width. |
| `x` | `number` | yes | Left edge as a fraction of canvas width. |
| `y` | `number` | yes | Top edge as a fraction of canvas height. |

### `CanvasRect`

| Field | Type | Required | Description |
|---|---|---|---|
| `height` | `integer` | yes | Height in canvas units. Must be positive and no larger than the canvas height. |
| `width` | `integer` | yes | Width in canvas units. Must be positive and no larger than the canvas width. |
| `x` | `integer` | yes | Left edge in canvas units. May be negative — a tile can hang off the left. |
| `y` | `integer` | yes | Top edge in canvas units. May be negative. |

### `CanvasSlotRect`

| Field | Type | Required | Description |
|---|---|---|---|
| `height` | `integer` | yes | Height in canvas units. 0 only on a degraded read. |
| `width` | `integer` | yes | Width in canvas units. 0 only on a degraded read. |
| `x` | `integer` | yes | Left edge in canvas units. |
| `y` | `integer` | yes | Top edge in canvas units. |

### `CanvasState`

| Field | Type | Required | Description |
|---|---|---|---|
| `activePreset` | `string` | yes | The active preset id, e.g. "2up". Meaningful in auto mode; retained but not applied in advanced mode. |
| `activeSceneId` | `string` | no | The active scene's id, absent when no scene is active. |
| `aspectRatio` | `string` | yes | The studio's aspect-ratio intent, e.g. "16/9". |
| `autoEmphasisEnabled` | `boolean` | yes | Whether the encoder may hero the loudest seat automatically this session. |
| `broughtInSourceIds` | `string[]` | yes | Extra legs pulled out of their owners' folded person-units so each has its own cell. Kept disjoint from traySourceIds. |
| `canvasBackground` | `CanvasBackground` | no | — |
| `canvasHeight` | `integer` | yes | Height of the coordinate space. 1080. |
| `canvasWidth` | `integer` | yes | Width of the COORDINATE SPACE the rectangles live in — 1920, fixed for every studio, and NOT the broadcast width. Scale a miniature by this; label the stream by `output`. |
| `fitMode` | `string (enum)` | yes | Frame-level fit for sources with no per-tile override. (one of: `contain`, `stretch`) |
| `focusSourceId` | `string` | yes | The source promoted to the focus slot. Auto-mode intent. |
| `layoutMode` | `string (enum)` | yes | Who owns geometry. 'auto': the server's planner resolves every rectangle from the active preset and overrides what you wrote. 'advanced': each tile stays exactly where you last put it. (one of: `auto`, `advanced`) |
| `layoutRev` | `integer` | yes | The layout revision. Monotonic per studio, bumped by every canvas write. Hold it and send it back as `baseRev` to make your next write refuse to clobber someone else's. |
| `membershipBasis` | `string (enum)` | yes | How onCanvas/inTray on every placement were reached.  'resolved' — the normal, authoritative answer: membership came from the auto planner, or (in advanced mode) from the stored placements the encoder is driven from. Trust it.  'stored' — the auto planner could NOT resolve this activePreset. The encoder declares the preset catalog and ships new presets independently, so a studio can legitimately hold one this server build does not know. Membership then falls back to the persisted tray column and the stored rectangles, both of which may be stale. Render the canvas, but do not conclude from it that a source is off air.  '' (empty) — an older server. It makes NO claim; do not read it as either value. (one of: `resolved`, `stored`, ``) |
| `output` | `ProgramOutput` | yes | — |
| `pinnedOwnerId` | `string` | yes | The person pinned as the permanent hero for this session, by owner key. Only meaningful under the person-grid presets. |
| `placements` | `CanvasPlacement[]` | yes | One row per source in the studio, seated or not. Ordered for painting: placed tiles first in draw order (z ascending, source id breaking ties), then the unplaced ones by id. |
| `screenPriority` | `boolean` | yes | Whether a shared screen outranks cameras when the planner seats people. |
| `slotAssignments` | `object` | yes | Sticky seating, per preset: preset id -> slot index (as a string) -> source id.  ALWAYS PRESENT, never null. An EMPTY object means 'no sticky seats are assigned on this studio' — a real state, not a failed read and not an unpopulated field. Sparse within itself: a preset or slot with no entry has no sticky seat and the planner picks for it.  Read this before POST /canvas/preset, whose slotAssignments is a WHOLE-SET replacement: take this map, change the entries you mean, send the whole thing back. |
| `spotlightId` | `string` | yes | The spotlit source id, EMPTY when none. Always present, never omitted, so a client mirroring the studio row does not have to tell absent from unset. Legacy sibling of focusSourceId, carried because the studio row carries it and a client mirroring the row would otherwise lose it on a round trip. |
| `tileOrder` | `string[]` | yes | Slot-order intent, by source id. Auto-mode only. |
| `traySourceIds` | `string[]` | yes | The overflow tray: active sources the current preset had no slot for. |
| `updatedAt` | `string` | yes | When the layout last changed, RFC 3339. |
| `verticalOverlay` | `VerticalOverlay` | no | — |

### `ChatConnector`

| Field | Type | Required | Description |
|---|---|---|---|
| `desired` | `boolean` | yes | Whether the studio wants this platform's chat attached. |
| `platform` | `string` | yes | The connector's identity: youtube, twitch, kick, ... |
| `requiresLiveBroadcast` | `boolean` | yes | True for platforms (YouTube) whose chat cannot attach until the broadcast is live, so an off-air "not connected" reads as calm rather than broken. |
| `state` | `string` | yes | The connector lifecycle state that drives the pill: connected, reconnecting, failed, idle, ... |

### `ChatMessage`

| Field | Type | Required | Description |
|---|---|---|---|
| `authorDisplayName` | `string` | yes | — |
| `authorId` | `string` | no | — |
| `id` | `string` | yes | — |
| `platform` | `string` | yes | — |
| `text` | `string` | yes | — |
| `timestamp` | `string` | no | — |

### `ChatMessageList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `ChatMessage[]` | yes | — |
| `nextCursor` | `string` | no | — |

### `ChatSendResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `messageId` | `string` | no | — |
| `ok` | `boolean` | yes | — |

### `CompleteMediaUploadRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `parts` | `CompletedMediaPart[]` | no | The finished parts. Omit the body entirely for a single-file upload. Order does not matter — the server sorts, because parts finish out of order when several are in flight — but COMPLETENESS does: a partial list is an error, not a partial completion. |

### `CompletedMediaPart`

| Field | Type | Required | Description |
|---|---|---|---|
| `etag` | `string` | no | The `ETag` response header that part's PUT returned, verbatim — quotes included, the server normalises. Browsers only see this header when the storage host exposes it via CORS; if you cannot read it, send the whole list with empty etags (or send no list at all) and the server recovers them from storage itself. |
| `partNumber` | `integer` | yes | The partNumber from the plan. |

### `Connection`

| Field | Type | Required | Description |
|---|---|---|---|
| `avatarUrl` | `string` | no | — |
| `connectedAt` | `string` | no | — |
| `connectionType` | `string` | yes | oauth \| manual |
| `displayName` | `string` | yes | — |
| `expiresAt` | `string` | no | — |
| `externalUserId` | `string` | no | — |
| `grantedScopes` | `string[]` | no | — |
| `id` | `string` | yes | — |
| `platform` | `string` | yes | — |
| `status` | `string` | yes | active \| needs_reauth \| expired \| revoked |
| `updatedAt` | `string` | no | — |

### `ConnectionList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `Connection[]` | yes | — |
| `nextCursor` | `string` | no | — |

### `ContributeRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `deviceId` | `string` | yes | Your app's own stable identifier for THIS DEVICE. Mint it once, keep it in the Keychain / Keystore, and send the same value forever.  It is the IDEMPOTENCY KEY for this endpoint. The same value always resolves to the same input on the same studio, which is what makes a reconnection land back on the same camera tile with the same credential instead of littering the studio with half-made inputs. A value your app regenerates each launch produces a new input each launch, and the operator watches their source list fill up with duplicates of one phone.  Opaque to TRaX and never resolved to anyone: send an identifier for the DEVICE, not for the person holding it. |
| `deviceLabel` | `string` | no | The human name for this input — "EJ's iPhone". Optional, and refreshed on every call, so renaming the phone renames the input the operator sees. Send nothing and the input keeps whatever it is already called. |
| `protocols` | `string[]` | no | Which publish protocols to hand back. Omit it (or send `[]`) for `["srt"]`, which is what the TRaX phone app dials and the protocol whose URL carries a real per-input credential.  A REQUEST, not a guarantee — read `granted` off the response. Ask for exactly what you will dial: every extra entry is another copy of the same live publish secret sitting in your app's memory, logs and crash reports. |

### `Contribution`

| Field | Type | Required | Description |
|---|---|---|---|
| `autoSeat` | `boolean` | yes | Whether this input takes a seat on the canvas by itself when the studio is ALREADY live. It NEVER starts the broadcast — going live is the operator's call and nothing on this path can make it happen. Read it to tell your user what will happen when they hit publish: a seat that appears on air, or a source the operator has to place. |
| `deviceId` | `string` | yes | Your `deviceId`, echoed back, so an app provisioning several devices can match a reply to a request without relying on ordering. |
| `granted` | `string[]` | yes | The protocols actually GRANTED, which may be narrower than requested and may be empty. Configure from this list, never from what you asked for. |
| `ingest` | `object` | yes | Publish endpoints keyed by protocol. Contains exactly the keys listed in `granted`. Same shape `POST .../sources/{sourceId}/ingest` returns, so if you already configure an encoder from a mint result you need no second code path here. |
| `ingestHost` | `string` | no | The hostname your credential points at, lifted out of the URLs so you can show "publishing to …" without parsing — or displaying — a string that is also a secret. Display only: dial the URLs. |
| `ingestMetro` | `string` | yes | Which metro this device is being steered to, or `"auto"`.  Today it is always `"auto"`, and that is a measurement rather than a placeholder: nearest-point-of-presence selection happens in DNS, when your device RESOLVES the ingest hostname, not when this call mints the URL. The server genuinely does not know which PoP you will reach, and inferring one from your IP address would be wrong for every VPN, every carrier-grade NAT, and most mobile subscribers — which is exactly the population this endpoint exists for.  DISPLAY it; do not branch on it. A later release may name a real metro here, and a client that special-cased the string would break on the improvement. |
| `sourceId` | `string` | yes | The input this device is bound to. Stable for the life of the device on this studio — store it, and use it for the ordinary source calls: rename with `PATCH /v1/studios/{id}/sources/{sourceId}`, rotate the credential with `POST .../ingest/rotate`, remove the input with `DELETE`. |
| `srtStreamId` | `string` | no | The raw SRT streamid to dial with — `publish:<path>:<key>:<key>`, NOT url-encoded, because libsrt wants literal colons as delimiters. It carries no JWT: the scoped key is the whole capability, which is what keeps it comfortably under SRT's 512-byte streamid cap.  Present only when `srt` is in `granted`. Prefer the `complete` URL; this exists for encoder SDKs that want the streamid as its own socket option. |
| `streamKey` | `string` | yes | The input's stream key, on its own, for encoders whose UI asks for a server and a stream key as two separate fields. Already embedded in every `complete` URL in this response, so it adds no exposure — and it is still a live publish credential. Keychain, not log line. |
| `streamName` | `string` | yes | The media path you are publishing to, e.g. `inputs/mobile-contrib-mc-<hex>`. The one field in this response that is safe to log — use it to correlate this device's session with `GET /v1/studios/{id}/stream-status`. |

### `CreateBroadcastRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `description` | `string` | no | Description body. Optional. |
| `scheduledStartTime` | `string` | no | RFC 3339 planned start. Absent = CREATE NOW on YouTube (a near-immediate start is stamped); Facebook's scheduled path requires a future time at least ~10 minutes out. |
| `title` | `string` | yes | Title for the created broadcast. Required — YouTube rejects untitled broadcasts. Overrides the saved broadcastConfig's title. |

### `CreateBroadcastTemplateRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `config` | `object` | yes | The BroadcastConfig snapshot as a JSON object. Required; a scalar/array is rejected. |
| `isDefault` | `boolean` | no | Pin the new template as the studio's default in the same transaction. Default false. |
| `name` | `string` | yes | Human label. Required. |

### `CreateDestinationRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `broadcastConfig` | `BroadcastConfig` | no | — |
| `connectionId` | `string` | no | Bind to a linked account; mutually exclusive with rtmpUrl+streamKey. |
| `enabled` | `boolean` | no | — |
| `name` | `string` | yes | — |
| `platform` | `string` | yes | — |
| `rtmpUrl` | `string` | no | — |
| `streamKey` | `string` | no | Write-only; never returned on any read. |
| `vertical` | `boolean` | no | — |

### `CreateManualConnectionRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | `string` | yes | The name shown in destination pickers, e.g. "My Facebook Page". Required. |
| `platform` | `string` | no | Free-form: facebook \| instagram \| rumble \| twitter \| tiktok \| custom \| ... Empty defaults to custom. |
| `rtmpUrl` | `string` | yes | RTMP(S) push URL from the platform's stream dashboard, e.g. rtmps://live-api-s.facebook.com:443/rtmp. Required. |
| `streamKey` | `string` | yes | The stream key. WRITE-ONLY: stored encrypted and never returned by any read on this API. Required. |

### `CreateMediaUploadRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `byteSize` | `integer` | yes | — |
| `contentType` | `string` | yes | — |
| `filename` | `string` | yes | — |
| `folder` | `string` | no | — |

### `CreateSourceRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `active` | `boolean` | no | — |
| `mediaAssetId` | `string` | no | Attach a media-library asset as this source, instead of a URL. Pass an id from `GET /v1/media`; it must be READY and yours, and the type must be a library-backed kind.  The server resolves it to a storage URL the ENCODER can reach, which is a different signature from the `downloadUrl` a phone gets — and it re-mints that URL whenever it expires. That is why an asset-backed source keeps working and a pasted presigned URL rots.  Mutually exclusive with `url`: sending both is a 400, not a precedence rule you have to remember. |
| `name` | `string` | yes | — |
| `type` | `string` | yes | webcam \| rtmp \| srt \| webrtc-input \| media \| ... The library-backed kinds — `video-file`, `image`, `audio-file`, `media` — are the ones `mediaAssetId` applies to. |
| `url` | `string` | no | Source URL for URL-backed kinds. Mutually exclusive with `mediaAssetId`. Ignored for kinds where TRaX provisions the ingest itself (webcam, webrtc-input, generic-input) — for those leave it empty and read the endpoints back from `POST .../ingest`. |

### `CreateStudioRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | — |

### `Destination`

| Field | Type | Required | Description |
|---|---|---|---|
| `connectionId` | `string` | no | The linked account supplying this destination's credentials; absent for a pasted-credential row. This is the join key to GET /v1/connections — the only way to find out WHICH account to re-link when a leg stops resolving. |
| `createdAt` | `string` | no | — |
| `degraded` | `boolean` | no | True while the encoder is DROPPING frames toward this leg to protect the others: the stream is still live and the picture is degrading. Meaningful only during a live session. |
| `drainPct` | `integer` | no | How much of this leg's buffer is being shed, 0-100. On an idle destination this is 0, which means "not applicable", not "measured healthy". |
| `enabled` | `boolean` | yes | VIDEO ONLY. A disabled destination is retained but no video leg is opened for it. It does NOT govern chat: for an always-on platform (twitch, kick, trovo, linkedin) the chat connector attaches from the linked account whether this is true or false, and whether or not the studio is live. See requiresLiveBroadcast. |
| `encoderStreamId` | `string` | no | The encoder's id for this leg while a session runs. Correlation only; absent when the studio is not live. |
| `id` | `string` | yes | — |
| `lastError` | `string` | no | Why the leg last failed, verbatim from whatever refused it. Read this whenever status is ERROR or STALLED: status alone cannot tell a revoked token from an unreachable ingest host. |
| `name` | `string` | yes | — |
| `platform` | `string` | yes | youtube \| twitch \| kick \| custom_rtmp \| ... Not validated against a closed set: an unrecognised value is stored as given. |
| `requiresLiveBroadcast` | `boolean` | no | Whether this destination's PLATFORM can only attach chat once a broadcast is live (youtube, facebook, instagram, tiktok have no chat channel id before then). A property of the platform, not this row. |
| `rtmpUrl` | `string` | no | Set for a pasted-credential destination. ABSENT for a connection-backed one: that URL is resolved fresh from the linked account at each go-live and never stored, so there is nothing truthful to return between streams. |
| `settings` | `object` | no | Opaque per-destination settings, round-tripped unchanged. Its schema is not part of this contract. |
| `status` | `string` | no | IDLE \| CONNECTING \| LIVE \| ERROR \| STALLED \| STOPPING. Meaningful only while the studio is live; treat the value set as open and match defensively. |
| `streamKey` | `string` | no | MASKED: "****" plus the last four characters, or "****" for a key of four characters or fewer. Absent when no key is stored, which is every connection-backed destination. No surface returns the plaintext — losing it means rotating at the platform. |
| `studioId` | `string` | yes | — |
| `updatedAt` | `string` | no | — |
| `vertical` | `boolean` | yes | — |

### `DestinationList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `Destination[]` | yes | — |
| `nextCursor` | `string` | no | — |

### `Error`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | `object` | yes | — |

### `GoLiveResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `destinationIds` | `string[]` | yes | — |
| `encoderStreamId` | `string` | yes | — |

### `GoOfflineResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `ok` | `boolean` | yes | — |

### `Health`

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `string` | yes | — |
| `writeEnabled` | `boolean` | no | Whether mutating (write) endpoints are currently enabled. |

### `IngestEndpoint`

| Field | Type | Required | Description |
|---|---|---|---|
| `base` | `string` | no | The same endpoint with the credential stripped, e.g. `srt://ingest.traxstreaming.live:8890`. INFORMATIONAL ONLY — it does not authenticate, and `base` + `streamKey` is not a working substitute for `complete`. An RTMP publish is authenticated by the `?user=`/`?pass=` query parameters that only `complete` carries, so an encoder configured with `base` as the server and `streamKey` as the key is rejected at the handshake. Use it to SHOW an operator where a contributor publishes without showing what lets them; dial `complete`. |
| `complete` | `string` | yes | The URL to hand your encoder, credential included. For SRT that is the whole `srt://host:port?streamid=publish:<path>:<key>:<key>&latency=...` string — the stream key appears TWICE, as the streamid's user and pass fields. For RTMP/RTMPS the credential rides as `?user=<key>&pass=<key>` query parameters, not as URL userinfo. This IS the secret. Store it in the platform keychain, never in a log line or an analytics event.  Dial it VERBATIM. Do not reassemble it from parts: the credential form is the server's to decide and it has changed before, and a client that rebuilds the URL from a remembered shape keeps sending the old one long after the server moved on. |

### `LinkStart`

| Field | Type | Required | Description |
|---|---|---|---|
| `authorizationUrl` | `string` | yes | Open this in a browser the user controls. Single-use, and it expires with the state below. Do NOT follow it server-side: the platform shows a consent screen, not a token. |
| `expiresAt` | `string` | no | When the URL stops working, RFC 3339. Ten minutes out today. After this, call the endpoint again. |
| `state` | `string` | yes | The opaque CSRF/state token embedded in the URL, returned so a caller with several link attempts in flight can tell which one came back. Single-use. |

### `LinkStartRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `platform` | `string (enum)` | yes | Which platform to link. A platform TRaX has no OAuth application configured for is a 400, not an empty URL. (one of: `twitch`, `youtube`, `kick`, `facebook`, `linkedin`, `trovo`) |
| `reconnectConnectionId` | `string` | no | RE-AUTH IN PLACE. Set this to an existing connection.s id to refresh its grant while KEEPING that id, instead of creating a second row. This is the repair for a connection whose status has gone needs_reauth or expired. |
| `returnTo` | `string` | no | Where the browser lands after the platform redirects back. Must be a TRaX-owned https host. Omit for the default landing page. |
| `scopes` | `string[]` | no | OAuth scopes to request. LEAVE THIS OUT to get the platform's default set, which is what TRaX's own features need — that is the right choice unless you know exactly why it is not. Requesting less links successfully and then silently fails at whichever feature needed the missing scope; check `grantedScopes` on the resulting connection to see what the platform actually gave. |

### `MediaAsset`

| Field | Type | Required | Description |
|---|---|---|---|
| `byteSize` | `integer` | yes | — |
| `contentType` | `string` | no | — |
| `createdAt` | `string` | no | — |
| `durationSeconds` | `number` | no | Fractional seconds. 0 for a still image, and 0 when the file could not be probed — picker metadata, not a guarantee. |
| `filename` | `string` | yes | — |
| `folder` | `string` | no | — |
| `height` | `integer` | no | Pixels. 0 when unknown or not applicable (audio). |
| `id` | `string` | yes | — |
| `kind` | `string` | yes | video \| image \| audio |
| `status` | `string` | yes | UPLOADING \| READY \| FAILED. Only READY can be attached to a studio. |
| `thumbnailUrl` | `string` | no | Short-lived presigned GET for a generated thumbnail. Absent for a non-READY asset and for one with no extractable thumbnail (audio, most images) — draw a kind icon, do not treat it as an error. It EXPIRES: fetch it at render time, never store it. A list row carries a thumbnail and no download URL; reading the file itself is `GET /v1/media/{assetId}`. |
| `width` | `integer` | no | Pixels. 0 when unknown or not applicable (audio). |

### `MediaAssetDetail`

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | `string` | yes | — |
| `contentType` | `string` | no | — |
| `createdAt` | `string` | no | — |
| `downloadUrl` | `string` | no | Short-lived presigned GET for the original file, signed for the public storage host so it resolves from a phone. Absent unless READY. It EXPIRES — fetch it when you render, never persist it. You do NOT need it to put the file on a canvas: pass `mediaAssetId` to `POST /v1/studios/{id}/sources` and the server resolves its own encoder-facing URL. |
| `durationSeconds` | `number` | yes | Fractional seconds. 0 for a still image and 0 when the file could not be probed. |
| `errorMessage` | `string` | no | Why the asset is FAILED, when it is. |
| `filename` | `string` | yes | — |
| `folder` | `string` | no | — |
| `height` | `integer` | yes | — |
| `kind` | `string` | yes | video \| image \| audio |
| `sizeBytes` | `integer` | yes | The size MEASURED in storage once the upload completed — not the size you declared. |
| `status` | `string` | yes | UPLOADING \| READY \| FAILED. Poll until READY after completing an upload; only a READY asset carries URLs and only a READY asset can back a source. |
| `thumbnailUrl` | `string` | no | Short-lived presigned GET for the generated thumbnail. Absent unless READY, and absent when none could be extracted. |
| `updatedAt` | `string` | no | Moves when the upload completes — the field to watch while polling. |
| `width` | `integer` | yes | — |

### `MediaAssetList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `MediaAsset[]` | yes | — |
| `nextCursor` | `string` | no | — |
| `quotaLimitBytes` | `integer` | yes | The account's storage ceiling in bytes. An upload that would cross it is refused at `POST /v1/media` with 402 storage_quota_exceeded. |
| `quotaUsedBytes` | `integer` | yes | Bytes the library currently holds. Rides on the list rather than a separate endpoint so you can render usage, and warn a user their library is full, BEFORE they pick a file. |

### `MediaUpload`

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | `string` | yes | The reserved asset. It exists immediately in status UPLOADING and counts against quota from this moment — if you give up, call `/abort`. |
| `kind` | `string` | yes | video \| image \| audio, derived from the contentType you declared. Returned so you can branch before the upload finishes. |
| `mode` | `string` | yes | `single` or `multipart`. BRANCH ON THIS. The two shapes are mutually exclusive: `single` carries `uploadUrl` and no parts, `multipart` carries `parts` and no `uploadUrl`. The split point is server policy and it moves, so a client that reads `mode` keeps working when it does — one that only reads `uploadUrl` uploads nothing the day its user picks a big file. |
| `objectKey` | `string` | yes | Where the bytes land in storage. Informational — you do not need it. |
| `partBytes` | `integer` | no | Multipart path only: the size of every part but the last. Informational — cut the file by each part's own `offset`/`byteSize`. |
| `parts` | `MediaUploadPart[]` | no | Multipart path only: one presigned PUT per part, in order. PUT each part's slice to its URL, keep the `ETag` response header each one returns, then call `/complete` with the full list. Parts may go up in any order and a few at a time; completeness is what matters, not order. |
| `uploadUrl` | `string` | no | Single-file path only: a short-lived presigned PUT. Send the raw bytes with HTTP PUT and a Content-Type matching what you declared. SECRET — never log it. |

### `MediaUploadPart`

| Field | Type | Required | Description |
|---|---|---|---|
| `byteSize` | `integer` | yes | How many bytes to send for this part. Equal to `partBytes` for every part but the last. |
| `offset` | `integer` | yes | Byte offset into your local file where this part starts. Do NOT re-derive it from a part size of your own — the server may have grown the part size to keep the plan under the storage layer's part-count ceiling, so this plan is the only correct description of how the file is cut. |
| `partNumber` | `integer` | yes | 1-based part index. Send it back on `/complete` paired with the ETag the storage host returned for this part. |
| `url` | `string` | yes | Presigned PUT for this part. SECRET — the URL itself grants write access, so keep it out of logs. Short-lived; an expired plan needs a new `POST /v1/media`, not a retry. |

### `MintViewerTokenRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `caps` | `string (enum)[]` | yes | Requested capabilities. An unrecognised value is rejected rather than ignored — a silently dropped capability is a viewer with quietly wrong access. |
| `displayName` | `string` | no | The sender name PUBLISHED with a relayed chat message. REQUIRED whenever caps contains chat.send. A relayed message goes out on the BROADCASTER's connected platform accounts, so without a name it reads as the broadcaster speaking. Unlike memberRef this value is PUBLIC by construction — send a display name, never an email or an internal id. Sanitized and truncated to 32 characters. |
| `memberRef` | `string` | no | YOUR opaque identifier for the person, e.g. their user id in your system. Never resolved to anyone by TRaX; used only as a rate-limit and revocation key. Optional for read-only capabilities; REQUIRED whenever caps contains chat.send. |
| `studioId` | `string` | yes | The studio the viewer will reach. The token is scoped to exactly this studio and is refused if presented against another. |
| `ttlSeconds` | `integer` | no | Requested lifetime. Omit or use 0 for the 900s default; anything above 3600 is clamped rather than refused. Read the real expiry off the response. |

### `Monitor`

| Field | Type | Required | Description |
|---|---|---|---|
| `expiresAt` | `string` | yes | RFC 3339. Reflects the CLAMPED lifetime, which may be shorter than you asked for.  It bounds when a NEW connection may be made. A session that is ALREADY playing outlives it: the media server authorises a read once, at session establishment, and never re-checks — so your picture does not go black when this passes. Mint again to (re)connect, not to keep watching. |
| `srt` | `object` | yes | An SRT alternative for a client that cannot speak WHEP, or `null` when one cannot be built.  `null` is a real answer, not a missing field: the read credential rides INSIDE SRT's streamid, which libsrt caps at 512 bytes and rejects locally — before anything reaches the network — when exceeded. When the composed URL would be over the cap, or no SRT endpoint is configured, the server returns null rather than a URL that cannot dial. Handle it by falling back to WHEP, which is the path you should be on anyway. |
| `streamName` | `string` | yes | The program path being monitored, e.g. `s/<studio-id>/pp`. Safe to log. |
| `whep` | `MonitorWhep` | yes | — |

### `MonitorRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `ttlSeconds` | `integer` | no | Requested lifetime for the credential. Omit it (or send 0 or less) for the 300-second default; anything above the 900-second ceiling is CLAMPED, not refused. Read the real expiry off `expiresAt` — never schedule from the value you asked for. |

### `MonitorWhep`

| Field | Type | Required | Description |
|---|---|---|---|
| `token` | `string` | yes | Send as `Authorization: Bearer <token>` on the WHEP signaling request. It is NOT your API key and NOT the user's login token: it authorises exactly this studio's program path, for a few minutes, and nothing else. That is what makes it safe to put on a signaling request your API key has no business appearing on. |
| `url` | `string` | yes | POST your SDP offer here. This is the path every client should take — WebRTC degrades on a lossy cellular uplink far better than the alternative. |

### `Ok`

| Field | Type | Required | Description |
|---|---|---|---|
| `ok` | `boolean` | yes | — |

### `PickBroadcastRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `broadcastId` | `string` | no | The platform broadcast id to pick, from the broadcasts list. null or empty CLEARS the pick and returns the destination to create mode (auto-create at go-live). |
| `title` | `string` | no | Human title stored on the pick pointer so status rows can label it without a platform round trip. Optional; ignored when clearing. |

### `ProgramOutput`

| Field | Type | Required | Description |
|---|---|---|---|
| `fpsDen` | `integer` | yes | Frame-rate denominator, e.g. 1 — or 1001 for 59.94. Rational rather than rounded, because 59.94 and 60 are different broadcasts. |
| `fpsNum` | `integer` | yes | Frame-rate numerator, e.g. 60 — or 60000 for 59.94. |
| `height` | `integer` | yes | Output height in pixels. |
| `width` | `integer` | yes | Output width in pixels. |

### `RemovedResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes | — |

### `ReplanCanvasRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `layoutMode` | `string (enum)` | no | Send "auto" to flip an advanced studio back to the planner and re-plan in one call — this is the way OUT of advanced mode. Omit to re-plan in place, which is a no-op on an advanced studio. (one of: `auto`, `advanced`) |

### `Scene`

| Field | Type | Required | Description |
|---|---|---|---|
| `category` | `string` | yes | Grouping label, e.g. "general". |
| `description` | `string` | no | Free-text description. |
| `hasComposition` | `boolean` | yes | FALSE means this scene is a label with no saved canvas behind it — recalling it changes nothing. Reported explicitly so a client can grey the row instead of offering a recall that silently does nothing. |
| `hotkey` | `string` | no | Keyboard shortcut the studio UI binds it to. |
| `id` | `string` | yes | The scene id — what the recall endpoint takes. |
| `isActive` | `boolean` | yes | Whether this is the scene currently on the program. |
| `isFavorite` | `boolean` | yes | Whether the operator marked it a favourite. |
| `name` | `string` | yes | Display name. |
| `transitionDuration` | `number` | yes | Transition length in seconds. 0 for a cut. |
| `transitionType` | `string` | yes | How the program cuts to it: "cut", "fade", ... Free text — see the capabilities endpoint's `transitions` for the names the studio UI offers. |
| `updatedAt` | `string` | yes | When the scene last changed, RFC 3339. |

### `SceneList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `Scene[]` | yes | — |

### `SendChatMessageRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `platforms` | `string[]` | no | Subset to fan out to; empty = every enabled platform. |
| `text` | `string` | yes | — |

### `SetActiveSceneRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `sceneId` | `string` | yes | The scene to recall. A scene id from a studio you cannot see answers 404, identical to one that does not exist. |

### `SetCanvasPresetRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `focusSourceId` | `string` | no | The source to promote to the focus slot. Send an empty string to clear the focus. |
| `layoutMode` | `string (enum)` | no | Usually omitted. Picking a preset while advanced persists the intent without applying it. (one of: `auto`, `advanced`) |
| `presetId` | `string` | no | A preset id from the capabilities endpoint. Do not hardcode the catalog — it is declared by the encoder and it changes. Present but empty is a 400. |
| `slotAssignments` | `object` | no | The WHOLE sticky-seat map: preset id -> slot index (as a string) -> source id. |
| `tileOrder` | `string[]` | no | The WHOLE slot order. Present (including empty) REPLACES the stored order. |
| `traySourceIds` | `string[]` | no | The WHOLE overflow tray. Present (including empty) REPLACES the stored set. |

### `Source`

| Field | Type | Required | Description |
|---|---|---|---|
| `active` | `boolean` | yes | — |
| `createdAt` | `string` | no | — |
| `id` | `string` | yes | — |
| `name` | `string` | yes | — |
| `publishedAt` | `string` | no | When the CURRENT publish began (RFC 3339). Absent when nothing is publishing or when the start time is unknown. Stable while the publisher stays connected — a new value means it dropped and reconnected. |
| `publishing` | `boolean` | no | Is a publisher attached to this input right now — media-plane truth, the same signal the studio UI's source LEDs use. NULL means the liveness tracker could not be reached on this request: UNKNOWN, not offline. A client polling "am I live yet" must treat null as "ask again". |
| `status` | `string` | no | Control-plane provisioning state (`OK`, `MISSING`, `RECREATING`, `INGEST_DOWN`). Says whether this input still has a backing ingest stream — NOT whether media is arriving. A perfectly provisioned input nobody is publishing to reads `OK`. For "is anything arriving", read `publishing`. |
| `studioId` | `string` | yes | — |
| `type` | `string` | yes | — |

### `SourceIngest`

| Field | Type | Required | Description |
|---|---|---|---|
| `granted` | `string[]` | yes | The protocols actually GRANTED, which may be narrower than requested and may be EMPTY. Configure your client from this list, never from what you asked for. |
| `ingestUrls` | `object` | yes | Endpoints keyed by protocol. Contains exactly the keys listed in `granted` — never a protocol you asked for but cannot publish over. |
| `streamKey` | `string` | yes | The input's stream key. ALWAYS PRESENT — on a mint and on a rotate alike. It is the SAME credential that is already embedded inside every `complete` URL in this response: for SRT it is the streamid's user and pass fields, for RTMP/RTMPS the `?user=` and `?pass=` query parameters. Repeating it here therefore adds no exposure, and it exists for encoders whose UI asks for a server and a stream key as two separate fields.  It is still a live publish credential. Store it in the platform keychain alongside `complete`, never in a log line. Note that `base` + `streamKey` is NOT a working substitute for `complete` — dial `complete` verbatim. |
| `streamName` | `string` | yes | The media path this source publishes to, e.g. `inputs/generic-input-<uuid>`. Stable for the life of the source and the one field here that is safe to log — use it to correlate a device's session with stream status and metrics. |

### `SourceIngestRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `protocols` | `string (enum)[]` | no | The protocols you want endpoints for. Omit the body entirely, or send an empty array, for the `["srt"]` default. Ask for exactly what your client will dial: every extra entry is another copy of a live publish credential in your app's memory, logs and crash reports. An unrecognised NAME is a 400; a recognised protocol this source cannot publish over is simply absent from `granted` (see the response). |

### `SourceIngestRotateRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `kickPublishers` | `boolean` | no | Cut whatever is publishing to this input right now, immediately after the new credential is saved. The media server authorises a publish once, at handshake, and never re-checks — so a session that connected with the OLD key keeps broadcasting through the rotation until its socket drops. Send `true` when you are revoking a leaked credential and mean it. Leave it `false` (the default) for a planned hand-over: the broadcast in progress finishes on the old key while every NEW connection requires the new one. |
| `protocols` | `string (enum)[]` | no | The protocols you want endpoints for AFTER rotating. Same semantics as the mint endpoint: omit the body or send an empty array for the `["srt"]` default, and read `granted` off the response rather than assuming you got what you asked for. This scopes what comes BACK, not what is invalidated — rotation replaces the single underlying stream key, so asking only for `srt` still kills the old `rtmp` URL. An unrecognised NAME is a 400 and nothing is rotated. |

### `SourceList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `Source[]` | yes | — |
| `nextCursor` | `string` | no | — |

### `StorageConfig`

| Field | Type | Required | Description |
|---|---|---|---|
| `accessKeyLast4` | `string` | no | The last four characters of the stored access key id, so you can tell two credentials apart. Never the whole key, never the secret. |
| `bucket` | `string` | yes | — |
| `createdAt` | `string` | no | — |
| `endpoint` | `string` | yes | — |
| `forcePathStyle` | `boolean` | yes | Address the bucket as a path segment rather than a subdomain. True for most non-AWS providers; defaults true on create when unset. |
| `id` | `string` | yes | — |
| `lastVerifiedAt` | `string` | no | — |
| `name` | `string` | yes | — |
| `prefix` | `string` | no | The key prefix TRaX confines itself to. Absent or empty means the bucket root. |
| `provider` | `string` | yes | s3 is the only value today; any S3-compatible endpoint (AWS, Backblaze B2, Cloudflare R2, MinIO, Garage) is reached through it. |
| `region` | `string` | no | — |
| `status` | `string` | yes | unverified \| ok \| unreachable \| invalid_creds \| forbidden.  EVENT-DRIVEN, never swept: written on create, update and verify, downgraded when a real operation fails, healed by the next success. An old "ok" means "worked when last exercised", not "works now". |
| `statusDetail` | `string` | no | Human-readable detail behind status — usually your provider's own error text. |
| `updatedAt` | `string` | no | — |

### `StorageConfigList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `StorageConfig[]` | yes | — |
| `nextCursor` | `string` | no | — |

### `StorageProbeResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `string` | yes | ok \| unreachable \| invalid_creds \| forbidden. A non-ok verdict arrives as a SUCCESSFUL 200 — read this field, not the HTTP code. |
| `statusDetail` | `string` | no | — |

### `StorageWrite`

| Field | Type | Required | Description |
|---|---|---|---|
| `accessKeyId` | `string` | no | Write-only. Only its last four characters are ever readable again. |
| `bucket` | `string` | no | — |
| `endpoint` | `string` | no | Full S3 endpoint URL, e.g. https://s3.us-west-002.backblazeb2.com. A bare hostname is rejected. |
| `forcePathStyle` | `boolean` | no | Defaults to true when omitted on create, which is right for most non-AWS providers. |
| `name` | `string` | no | — |
| `prefix` | `string` | no | — |
| `region` | `string` | no | — |
| `secretAccessKey` | `string` | no | Write-only. Never returned by any surface. |

### `StreamStatus`

| Field | Type | Required | Description |
|---|---|---|---|
| `broadcastStartedAt` | `string` | no | — |
| `encoderStreamId` | `string` | no | — |
| `live` | `boolean` | yes | — |
| `liveStartedAt` | `string` | no | — |
| `mode` | `string` | no | cloud \| local |

### `Studio`

| Field | Type | Required | Description |
|---|---|---|---|
| `createdAt` | `string` | no | — |
| `description` | `string` | no | — |
| `id` | `string` | yes | — |
| `lastOpenedAt` | `string` | no | — |
| `name` | `string` | yes | — |
| `ownerSub` | `string` | yes | — |
| `role` | `string` | yes | owner \| VIEW \| EDIT \| ADMIN |

### `StudioAudio`

| Field | Type | Required | Description |
|---|---|---|---|
| `master` | `AudioMaster` | yes | — |
| `sources` | `AudioSourceStrip[]` | yes | One strip per source row, in the same order the sources list returns them. Empty when the studio has no sources — an empty mix, not an error. |

### `StudioEventSnapshot`

| Field | Type | Required | Description |
|---|---|---|---|
| `audio` | `StudioAudio` | yes | The studio.s audio mixer — the same shape GET /v1/studios/{id}/audio returns. |
| `canvas` | `CanvasState` | yes | The studio.s canvas/scenes/presets state — the same shape GET /v1/studios/{id}/canvas returns. |
| `chatConnectors` | `ChatConnector[]` | yes | Every linked platform's chat connector state. Empty when no chat platforms are linked — state, not an omission. |
| `destinations` | `Destination[]` | yes | — |
| `sources` | `Source[]` | yes | — |
| `streamStatus` | `StreamStatus` | yes | — |

### `StudioList`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `Studio[]` | yes | — |
| `nextCursor` | `string` | no | — |

### `ThumbnailResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `thumbnailUrl` | `string` | yes | The thumbnail URL YouTube now serves for the broadcast. |

### `UpdateAudioMasterRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `muted` | `boolean` | no | New master gate state. True silences the program on every destination. |
| `volume` | `number` | no | New master fader position, LINEAR. Outside 0.0–10.0 is a 400. |

### `UpdateAudioSourceRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `muted` | `boolean` | no | New gate state. Set THIS to mute someone; writing volume 0.0 instead loses their fader position. |
| `pan` | `number` | no | New stereo position. Outside -1.0–1.0 is a 400. |
| `soloed` | `boolean` | no | New solo latch. |
| `trim` | `number` | no | New pre-fader input gain, LINEAR. Outside 0.1–16.0 is a 400. |
| `volume` | `number` | no | New fader position, LINEAR. Outside 0.0–10.0 is a 400, not a clamp. |

### `UpdateBroadcastRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `broadcastId` | `string` | yes | The YouTube broadcast to edit. Required so the change never lands on the wrong stream. |
| `categoryId` | `string` | no | snippet.categoryId. |
| `description` | `string` | no | snippet.description. Applied to the picked broadcast. |
| `enableAutoStart` | `boolean` | no | contentDetails.enableAutoStart. |
| `enableAutoStop` | `boolean` | no | contentDetails.enableAutoStop. |
| `enableDvr` | `boolean` | no | contentDetails.enableDvr. Immutable once testing/live. |
| `enableEmbed` | `boolean` | no | contentDetails.enableEmbed. Immutable once testing/live. |
| `enableMonitorStream` | `boolean` | no | contentDetails.monitorStream.enableMonitorStream. Immutable once testing/live. |
| `latency` | `string (enum)` | no | contentDetails.latencyPreference. Immutable once testing/live. (one of: `normal`, `low`, `ultraLow`) |
| `madeForKids` | `boolean` | no | status.selfDeclaredMadeForKids (COPPA). |
| `privacy` | `string (enum)` | no | status.privacyStatus. (one of: `public`, `unlisted`, `private`) |
| `projection` | `string (enum)` | no | contentDetails.projection. Immutable once testing/live. (one of: `rectangular`, `360`) |
| `recordFromStart` | `boolean` | no | contentDetails.recordFromStart. Immutable once testing/live. |
| `streamDelayMs` | `integer` | no | contentDetails.broadcastStreamDelayMs. Immutable once testing/live. |
| `title` | `string` | no | snippet.title. Applied to the picked broadcast. |

### `UpdateBroadcastTemplateRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `config` | `object` | yes | New BroadcastConfig snapshot as a JSON object. Required. The default pin is left untouched. |
| `name` | `string` | yes | New human label. Required. |

### `UpdateCanvasPlacementRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `alpha` | `number` | no | New opacity. Outside 0.0-1.0 is a 400, not a clamp. |
| `baseRev` | `integer` | no | The layoutRev this edit was based on. Omit for last-write-wins. A stale baseRev is a 409 — EXCEPT when the tile already holds exactly the values this request asks for, which is the retry case and comes back 200. That exception is what makes this call safe to retry over a connection that drops after the write lands. |
| `cropPanX` | `number` | no | New visible-rect centre X. |
| `cropPanY` | `number` | no | New visible-rect centre Y. |
| `cropZoom` | `number` | no | New punch-in factor. Send 1.0 to clear a crop. |
| `fitMode` | `string (enum)` | no | New per-source fit. (one of: `contain`, `stretch`) |
| `rect` | `CanvasRect` | no | — |
| `visible` | `boolean` | no | Whether to draw the tile. False keeps the rectangle so the tile does not jump when shown again. |
| `zIndex` | `integer` | no | New stacking order. Higher draws in front. |

### `UpdateCanvasRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `aspectRatio` | `string` | no | New aspect-ratio intent, e.g. "16/9". |
| `baseRev` | `integer` | no | The layoutRev this edit was based on. Omit for last-write-wins. Send it and a write based on a revision the canvas has already passed is refused with 409 rather than applied. |
| `canvasBackground` | `CanvasBackground` | no | — |
| `fitMode` | `string (enum)` | no | New frame-level fit. (one of: `contain`, `stretch`) |
| `layoutMode` | `string (enum)` | no | Who owns geometry from now on. Anything else is a 400. (one of: `auto`, `advanced`) |
| `screenPriority` | `boolean` | no | Whether a shared screen outranks cameras in auto seating. |
| `verticalOverlay` | `VerticalOverlay` | no | — |

### `UpdateDestinationRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `broadcastConfig` | `BroadcastConfig` | no | — |
| `enabled` | `boolean` | no | — |
| `name` | `string` | no | — |
| `platform` | `string` | no | — |
| `rtmpUrl` | `string` | no | — |
| `streamKey` | `string` | no | Write-only; never returned on any read. |
| `vertical` | `boolean` | no | — |

### `UpdateManualConnectionRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | `string` | no | New label. Absent = keep; empty string is rejected (a connection always has a label). |
| `rtmpUrl` | `string` | no | New RTMP(S) push URL. Absent = keep; empty string is rejected. |
| `streamKey` | `string` | no | New stream key. Absent OR empty = keep the stored key — there is no key-clear; rotate the key on the platform and PATCH it here, or delete the connection. |

### `UpdateSourceRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `active` | `boolean` | no | — |
| `name` | `string` | no | — |
| `url` | `string` | no | — |

### `UpdateStudioRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `autoGoLive` | `boolean` | no | — |
| `autoGoOfflineOnDrop` | `boolean` | no | — |
| `name` | `string` | no | — |

### `VerticalOverlay`

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | `boolean` | yes | Whether the guide is shown. |
| `height` | `integer` | yes | Guide height in canvas units. |
| `width` | `integer` | yes | Guide width in canvas units. |
| `xOffset` | `integer` | yes | Horizontal offset of the guide, in canvas units. |

### `ViewerToken`

| Field | Type | Required | Description |
|---|---|---|---|
| `caps` | `string[]` | yes | The capabilities actually GRANTED, which may be narrower than requested. Render your interface from these. |
| `expiresAt` | `string` | yes | Absolute expiry. Reflects the CLAMPED lifetime, which may be shorter than requested — schedule the next mint from this. |
| `token` | `string` | yes | The credential. Safe to hand to a browser, unlike the API key that minted it. |


<!-- reference/path-grammar -->


# Stream paths

Every feed in TRaX lives at a **path** — the routing key shared by all protocols
(the SRT streamid `path` field, the RTMP URL path, the WHIP/WHEP URL path) and
bound into every session token's `path` claim.

## The public grammar

External contributions are provisioned as **input paths**:

```
inputs/<type>-<uuid>
```

- `<type>` — the input kind assigned at provisioning (for example `srt`, `rtmp`).
- `<uuid>` — the input's unique id.

You receive the exact path when your input is provisioned; treat it as opaque.
Paths are exact-match — there is no wildcarding, no trailing-slash tolerance,
and case matters.

## Rules

1. **The path in the URL and the path in the token must be identical.** The token
   binds `action` + `path`; any difference is an auth failure, not a 404.
2. **Don't construct paths yourself.** Other path families exist on the platform
   for internal use (studio program feeds, participant devices, monitoring).
   They are not contracts and reject external credentials — only the
   `inputs/...` path you were provisioned is yours.
3. **Budget for the path in SRT.** The path is part of the streamid, which has a
   [512-byte hard cap](/reference/srt-streamid) — another reason not to invent
   long paths.


<!-- reference/errors -->


# Errors & status codes

Every `/v1` endpoint returns errors in **one envelope**, so you write the
error-handling path once and it works for the whole API:

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "the API key is missing the required scope: stream:golive",
    "requestId": "req_9f2c1a7b4e5d6f80",
    "requiredScope": "stream:golive"
  }
}
```

- **`code`** — a stable, machine-readable string. Branch on this, not on the
  HTTP status or the human message. Codes are part of the compatibility promise
  (see [Versioning](/reference/versioning)); new codes may be added, existing
  ones will not change meaning within `/v1`.
- **`message`** — a human-readable explanation. For logs and developers, not for
  branching. The wording may change at any time.
- **`requestId`** — the same value returned in the `X-Request-Id` response
  header. Quote it when you ask us to look into a request.
- **`requiredScope`** — present **only** on `insufficient_scope`. It names the
  exact scope your key is missing, so you can request a key that has it.

## The `X-Request-Id` header

Every response — success or error — carries an `X-Request-Id`. If you send your
own `X-Request-Id` on the request, we echo it back; otherwise the gateway
generates one (`req_` + hex). Log it on your side and you can correlate any call
with our logs.

## Codes and their HTTP status

| HTTP | `code` | When it happens | What to do |
|---|---|---|---|
| `400` | `invalid_request` | Malformed input: a bad `cursor`, a non-numeric `limit`, a body that doesn't parse. | Fix the request. Don't retry unchanged. |
| `401` | `invalid_key` | No key sent, or the key is unknown, revoked, or expired. | Check the `Authorization: Bearer sk_live_…` (or `X-API-Key`) header; mint a new key if needed. |
| `402` | `subscription_required` | The account behind the key has no active subscription for what the route does (creating a source, for example). | Not fixable in code; the account needs a plan. |
| `403` | `insufficient_scope` | The key is valid but lacks the scope for this route. `requiredScope` names it. | Issue a key that holds the named scope. |
| `404` | `not_found` | The studio (or sub-resource) doesn't exist, or your account can't see it. | Verify the id. A resource you don't own reads as not-found. |
| `429` | `rate_limited` | You exceeded the per-key rate limit. | Back off for the `Retry-After` seconds, then retry. See [Rate limits](/reference/rate-limits). |
| `503` | `write_disabled` | A write endpoint (`go-live` / `go-offline`) is currently gated off. | Not retryable by you; the write surface is disabled in this preview. |
| `503` | `unavailable` | A dependency needed to serve the request is temporarily down (e.g. key verification). | Transient — retry with backoff. |
| `502` | `bad_gateway` | An upstream service returned an unexpected error. | Transient — retry with backoff. |
| `500` | `internal` | An unexpected error on our side. | Retry with backoff; if it persists, send us the `requestId`. |

## How to handle errors

1. **Read `error.code`, not the HTTP status alone.** Two different `503`s
   (`write_disabled` vs `unavailable`) mean very different things — one is a
   deliberate gate, the other is transient.
2. **Retry only the transient codes** (`unavailable`, `bad_gateway`, `internal`,
   and `rate_limited` after its `Retry-After`). Use exponential backoff. Never
   hot-loop a retry.
3. **Never retry a `4xx` unchanged** — `invalid_request`, `invalid_key`,
   `insufficient_scope`, and `not_found` will fail identically until you change
   the request or the key.
4. **Surface `requestId` in your own error reports.** It's the fastest way for
   us to trace a failing call.

## Auth errors specifically

- A **401 `invalid_key`** means the credential itself is the problem (missing,
  unknown, revoked, expired). Re-check the header and the key.
- A **403 `insufficient_scope`** means the credential is fine but under-scoped.
  `requiredScope` tells you what to add. A key can only ever act within its
  owner's own account, so a 404 rather than a 403 can also mean "not yours".

See the full request/response shapes in the
[**API reference**](/reference/api/v1) and the credential model in
[**Authentication**](/reference/authentication).


<!-- reference/pagination -->


# Pagination

Every list endpoint on `/v1` (studios, sources, destinations) returns a page in
one shape:

```json
{
  "data": [ { "id": "…" }, { "id": "…" } ],
  "nextCursor": "c3R1ZGlvXzQy"
}
```

- **`data`** — the items on this page, ordered by `id` ascending.
- **`nextCursor`** — an opaque cursor for the next page. It is **omitted when
  there are no more pages**, so "the response has no `nextCursor`" is your
  end-of-list signal.

## Paging through a full list

Pass the `nextCursor` from one response as the `cursor` query parameter on the
next request. Repeat until a response comes back without a `nextCursor`.

```bash
# Page 1
curl -sS "https://api-dev.traxstreaming.live/v1/studios?limit=50" \
  -H "Authorization: Bearer sk_live_…"

# Page 2 — feed back the nextCursor you just received
curl -sS "https://api-dev.traxstreaming.live/v1/studios?limit=50&cursor=c3R1ZGlvXzQy" \
  -H "Authorization: Bearer sk_live_…"
```

A loop, in pseudocode:

```
cursor = null
loop:
  page = GET /v1/studios?limit=100  (+ &cursor=<cursor> if set)
  process(page.data)
  if page.nextCursor is absent: break
  cursor = page.nextCursor
```

## Parameters

| Query param | Type | Default | Notes |
|---|---|---|---|
| `limit` | integer | `50` | Items per page. Values above the maximum are **clamped** to it, not rejected. A non-numeric or `< 1` value is a `400 invalid_request`. |
| `cursor` | string | — | An opaque cursor from a prior response's `nextCursor`. An empty/absent cursor starts at the beginning. A malformed cursor is a `400 invalid_request` (never a 500). |

The maximum `limit` is **200**. Ask for more and you get 200.

## Why cursors, not page numbers

The API uses **keyset (cursor) pagination** keyed on the resource `id`, not
offset/`page=N` pagination. Cursors are **stable under inserts and deletes**: if
a new studio is created while you're paging, an offset would silently skip or
repeat a row, whereas a keyset cursor keeps advancing past the last id you saw.

Treat the cursor as **opaque** — it's a base64url token whose contents are an
implementation detail. Don't parse it, construct it, or persist it long-term;
just echo back the `nextCursor` you were given.

See the per-endpoint parameters in the [API reference](/reference/api/v1).


<!-- reference/rate-limits -->


# Rate limits

`/v1` is rate-limited **per API key** with a token-bucket limiter. Each key gets
its own independent bucket, so one key hitting its limit never throttles
another key — including other keys on your own account.

## How the bucket works

- The bucket holds up to a **burst** of tokens and refills at a steady
  **sustained rate** (tokens per second).
- Each request spends one token. If a token is available, the request proceeds.
- If the bucket is empty, the request is rejected with **`429 rate_limited`**
  and a **`Retry-After`** header (in seconds) telling you how long until a token
  refills.

This means you can burst up to the bucket size after an idle period, then settle
into the sustained rate. In the dev preview the default is a burst on the order
of a minute's worth of sustained calls; treat the exact numbers as subject to
change and **drive your client off the `Retry-After` header**, not a hardcoded
figure.

## Handling a 429

```json
// HTTP 429, header: Retry-After: 3
{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded; retry after the Retry-After interval",
    "requestId": "req_…"
  }
}
```

1. Read the **`Retry-After`** response header (seconds).
2. Wait at least that long.
3. Retry the request.
4. If you're making many calls, add jitter and exponential backoff so a fleet of
   clients doesn't retry in lockstep.

```
resp = call()
if resp.status == 429:
  wait(seconds = resp.header("Retry-After") + jitter)
  retry with exponential backoff
```

## Staying under the limit

- **Cache reads.** Studio/source/destination lists change slowly; don't poll
  them in a tight loop.
- **Page with a large `limit`.** Fetch up to 200 items per request instead of
  many small pages (see [Pagination](/reference/pagination)).
- **Use one key per integration.** Because buckets are per-key, splitting
  distinct workloads across distinct keys keeps one busy job from starving
  another — and makes it easy to revoke just one.
- **Back off on 429, don't hammer.** A client that ignores `Retry-After` and
  retries immediately just stays rate-limited.

Limits and tiers will be documented here as they firm up. For now, build against
the `429 + Retry-After` contract and you'll be forward-compatible.


<!-- reference/versioning -->


# Versioning & compatibility

The Developer API is **versioned in the path**: everything lives under `/v1`.
That prefix is a contract, not a build number — it's decoupled from the web
studio's internal backend, so the API doesn't move under you when the app
changes.

## The compatibility promise

**Within a major version (`/v1`), changes are additive and backward-compatible.**
We may, without a new version:

- add new endpoints;
- add new **optional** request parameters;
- add new fields to a response object;
- add new `error.code` values;
- add new enum values to an existing field.

We will **not**, within `/v1`:

- remove or rename an endpoint, field, or `error.code`;
- change the type or meaning of an existing field;
- make a previously optional request parameter required;
- change the meaning of an existing `error.code`.

## Write your client to tolerate additions

Because additive changes ship within `/v1`, a well-behaved client:

- **ignores unknown response fields** rather than failing to parse them;
- **treats `error.code` as an open set** — branch on the codes you know, and
  have a sensible default for a code you don't recognize;
- **doesn't depend on field ordering** or on the absence of a field;
- pins to `/v1` in its base URL and lets new fields arrive for free.

If you generate a typed client from the OpenAPI spec (see the SDK quickstarts),
regenerate it periodically to pick up new fields — but an old generated client
keeps working against `/v1`.

## Breaking changes → a new major version

A change that would break existing callers only ships under a **new path
version** (`/v2`), never inside `/v1`. When that happens, `/v1` and `/v2` run
**side by side for an overlap window** so you can migrate deliberately. We'll
announce deprecations with lead time; `/v1` won't disappear out from under you.

## Environments

| Environment | Base URL | Status |
|---|---|---|
| Development | `https://api-dev.traxstreaming.live/v1` | **Live now** (read endpoints; writes gated — see [Roadmap](/reference/roadmap)) |
| Production | `https://api.traxstreaming.live/v1` | Planned once the surface is stable |

Only the **host** changes between environments — the `/v1` contract is identical.
Build against `/v1` on dev today and you'll move to production by swapping the
hostname.

The machine-readable spec at
[`/v1/openapi.json`](https://api-dev.traxstreaming.live/v1/openapi.json) carries
its own `info.version` (semver), which tracks additive revisions within `/v1`.
The **path** version (`/v1`) is the compatibility boundary; the spec's
`info.version` just tells you how recent the document is.


<!-- reference/webhooks -->


# Webhooks

> **Status: planned — not available yet.** Webhooks are on the `/v1` roadmap but
> are **not implemented in the current dev preview**. There is no endpoint to
> register a webhook today, and no events are delivered. This page describes the
> **intended** design so you can plan for it; the shapes below may change before
> it ships. Until then, poll [`GET /v1/studios/{id}/stream-status`](/reference/api/v1)
> for live/offline state. See the [Roadmap](/reference/roadmap) for phasing.

## What webhooks will do

Instead of polling stream status, you'll register an HTTPS URL and receive a
signed `POST` when something happens — starting with a studio going live or
offline. This is the standard "don't poll, get pushed" pattern for stream-event
integrations (go-live alerts, auto-posting, dashboards).

## Planned event catalog

The first events map to the lifecycle the API already exposes as reads:

| Event | Fires when | Phase |
|---|---|---|
| `stream.live` | A studio goes live | Phase 1 (with the write API) |
| `stream.offline` | A studio goes offline | Phase 1 (with the write API) |
| `source.status_changed` | A source's status changes | Phase 2 |
| `destination.status_changed` | A destination's status changes | Phase 2 |
| `chat.message` | A chat message is received | Phase 3 |

## Planned delivery contract

When it ships, expect the platform's usual webhook discipline:

- **Signed payloads.** Each delivery carries an HMAC signature header so you can
  verify it came from TRaX and wasn't tampered with. Verify the signature before
  trusting the body.
- **Delivery with retry.** Failed deliveries are retried with backoff; your
  endpoint should be idempotent and return `2xx` quickly.
- **Registration + management.** Register, list, and delete webhook
  subscriptions through the API, gated by a `webhooks:manage` scope. The scope
  vocabulary already lists `webhooks:manage` so keys you mint now stay valid when
  this lands.
- **At-least-once semantics.** Deduplicate on a delivery id; design your handler
  to tolerate the same event arriving more than once.

## Until then: poll stream-status

The live/offline signal is available today as a read:

```bash
curl -sS "https://api-dev.traxstreaming.live/v1/studios/<id>/stream-status" \
  -H "Authorization: Bearer sk_live_…"
# { "live": true, "encoderStreamId": "…", "liveStartedAt": "…", "mode": "cloud" }
```

Poll it on a sensible interval (respecting [rate limits](/reference/rate-limits))
and you have the same live/offline signal webhooks will push later — swapping to
webhooks when they ship is then a small change.

Tell us if webhooks are what you need next — demand shapes the order things ship.


<!-- reference/embed-chat -->


# Embed chat reference

The contract behind [Put TRaX chat on your own site](/guides/embed-chat): the
token exchange, the viewer socket, the headless SDK, and the parts that are
deliberately uneven.

> **Availability.** `POST /v1/viewer-tokens` and the viewer chat socket are live
> in production. The `embed.js` bundle is not yet published at a public URL —
> TRaX gives you the script URL when your account is switched on for the embed.
> The contract below is stable either way.

## The trust model

TRaX has no account for the person reading chat on your site, and does not want
one. Your backend authenticates its own member, decides what that member may do,
and exchanges that decision for a credential.

| | Where it lives | What it proves |
|---|---|---|
| `sk_live_…` API key | Your server, only ever | You are you, and you may mint viewer tokens |
| Viewer token | The member's browser | One studio, one opaque member, a fixed capability list, minutes of life |

The viewer token is a signed JWT (ES256, `iss: trax-studio-api`,
`aud: trax-viewer`). Treat it as opaque — it is verified server-side and its
internal shape is not part of this contract.

**`memberRef` is opaque to TRaX.** It is stored on the token, used as a
rate-limit and block key, and never resolved to a person. TRaX holds nothing
else about your member.

**Revocation is expiry.** There is no revoke call, and that is deliberate: the
mechanism is that your server stops vouching and the current token runs out. It
is why the lifetime ceiling is an hour and not a day.

## `POST /v1/viewer-tokens`

Also rendered from the machine-readable spec at
[`/reference/api/v1`](/reference/api/v1), and served live at
[`api.traxstreaming.live/v1/openapi.json`](https://api.traxstreaming.live/v1/openapi.json).

**Call this from your server.** It is authenticated with your secret key.

```
POST https://api.traxstreaming.live/v1/viewer-tokens
Authorization: Bearer sk_live_…
Content-Type: application/json
```

Required scope: **`viewer:tokens`**. It is opt-in and implied by nothing —
an integration that only reads studios can never acquire it by accident.

### Request

| Field | Type | Required | Notes |
|---|---|---|---|
| `studioId` | string | yes | The studio whose chat this token may reach. |
| `caps` | string[] | yes | At least one of `chat.read`, `chat.send`, `video.play`. Unknown values are rejected, not ignored. Duplicates are collapsed. Max 8. |
| `memberRef` | string | with any write cap | Your opaque id for the person. Max 128 characters. Required whenever `caps` contains `chat.send`. |
| `displayName` | string | with `chat.send` | The name **published** alongside a relayed message. Max 32 characters after cleaning. Not collected for read-only viewers. |
| `ttlSeconds` | integer | no | Default 900. **Clamped to 3600.** |

### Response — `201 Created`

```json
{
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "expiresAt": "2026-08-21T02:14:07Z",
  "caps": ["chat.read", "chat.send"]
}
```

| Field | Notes |
|---|---|
| `token` | Hand this to the browser. Nothing else from your server. |
| `expiresAt` | RFC 3339, **after clamping**. Schedule your next mint from this value, never from the `ttlSeconds` you asked for. |
| `caps` | The capabilities actually **granted**. May be narrower than requested. Render your interface from this. |

### Errors

The standard `/v1` envelope — see [Errors](/reference/errors).

```json
{ "error": { "code": "insufficient_scope", "message": "…", "requestId": "…", "requiredScope": "viewer:tokens" } }
```

| Status | `code` | Means |
|---|---|---|
| 401 | `invalid_key` | No credential, or a key that does not resolve. |
| 403 | `insufficient_scope` | The key lacks `viewer:tokens`. `requiredScope` names it. |
| 404 | `not_found` | No such studio, **or** the studio is not yours. Deliberately the same answer, so the endpoint cannot be used to probe for other tenants' studio ids. |
| 400 | `invalid_request` | The request violates a mint rule — see below. |
| 429 | `rate_limited` | See [Rate limits](/reference/rate-limits). |
| 503 | `write_disabled` / `unavailable` | Writes are off on this deployment, or the studio service is down. |
| 502 | `bad_gateway` | Upstream fault. |

**Two sharp edges in the error mapping, stated plainly because they will cost
you time otherwise:**

- A `400 invalid_request` carries the generic message *"the request was rejected
  as invalid"*. The specific reason is determined upstream and is **not** passed
  through. When you get one, work down this list — it is the complete set of
  mint rules:
  - `caps` is empty, or names something outside `chat.read` / `chat.send` /
    `video.play`, or has more than 8 entries;
  - `caps` contains `chat.send` and `memberRef` is empty;
  - `caps` contains `chat.send` and `displayName` is empty (or cleans to
    empty — it is stripped of colons, brackets, parentheses and control
    characters before it is measured);
  - `memberRef` is longer than 128 characters.
- A viewer the broadcaster has **blocked** who asks for `chat.send` **and
  nothing else** gets a **`404 not_found`**, not a 403. Ask for
  `["chat.read", "chat.send"]` rather than `["chat.send"]` and you get the far
  better behaviour instead: a 201 whose `caps` comes back as `["chat.read"]`,
  and a widget that simply renders without a composer.

### Capabilities

| Capability | Grants |
|---|---|
| `chat.read` | Open the viewer chat socket, receive live messages and backfill. Required to connect at all. |
| `chat.send` | Submit messages that are relayed to the broadcaster's connected platforms. Requires `memberRef` **and** `displayName`. |
| `video.play` | Reserved for the playback plane. **Not available** — the delivery tier is a later phase. Requesting it today mints a capability nothing consumes. |

Capability is checked at three points, not one: at mint, at socket connect, and
live on an open socket. A signature proves *who*; it never proves *still
welcome*.

## The viewer chat socket

```
wss://<embed-host>/api/v1/embed/ws/studios/{studioId}/chat?token=<viewerToken>
```

The token rides in the query string because the browser WebSocket API cannot set
headers. It is verified **before** the upgrade, and the `studio` claim is matched
against the id in the path — a token minted for one studio cannot read another.

Refused before the upgrade:

| Status | Body | Cause |
|---|---|---|
| 400 | `missing studio id` | Malformed path. |
| 401 | `token required` | No `token` parameter. |
| 401 | `invalid_token` | Bad signature, expired, wrong issuer/audience/scope, or the studio claim does not match the path. |
| 403 | `insufficient_capability` | The token has no `chat.read`. |
| 503 | `realtime bus unavailable` | Server-side. |

Origin is deliberately **not** checked. The whole point is that the page is on a
domain TRaX does not know in advance; the token is the authorization, and an
origin check could only ever have been advisory.

The server sends a `ping` frame every 15 s and expects the connection to answer
`{"type":"pong"}`. It closes a connection that sends nothing for 45 s. Inbound
frames are capped at 64 KB.

### Envelope

Every frame in both directions:

```json
{ "type": "…", "requestId": "…", "ok": true, "data": { }, "result": { }, "error": "…" }
```

`requestId` is yours to choose on a request; the reply echoes it. `ok`,
`result` and `error` appear only on `type: "reply"`.

### Server → client

| `type` | `data` | Meaning |
|---|---|---|
| `hello` | `{ studioId, caps, canSend }` | First frame. The capabilities the **server** granted. Build your UI from this, not from what you requested. |
| `chat_message` | a message (below) | A live message from any connected platform, or from the studio itself. |
| `chat_send_result` | `{ clientMessageId, results: [{ platform, ok, reason? }] }` | What the platforms actually did with a message **this connection** submitted. Filtered per-connection — you never see other viewers' outcomes. |
| `caps_changed` | `{ canSend, reason }` | The broadcaster blocked or unblocked this viewer mid-session. `reason` is `"blocked"` on a block, empty on a restore. |
| `chat_message_removed` | a removal (below) | A message, or a person's history, must stop being displayed. |
| `ping` | — | Answer `{"type":"pong"}`. |
| `reply` | — | The answer to one of your requests. |

An unblock restores only what the token already granted. The blocklist can
subtract capability; it can never add it.

### Client → server

Anything else is ignored. This socket performs no other mutation.

**`chat_history`** — backfill.

```json
{ "type": "chat_history", "requestId": "r1", "data": { "limit": 50 } }
```

Replies `{ type: "reply", requestId: "r1", ok: true, result: { messages: [...] } }`.
**Newest first** — that is what "the last 50 messages" means to a database.
Reverse it before rendering, or use the SDK, which sorts by timestamp.

**`chat_send`** — relay a message outward.

```json
{ "type": "chat_send", "requestId": "r2", "data": { "text": "hello" } }
```

A send without a `requestId` is refused rather than performed: the outcome is
the point, and a caller who has not asked to hear it cannot be told their
message was throttled or dropped.

On acceptance the reply is
`{ ok: true, result: { status: "queued", clientMessageId: "…" } }`. **`queued`
is not `sent`** — the platforms have not answered yet. Wait for the
`chat_send_result` carrying that `clientMessageId`.

Refusals arrive as `{ ok: false, error: "<code>" }`:

| `error` | Meaning | Whose fault |
|---|---|---|
| `too_fast` | This viewer is over their own rate limit. | The sender's. Nudge, don't scold. |
| `room_busy` | The whole embed audience is at the studio ceiling. | Nobody's. Do **not** tell this person to slow down. |
| `rate_limited` | Too many RPCs on this connection (any type). | The client's. |
| `message_too_long` | Does not fit the platform budget once attributed. | The sender's. |
| `empty_message` | Nothing left after cleaning. | The sender's. |
| `chat_send_not_granted` | No `chat.send`, or it was revoked mid-session. | — |
| `relay_unavailable` | The relay could not accept it. | Ours. |
| `no_display_name` | Token carries `chat.send` with no attested name. Should be impossible; reachable only with a token from an older build. | — |

Rate limits, all token buckets:

| Bucket | Sustained | Burst |
|---|---|---|
| RPCs per connection (any type) | 1 per 2 s | 20 |
| Relays per viewer | 1 per 4 s | 3 |
| Relays per **studio**, across every embed connection | 1 per 6 s | 5 |

The studio ceiling exists because every relayed message is an API call against
the *broadcaster's* platform account, under *their* limits. A thousand
well-behaved viewers still add up to a flood, and an embed that consumed the
whole quota would silence the person who owns the account.

### Message shape

Both `chat_message` and each row of `chat_history` carry the same shape. The
author is **nested**:

```json
{
  "id": "…",
  "platform": "twitch",
  "platformMessageId": "…",
  "author": { "id": "…", "displayName": "Ada" },
  "text": "…",
  "timestamp": "2026-08-21T01:12:33Z"
}
```

- `platform` is the originating service — `twitch`, `youtube`, `kick` — or
  `studio` for a message said in the broadcast itself: the broadcaster typing in
  their chat panel, and every embed visitor's own message coming back.
  **`studio` is not a platform**; do not render it as a platform badge.
- `author.displayName` may be absent. Render no name rather than a placeholder.
- History rows carry some additional internal bookkeeping fields. They are not
  part of this contract; ignore anything not listed above.

## Inbound moderation

A moderator took something down; every surface showing it has to follow,
including yours.

`chat_message_removed` payload:

```json
{ "platform": "twitch", "platformMessageId": "…", "authorId": "…", "channelWide": false, "reason": "deleted" }
```

`reason` is a closed set: `deleted`, `banned`, `timeout`, `cleared`.

### The matching rule

Getting this wrong is the whole risk: too narrow and moderated content stays up;
too broad and a removal wipes the wrong messages, which from a viewer's seat is
indistinguishable from the chat breaking. Use `shouldRemove` from the SDK rather
than reimplementing it. What it does:

1. **Platform must match, always.** Ids are unique only within a platform, and
   two platforms hand out the same-looking ids. Matching across them would
   delete a stranger's messages on a different service.
2. `channelWide: true` removes everything from that platform, and only that
   platform.
3. Otherwise, if `platformMessageId` is set, remove the message with that id.
4. Otherwise, if `authorId` is set, remove **every** message from that author —
   which is what a ban or timeout does on the platforms themselves. A message
   with no author id never matches, so an empty-against-empty comparison cannot
   wipe every anonymous sender.
5. Anything else is refused rather than guessed. "Delete nothing" and "delete
   everything" are the alternatives, and only one of them is recoverable.

If your log de-duplicates by message id, drop removed ids from that set too —
otherwise a reconnect that replays backfill is silently swallowed and the
removal turns permanent for the wrong reason.

### Platform coverage — uneven on purpose

| Platform | A single message deleted natively | A ban or timeout | A room clear |
|---|---|---|---|
| Twitch | yes (`CLEARMSG`) | yes (`CLEARCHAT`) | yes |
| YouTube | yes (`messageDeletedEvent`) | yes (`userBannedEvent`) | — |
| Kick | **no — see below** | yes (`moderation.banned`; a timeout too) | — |
| Anything else | no moderation events on the wire | no | no |

Moderation performed **through TRaX** reflects on every platform, including
Kick — a broadcaster deleting a Kick message in the TRaX UI does see it
disappear from your embed.

**The Kick gap.** A single message deleted natively on kick.com is not covered
and cannot be. Kick's event-type catalogue publishes no message-deletion event —
there is nothing to subscribe to. This was verified against Kick's published
event types on 2026-08-20. It is the one remaining hole in the matrix, and it is
theirs, not a setting you can turn on.

## Headless SDK

The same bundle exports a DOM-free client for building your own interface.

```js
import { TraxChatClient, shouldRemove } from 'https://play.traxstreaming.live/embed.js'

const client = new TraxChatClient({
  host: 'https://play.traxstreaming.live',
  studioId: 'YOUR-STUDIO-ID',
  auth: async () => (await fetch('/my/viewer-token', { method: 'POST' })).json(),
  onMessage: (m) => renderMessage(m),
  onState: (state, caps) => setComposerVisible(caps.includes('chat.send')),
  onRemoval: (rm) => {
    for (const m of myLog) if (shouldRemove(m, rm)) removeFromLog(m)
  },
  onError: (err) => console.warn(err),
})

await client.connect()                      // resolves once the server has said hello
for (const m of await client.history()) renderMessage(m)   // oldest first
const outcome = await client.send('hello')  // resolves on real delivery
```

### Options

| Option | Notes |
|---|---|
| `host` | Origin of the embed plane. |
| `studioId` | Required. |
| `auth` | `() => Promise<{ token, expiresAt, caps }>`. Called on connect **and** again before each expiry. |
| `onMessage` | One live message. |
| `onState` | `(state, caps)` — fires on connection **and** capability changes. |
| `onRemoval` | A removal to apply. |
| `onError` | Transport or auth failure. The client keeps retrying. |

### Methods and properties

| Member | Notes |
|---|---|
| `connect()` | Opens the socket **and waits for the server hello**. Resolves on timeout rather than throwing — a refused connection has already scheduled its own retry. |
| `history(limit = 50)` | Backfill, sorted oldest-first. Returns `[]` if the socket is not live. |
| `send(text)` | Resolves with a `SendOutcome` (below). |
| `close()` | Tears down and stops reconnecting. |
| `caps` / `canSend` | What the server granted, live. |
| `capsReason` | `"blocked"` when capability was last narrowed by a block; empty otherwise. Use it to explain a composer that disappeared. |
| `state` | `connecting` \| `live` \| `reconnecting` \| `closed`. |

Also exported: `shouldRemove`, `normalizeMessage`, `oldestFirst`,
`msUntilRefresh`, `backoffMs`, and the `REFRESH_LEAD_MS` / `MIN_REFRESH_MS` /
`DELIVERY_TIMEOUT_MS` / `CONNECT_TIMEOUT_MS` constants.

### Send outcomes

`send()` never resolves to a bare boolean. A sender who believes a message was
delivered when it never left is the worst failure this feature has.

| `status` | Fields | Meaning |
|---|---|---|
| `relayed` | `platforms: string[]` | It reached at least these platforms. |
| `local-only` | `reason: 'rate-limited' \| 'room-busy' \| 'no-platforms'` | The visitor sees their words in the embed; nothing left. Nothing went wrong, and nothing was delivered. |
| `rejected` | `reason: string` | Refused before it left. |
| `failed` | `reason: string` | Went out and was refused, or we never learned what happened. |

A delivery wait that times out (20 s) resolves to **`failed`**, not to success.
The message may well have landed — but we do not know, and "probably delivered"
rendered as delivered is how a sender ends up certain of something false. The
same applies to a socket that drops with a send in flight.

`no-platforms` means the broadcaster currently has no chat destinations
connected. It is not an error.

### Reconnection and refresh

- Reconnect backoff is exponential to 30 s, with jitter so a server restart does
  not bring every embedded page back in the same millisecond.
- The token is re-minted 60 s before expiry, never closer than 5 s apart, using
  the server's `expiresAt`.
- Every refresh calls **your** `auth` endpoint again. That is the revocation
  path: stop vouching and the next refresh fails.

## `<trax-chat>` element

| | |
|---|---|
| Attribute `studio` | **Required.** The studio id. Read once at start; changing it later has no effect. |
| Attribute `host` | Optional. Defaults to the production embed plane. |
| Property `.auth` | **Required.** The auth callback. Assigning it starts the element, at any time. Never an attribute — that would put a credential in your markup. |
| Property `.resolvedHost` | The plane it actually connected to. |
| Event `trax-state` | `detail: { state, caps, host }`. Fires on connection and capability changes. |

CSS custom properties: `--trax-font`, `--trax-size`, `--trax-fg`, `--trax-bg`,
`--trax-rule`, `--trax-muted`, `--trax-accent`, `--trax-accent-fg`,
`--trax-platform-bg`, `--trax-platform-fg`, `--trax-warn`.

The element renders in a shadow root and writes message text with
`textContent`, never `innerHTML` — chat is attacker-controlled by definition and
this runs inside your page.

## Limits and caveats

**Relayed messages leave on the broadcaster's platform account.** There is no
per-visitor platform identity and there cannot be one — a Twitch relay is a
`PRIVMSG` over the broadcaster's own connection. Every relayed line therefore
carries `Name (web): `. It is not configurable. Read
[the guide's step 4](/guides/embed-chat#step-4-letting-your-visitors-post-read-this-part-twice)
before enabling the write path; there are platform-terms consequences and they
are the broadcaster's to accept.

**The origin tag is `web`, not your domain.** TRaX does not reliably know which
page a socket was opened from, and a tag that is right most of the time is worse
than one that claims nothing it cannot back up.

**Messages are composed to the tightest platform budget** — 200 characters,
YouTube's — minus the prefix, so a message is whole on every platform or refused
before it leaves. Nothing is truncated on one service and complete on another.

**`displayName` is public.** It goes to the broadcaster's platform audience. It
is server-attested from your backend, so a visitor cannot choose it, but pick
the field accordingly.

**Token TTL: 15 minutes default, 1 hour maximum.** On expiry the client
re-mints through your callback. If your endpoint refuses, the socket closes and
retries with backoff — the viewer sees `reconnecting`, then `closed`.

**A viewer token cannot** read a different studio, post without `chat.send`,
outlive an hour, moderate anything, or play video. `video.play` exists in the
vocabulary but has no consumer yet.

**Kick single-message deletes done on kick.com do not reflect.** See
[platform coverage](#platform-coverage-uneven-on-purpose).

**Video is not part of this.** Playback on the same viewer token is a separate
phase and is not available.


<!-- reference/roadmap -->


# Roadmap & status

What's live on the development edge today versus what's planned. We label this
honestly so you never build against something that isn't there yet. "Live (dev)"
means reachable now at `https://api-dev.traxstreaming.live`; "Planned" means
designed but not shipped.

## Live now (dev)

| Capability | Where |
|---|---|
| **API keys** — create, copy-once, list, revoke (self-serve from your account's Developer / API Keys screen) | [Developer API](/reference/public-api) |
| **Read endpoints** — list studios, sources, destinations; read stream-status | [API reference](/reference/api/v1) |
| **Studio / source / destination CRUD** (Phase 2) — create, update, delete (write-gated) | [API reference](/reference/api/v1) |
| **Connections** (Phase 2) — list + unlink linked platform accounts | [API reference](/reference/api/v1) |
| **Chat** (Phase 3) — read recent messages + send (write-gated) | [API reference](/reference/api/v1) |
| **Media library** (Phase 3) — list assets + initiate uploads (write-gated) | [API reference](/reference/api/v1) |
| **`go-live` / `go-offline`** (Phase 1) — take a studio live / offline (write-gated) | [API reference](/reference/api/v1) |
| **Error envelope** — `{ error: { code, message, requestId } }`, stable codes | [Errors](/reference/errors) |
| **Cursor pagination** — `{ data, nextCursor }` | [Pagination](/reference/pagination) |
| **Per-key rate limits** — token bucket, `429 + Retry-After` | [Rate limits](/reference/rate-limits) |
| **Versioned `/v1` contract** — additive-within-major | [Versioning](/reference/versioning) |
| **OpenAPI 3.0 spec** — served live for codegen | [`/v1/openapi.json`](https://api-dev.traxstreaming.live/v1/openapi.json) |
| **Media ingest plane** — SRT / RTMP(S) / WHIP / WHEP with session tokens (operator-provisioned) | [SRT](/reference/srt-streamid) · [RTMP](/reference/rtmp) · [WHIP/WHEP](/reference/whip-whep) |
| **BYO storage** (studio) — connect your own S3-compatible bucket as a media library; **cloud recording** into it | [BYO storage](/guides/byo-storage-setup) · [Cloud recording](/guides/cloud-recording) |

## Write flag

Every mutating (write) endpoint across Phases 1–3 is gated behind the
deployment's `PUBLIC_API_WRITE_ENABLED` flag. While it is off, writes return
`503 write_disabled` and never touch the live stream path; the flag flips on
per-deployment after off-air validation. Reads are always on.

## Shipped phases

| Phase | Status | Adds |
|---|---|---|
| **Phase 1** | ✅ Live (dev) | Reads; `go-live` / `go-offline` writes |
| **Phase 2** | ✅ Live (dev) | Write CRUD for **studios / sources / destinations**; **connections** (list / unlink platform accounts) |
| **Phase 3** | ✅ Live (dev) | **Chat** — read + send; **media** — library list + initiate upload |

## Planned

Roughly in the order we expect to ship. Nothing here is available yet.

| Phase | Adds |
|---|---|
| **Phase 4** | **OAuth client apps** — a third-party app a *different* TRaX user logs into, acting on their behalf (authorization-code + PKCE) |
| **Phase 5** | Official **SDKs** (TypeScript, then Go) and a self-serve developer portal (usage dashboards, key rotation) |
| **Webhooks** | Signed `stream.live` / `stream.offline` / `source.status_changed` / `destination.status_changed` events (poll stream-status until they ship) |
| **Later** | **MoQ** low-latency playback (use WHEP today) |

## Scopes ship ahead of features on purpose

The [scope vocabulary](/reference/public-api#scopes) covers everything through
Phase 3 (`studios/sources/destinations/connections/chat/media` read + write,
`stream:*`). `webhooks:manage` is listed ahead of its feature on purpose —
request keys with the scopes you'll want and they stay valid as those land, so
you don't have to re-mint keys later.

Have an opinion on what should ship first? Tell us — the order follows what
developers actually want to build.