TRaX Docs
reference

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.

Base URL

https://api-dev.traxstreaming.live/v1

Every response carries an X-Request-Id. Errors share one envelope:

{ "error": { "code": "…", "message": "…", "requestId": "…" } }

List endpoints are cursor-paginated: { "data": [ … ], "nextCursor": "…" } (pass ?cursor=…&limit=… to page).

Authenticating — 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:

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:

curl -sS "https://api-dev.traxstreaming.live/v1/studios" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

The meta endpoints (/v1/health, /v1/openapi.json) need no auth. Every other route requires a key with the matching scope: a 401 means the key is missing / unknown / revoked / expired; a 403 names the scope you're missing.

Building a first-party mobile or desktop app that logs a user in? You'll usually authenticate as the user with OAuth (PKCE), not a shared API key — see Build a client for when to use which, and how the WebSocket + WebRTC surfaces fit in.

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
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
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}/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
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
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 — 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

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:

# 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 · Swift (iOS) · Kotlin (Android). For a browsable, endpoint-by-endpoint rendering of the spec, see the API reference (/v1).

Cross-cutting contract

These behaviors are identical on every /v1 endpoint — read them once:

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 for the full transport map and how to authenticate each one.

Tell us what you want to build — it shapes what ships first.