#API reference

Every endpoint, parameter and field of the JustOnAir API, generated from openapi.json.

All endpoints live at https://api.justonair.com. Authenticate with Authorization: Bearer <API key>. Requests and responses are JSON. Times are ISO 8601 UTC; money is a decimal string in USD.

This page is generated from openapi.json. Import that file into Postman, an SDK generator or an agent framework to get the same thing as code.

#Streams

Create, read, change and end streams.

#Create a stream

POST /v1/streams

Reserves ingest capacity for 30 minutes and returns everything needed to go live: rtmp_url + stream_key, whip_url, playback_url and embed_url. The secrets are returned only here. Send an Idempotency-Key so a retry never creates a second stream.

Body (optional)

Responses

#List streams

GET /v1/streams

Newest first.

Responses

#Get a stream

GET /v1/streams/{id}

Status, what is arriving (ingest), the recording, and cost so far. Poll it to follow a stream; every 3–5 s is fine.

Responses

#Update a stream

PATCH /v1/streams/{id}

Rename it, replace its metadata, or change player settings. Works in any status.

Body. Only these fields can change, in any status. Null clears a field; metadata is replaced whole.

Responses

#End or cancel a stream

DELETE /v1/streams/{id}

Live: ends it and disconnects the publisher within seconds. Pending: cancels it and releases the slot. Already finished: returns it unchanged.

Responses

#Replace a lost stream key

POST /v1/streams/{id}/stream-key

Only while pending. The old key and WHIP URL stop working at once.

Responses

#Viewers per minute

GET /v1/streams/{id}/viewers

The viewer curve: live estimates from the hosted player, and exact counts from the CDN logs about an hour later.

Responses

#Playback

Signed URLs for your own player.

#Sign a playback URL

POST /v1/streams/{id}/playback-token

A fresh signed HLS URL, for example a short one per viewer minted by your backend. Refused once the stream is finished.

Body (optional)

Responses

#Recordings

The MP4 made after a stream ends.

#Delete the recording

DELETE /v1/streams/{id}/recording

Deletes the MP4 now, or marks it to be deleted as soon as it exists.

Responses

#Get a download link

POST /v1/streams/{id}/recording/download

Body (optional)

Responses

#Account

Balance and usage.

#Balance and usage

GET /v1/usage

Responses

#Webhooks

Endpoints that get stream and recording events, and their delivery log.

#List webhook endpoints

GET /v1/webhooks

Without secrets. Also returns event_types, every type an endpoint can subscribe to.

Responses

#Add a webhook endpoint

POST /v1/webhooks

Up to 5 per account. The answer includes secret; see Webhooks for verifying signatures.

Body

Responses

#Get a webhook endpoint

GET /v1/webhooks/{id}

With its secret.

Responses

#Change a webhook endpoint

PATCH /v1/webhooks/{id}

Body

Responses

#Delete a webhook endpoint

DELETE /v1/webhooks/{id}

Its delivery log goes with it.

Responses

#Rotate the signing secret

POST /v1/webhooks/{id}/secret

The old secret keeps signing alongside the new one for 24 hours.

Responses

#Send a test event

POST /v1/webhooks/{id}/test

Queues a webhook.test; it is sent within a couple of seconds.

Responses

#Delivery log

GET /v1/webhooks/{id}/deliveries

Newest first, kept 30 days.

Responses

#Send a delivery again

POST /v1/webhooks/{id}/deliveries/{delivery_id}/retry

A failed delivery gets one more attempt now; a pending one is brought forward.

Responses

#Embed

The hosted player’s public read.

#Public stream status (hosted player)

GET /v1/embed/{id}

No key needed; any web page may call it. Cached for a few seconds; the same read is served, cached at the CDN edge, at https://play.joacdn.com/api/embed/{id}. Rate limited per IP on unknown ids (60/min).

No API key needed.

Responses

#Report a viewer (sampled)

POST /v1/embed/{id}/beat

Sent by the hosted player, or by your own player to be counted live. Draw u once per page load; report every beacon.interval_seconds while u is below beacon.rate from the embed read. No body, so navigator.sendBeacon(url) works from any page.

No API key needed.

Responses

#Objects

#Stream

#CreatedStream

A stream plus its secrets. Returned once, by the create call (and by replacing the key). Store them; they are never shown again.

#Ingest

What the ingest node last measured arriving. Null until the first measurement.

#Recording

The recording: one MP4 of the top quality, made after the stream ends. Null while pending.

#Cost

What this stream has cost so far at current rates. Only on GET /v1/streams/{id}. Amounts are decimal strings.

#Viewers

Viewer counts. While the stream runs, now is estimated from the hosted player: exact up to about 400 viewers, within about 5% above. After the fact, the CDN logs give the exact count for every player (hosted, your own, apps), about an hour later; peak and watch_minutes use them once they exist. Only on GET /v1/streams/{id}.

#ViewerSeries

#PlayerSettings

#StreamList

#PlaybackToken

#RecordingDownload

#Embed

What the hosted player needs. Public: no key, any origin may read it.

#Usage

#WebhookEndpoint

#WebhookDelivery

#WebhookEvent

The body of every webhook. Headers: webhook-id, webhook-timestamp, webhook-signature (Standard Webhooks).

#Error