TRaX Docs
reference

TRaX Edge: live inputs, playback ids, signing keys, webhooks, usage

TRaX Edge is the media CDN without a studio. You create a live input, point an encoder at it over SRT or RTMP(S), and deliver it to viewers through one or more playback ids. There is no program, no canvas and no destination list: what goes in comes out. Everything lives on the same /v1 host, with the same API keys, error envelope and pagination as the rest of the API, and it is billed by the viewer-hour from the ledgers GET /v1/usage reads.

A key for Edge needs Edge scopes. None of them is in the default key scopes, so mint a key and tick what the integration needs:

Scope What it lets a key do
live_inputs:read List live inputs and read their status. Never a stream key.
live_inputs:write Create, rename, disable and delete live inputs. Includes read.
live_inputs:ingest Fetch and rotate a live input's publish URLs and stream key. A live credential; not included in any other scope.
playback:write / playback:read Create, list and delete playback ids. The same scope that publishes a studio source: it is the same power.
signing_keys:write Create, list, rotate and delete the keys that sign viewer tokens.
webhooks:write / webhooks:read Register, update, test and delete webhook endpoints.
usage:read Read metered usage.

The common dashboard key holds live_inputs:read and usage:read and can never see a stream key.

Endpoints

Method Path Scope What it does
POST /v1/live-inputs live_inputs:write Create a live input. The response is its record, not a credential.
GET /v1/live-inputs live_inputs:read List your live inputs (paged).
GET /v1/live-inputs/{liveInputId} live_inputs:read Read one, including its live/idle/disabled status.
PATCH /v1/live-inputs/{liveInputId} live_inputs:write Rename, replace metadata, set the bitrate cap, or disabled: true/false.
DELETE /v1/live-inputs/{liveInputId} live_inputs:write Delete it and every playback id on it.
POST /v1/live-inputs/{liveInputId}/ingest live_inputs:ingest Get the publish URLs and stream key. Same shape as a studio source's ingest.
POST /v1/live-inputs/{liveInputId}/ingest/rotate live_inputs:ingest Replace the stream key; kickPublishers: true cuts whoever is on the old one. The response says whether it did (kicked).
POST /v1/live-inputs/{liveInputId}/playback-ids playback:write Mint a public or signed playback id with its watch URL, embed snippet and token URL.
GET /v1/live-inputs/{liveInputId}/playback-ids playback:read List the input's playback ids (paged).
DELETE /v1/playback-ids/{playbackId} playback:write Revoke one playback id; the others keep working.
POST /v1/signing-keys signing_keys:write Create an ES256 key. The private half is returned once.
GET /v1/signing-keys signing_keys:write List your keys: ids and public halves only (paged).
POST /v1/signing-keys/{kid}/rotate signing_keys:write Mint a successor key; the old one stays valid until you delete it.
DELETE /v1/signing-keys/{kid} signing_keys:write Delete a key. Tokens signed with it stop verifying at once.
POST /v1/webhook-endpoints webhooks:write Register an HTTPS receiver. The signing secret is returned once.
GET /v1/webhook-endpoints webhooks:read List your endpoints (paged).
GET /v1/webhook-endpoints/{endpointId} webhooks:read Read one endpoint.
PATCH /v1/webhook-endpoints/{endpointId} webhooks:write Change its URL, events or description, or pause it.
DELETE /v1/webhook-endpoints/{endpointId} webhooks:write Delete it.
POST /v1/webhook-endpoints/{endpointId}/rotate-secret webhooks:write Replace the signing secret. The new one is returned once.
POST /v1/webhook-endpoints/{endpointId}/test webhooks:write Deliver a webhook.test event now and report what your endpoint answered.
GET /v1/usage usage:read Viewer-seconds and live-input-seconds per hour or day, from the ledgers that bill you.

Request and response shapes are in the API reference (/v1) under the Edge tag.

Go live in four calls

API=https://api.traxstreaming.live
KEY=sk_live_…   # live_inputs:write, live_inputs:ingest, playback:write

# 1. Create the input.
curl -sS -X POST "$API/v1/live-inputs" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Main stage","metadata":{"event":"launch-day"}}'
# → { "id": "3f6c…-uuid", "status": "idle", "streamName": "l/9a41…64-hex", … }

# 2. Fetch the publish credential (a POST: the response is a secret).
curl -sS -X POST "$API/v1/live-inputs/$ID/ingest" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"protocols":["rtmp"]}'
# → { "streamName": "l/9a41…", "ingestUrls": { "rtmp": { "complete": "rtmp://ingest.traxstreaming.live:1935/l/9a41…?user=…&pass=…", "base": "rtmp://ingest.traxstreaming.live:1935/l/9a41…" } },
#     "granted": ["rtmp"], "streamKey": "…" }

