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-dev.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.3.0).

The versioned public developer API for TRaX. Authenticate with a user-scoped API key: Authorization: Bearer sk_live_... (or the X-API-Key alias). 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 + media library (Phase 3). 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-dev.traxstreaming.live — every path below is absolute (e.g. GET /v1/studios).
• Authentication: Authorization: Bearer sk_live_... (or the X-API-Key header). The meta endpoints (/v1/health, /v1/openapi.json) need no auth.
• Errors: one envelope, { "error": { "code", "message", "requestId" } } — see Errors & status codes.
• Lists: cursor-paginated, { "data": [ … ], "nextCursor": "…" } — see Pagination.
• Rate limits: per-key token bucket, 429 + Retry-After — see 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}/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}/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.

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

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

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.

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

media

Media library assets + uploads

GET /v1/media

List the caller's media-library assets.

Requires scope media: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 media assets.	MediaAssetList
default	Error envelope.	Error

POST /v1/media

Initiate a media upload (returns a presigned PUT).

Requires scope media:write. Gated behind PUBLIC_API_WRITE_ENABLED. Reserves an asset row and returns a short-lived presigned PUT URL; upload the bytes to it, then the asset transitions to READY once processed.

Auth: API key required.

Responses:

Status	Description	Body
201	An upload was initiated.	MediaUpload
default	Error envelope.	Error

Schemas

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	—

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	—

CreateDestinationRequest

Field	Type	Required	Description
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	—

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	—
name	string	yes	—
type	string	yes	webcam | rtmp | srt | webrtc-input | media | ...
url	string	no	—

CreateStudioRequest

Field	Type	Required	Description
name	string	yes	—

Destination

Field	Type	Required	Description
enabled	boolean	yes	—
id	string	yes	—
name	string	yes	—
platform	string	yes	—
status	string	no	—
studioId	string	yes	—
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.

MediaAsset

Field	Type	Required	Description
byteSize	integer	yes	—
contentType	string	no	—
createdAt	string	no	—
filename	string	yes	—
folder	string	no	—
id	string	yes	—
kind	string	yes	video | image | audio
status	string	yes	UPLOADING | READY | FAILED

MediaAssetList

Field	Type	Required	Description
data	MediaAsset[]	yes	—
nextCursor	string	no	—

MediaUpload

Field	Type	Required	Description
assetId	string	yes	—
kind	string	yes	—
objectKey	string	yes	—
uploadUrl	string	yes	A short-lived presigned PUT URL to upload the bytes to.

Ok

Field	Type	Required	Description
ok	boolean	yes	—

SendChatMessageRequest

Field	Type	Required	Description
platforms	string[]	no	Subset to fan out to; empty = every enabled platform.
text	string	yes	—

Source

Field	Type	Required	Description
active	boolean	yes	—
createdAt	string	no	—
id	string	yes	—
name	string	yes	—
status	string	no	—
studioId	string	yes	—
type	string	yes	—

SourceList

Field	Type	Required	Description
data	Source[]	yes	—
nextCursor	string	no	—

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

StudioList

Field	Type	Required	Description
data	Studio[]	yes	—
nextCursor	string	no	—

UpdateDestinationRequest

Field	Type	Required	Description
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	—

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	—