# 3. Point your encoder at ingestUrls.rtmp.complete (or base + streamKey).

# 4. Mint a playback id and paste the embed.
curl -sS -X POST "$API/v1/live-inputs/$ID/playback-ids" \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)"
# → { "playbackId": "…", "policy": "public", "watchUrl": "…", "embedHtml": "<iframe …>", "player": { "tokenUrl": "…" } }

A live input's id is a UUID. streamName is the media path, l/ and 64 hex characters; it is not derived from the id and is safe to log. One ingest hostname serves every region: it resolves to the nearest point of presence. SRT is srt://ingest.traxstreaming.live:8890?streamid=publish:<streamName>:<streamKey>:<streamKey>, RTMP is port 1935 and RTMPS port 1936, both with the key in ?user=&pass=.

Dial complete verbatim and keep it, with streamKey, in a secret store. The ingest routes sit in the credential rate class (a burst of 5, refilling at 5 a minute), so fetch once and reuse rather than asking on every connect.

On RTMP the stream key travels as ?user=…&pass=…, exactly as complete has it. Do not move it to ?token= or any other parameter, and do not repeat it elsewhere in the URL: a publish whose key appears anywhere else in the URL is refused with key_in_url, because URLs end up in proxy and access logs.

Public and signed playback

A public playback id is published the moment it exists: anyone holding it can call POST /v1/playback/{playbackId}/token and watch. Mint one per partner or per embed so you can revoke a leaked link alone.

A signed playback id makes the token endpoint also require a JWT you signed, so you decide who may watch, per viewer and per session, with no call to TRaX in the path:

  1. POST /v1/signing-keys once. Store the privateKey from that response; TRaX keeps only the public half and cannot show the private one again.
  2. For each viewer, sign an ES256 JWT with header kid = the key's id and claims sub = the playback id, aud = trax-playback, exp at most 24 hours out.
  3. Your player sends it as {"token": "<jwt>"} in the body of the token request (or ?token=, which lands in access logs, so prefer the body).

Without a token the route answers 401 viewer_token_required; with one that does not verify, 401 viewer_token_invalid. Rotate with POST /v1/signing-keys/{kid}/rotate, move your signer to the new kid, and delete the old key once its last token has expired.

The watch page and the embed

watchUrl is a hosted page, https://watch.traxstreaming.live/p/{playbackId}. It needs no account and no sign-in. It mints a playback token, plays the stream over WebRTC, and keeps retrying until the input goes live, so you can hand the link out before the show starts. Video starts muted, because browsers refuse autoplay with sound; the viewer unmutes with one click and can go fullscreen from the player controls.

embedHtml is an <iframe> of the same page with ?embed=1, which drops the page chrome so the player fills the frame. Keep the allow="autoplay; fullscreen" attribute it ships with. Any site may frame it.

For a signed playback id, append the viewer's JWT to either URL as ?token=<jwt>. The page sends it to the token endpoint in the request body. Without one, the page tells the viewer they need a pass and stops.

To build your own page instead, load the player element and give it the id:

<script type="module" src="https://watch.traxstreaming.live/embed.js"></script>
<trax-player playback-id="…"></trax-player>

For a signed id, set token="<jwt>" on the element, or assign the element's token property from your script.

The player re-mints a token only when the one it holds is within 20 seconds of expiresAt, and it backs off between attempts using the token response's retryPolicy. The token endpoint allows 10 requests a minute per viewer address, so a player that minted on every retry would be throttled within a minute. A 404 from the token endpoint means the id is unknown or disabled, and the player stops instead of retrying.

Disabling versus deleting

PATCH /v1/live-inputs/{liveInputId} with {"disabled": true} takes an input out of service and keeps it: every playback id stops minting tokens, the ingest routes (fetch and rotate) and new playback ids answer 409 conflict, and a connected publisher is cut. {"disabled": false} brings it back to idle with the same ids and the same stream key. Delete the inputs you will not bring back.

The bitrate cap

Every live input has a cap on what its publisher may send: maxBitrateKbps, video plus audio. Leave it out and the input gets the platform default of 8000 kbps. You can set it lower, or higher up to your account tier's ceiling: 8000 kbps for a new account, 10000 kbps once the account is established. A value above the ceiling is a 400 invalid_request on create and on PATCH.

The edge measures what actually arrives at the PoP, averaged over about 30 seconds, so a keyframe burst does not count against you. The measurement includes the container (MPEG-TS over SRT, RTMP chunk headers), so a publish may run up to 10% over the cap before it counts as over. Then:

  1. After one minute over the cap, your endpoints get live_input.bitrate_exceeded, with maxBitrateKbps, measuredBitrateKbps, overSince and disconnectAt, beside the usual liveInputId, status, metadata and session.
  2. If the publish is still over two minutes later, it is disconnected. live_input.disconnected carries session.endReason: "bitrate_exceeded".
  3. For one minute after that, a reconnect is refused. Your encoder sees the connection refused; lower its bitrate and connect again.

A publish that drops back under the cap at any point starts over: the next run over it gets its own minute before a warning. The edge never throttles a publish to fit the cap, because a throttled stream reaches viewers broken and nobody is told why.

A recommended encoder profile that stays well inside the default cap:

Setting 1080p30 1080p60 720p30
Video H.264 High, 6000 kbps CBR H.264 High, 7000 kbps CBR H.264 Main, 3500 kbps CBR
Keyframe interval 2 s 2 s 2 s
Audio AAC-LC, 160 kbps, 48 kHz AAC-LC, 160 kbps, 48 kHz AAC-LC, 128 kbps, 48 kHz

Use CBR, or VBR with a maximum no higher than the cap. A VBR encoder with only a target setting can run well above it on fast motion for longer than a minute.

When the account refuses

TRaX Edge has no free tier, and three facts about the account stop NEW work (creating a live input, creating a playback id, a new publish, a new viewer). Each has its own error.code, because each has a different fix:

Status Code Meaning What to do
402 card_required No payment method is on file for TRaX Edge. Add one in the dashboard.
402 spend_cap_reached This calendar month's Edge spend reached the account's cap. Raise the cap, or wait for the next month (UTC).
403 suspended TRaX Edge is suspended on the account. Settle the unpaid Edge invoice, or contact support.

Reads keep working in all three. A viewer asking the token route for one of the account's playback ids gets the plain 404: the owner's billing state is not shown to the audience. Holding the maximum number of live inputs is 402 input_limit_reached; the per-input playback id, signing key and webhook endpoint limits are 409 conflict.

If TRaX Edge itself is unreachable the routes answer 503 unavailable with a Retry-After header; retry after that many seconds.

Rotating a leaked key

POST /v1/live-inputs/{liveInputId}/ingest/rotate replaces the stream key and returns the new credential. The old key is refused for every new connection from that moment. A publisher that is already connected is not affected by the rotation alone, because a publish is authorised once, when it connects; send {"kickPublishers": true} to cut it.

The response always carries the new credential, and tells you what became of the kick:

kicked kickFailure Meaning
true absent You asked for a kick and the publisher was cut.
false absent You did not ask for a kick.
false kick_unavailable You asked for a kick and it could not be performed.

kick_unavailable is still a 200: the key has rotated, the old key is already invalid for new connections, and streamKey in that response is the one now in force. Only a publisher that was connected before the rotation is still on air, until its connection drops; it cannot reconnect with the old key.

There is no kick-only route. To retry the kick, call the same route again with kickPublishers: true. That rotates the key again, so configure your encoder from the latest response, and leave a few seconds between attempts: each one issues a new key. If you send Idempotency-Key, use a fresh one for the retry; a repeated key returns the first response and kicks nothing.

Every call to this route rotates. After a timeout, do not resend it blindly: read the current credential with POST …/ingest, or send an Idempotency-Key with the rotate so that a repeat returns the first response.

Webhooks and usage

Register a receiver with POST /v1/webhook-endpoints and subscribe to the event types you want (["*"] for every type in the catalog). Every delivery is signed; see Webhooks for the signature, the retry policy and the event catalog. POST /v1/webhook-endpoints/{endpointId}/test fires one webhook.test event through the normal delivery path and waits for what your endpoint answered, so you can check your signature verification before anything real happens. If no attempt completes within about 20 seconds the route answers 503 unavailable; the event stays queued and is still delivered. A disabled endpoint takes no deliveries, so the test route answers 409 webhook_endpoint_disabled at once; enable the endpoint with PATCH {"disabled": false} and test again.

GET /v1/usage returns viewerSeconds and liveInputSeconds per hour or day, optionally split by liveInput and region, over a window of up to 31 days (hourly) or 366 days (daily). It reads the same ledgers that produce your invoice: 3600 viewer-seconds is one billable viewer-hour. It has its own rate bucket (a burst of 10, refilling at 1 a second), sized for a dashboard that refreshes on a timer.