Developer documentation · API v1

Schedule live Events.
Control fixed encoders safely.

A tenant-bound REST API for office scheduling systems and a separate, self-scoped control surface for encoder Devices.

Download OpenAPI 3.1View quick start

Contract 1.1.0 · scoped tenant API access

Origins

Use the API hostname explicitly

Never derive the machine API origin from an organisation or administration hostname.

Staging

https://api-staging.smartavstream.com

Production

https://api.smartavstream.com

Quick start

Create an Event without sharing contribution credentials

The ApiClient credential selects the Tenant. External API access must be enabled for that organisation, and the credential needs events:write for this request.

RequestPOST /api/v1/live-events
curl --request POST "https://api-staging.smartavstream.com/api/v1/live-events" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: office-event-4831-create" \
  --data '{
    "title": "Quarterly briefing",
    "externalReference": "office-event-4831",
    "contentType": "live_to_vod",
    "scheduledStartAt": "2026-10-09T22:00:00Z",
    "scheduledEndAt": "2026-10-09T23:00:00Z",
    "encodingProfile": "standard-landscape",
    "channelId": "11111111-1111-4111-8111-111111111111"
  }'

Reference

Six machine-facing operations

Tenant Administration endpoints are intentionally excluded: they use a human session and are not an external integration contract.

POST/api/v1/live-events

Create a draft scheduled-live or live-to-VOD Event.

GET/api/v1/live-events?externalReference=…

Reconcile an Event using your stable reference.

GET/api/v1/live-events/{eventId}

Read the authoritative schedule and revision.

PATCH/api/v1/live-events/{eventId}

Edit with Idempotency-Key and If-Match.

POST/api/v1/encoder/bootstrap

Retrieve bound ingest details once per credential version.

POST/api/v1/encoder/poll

Report heartbeat/state and receive the current instruction.

Encoder loop

Bootstrap once. Poll every 60 seconds.

The Device credential is bound to one Channel. Bootstrap returns the stream key only for a claimable credential version; polling never repeats it.

  1. 01

    Provision

    Create the Device in Tenant Administration and store the displayed token securely.

  2. 02

    Bootstrap

    Retrieve the RTMPS server, stream key and Channel credential version without logging the response.

  3. 03

    Poll

    Report the actual local state and apply the explicit idle, start, continue or stop instruction.

  4. 04

    Recover

    On transport failure or temporary 503, preserve the current state and retry. Never start from a cached instruction.

Operational truth

“Instructed to stream” is not “video received”

SmartAVStream keeps each signal separate so administration can expose mismatches instead of hiding them behind one live indicator.

Desired instruction

What SmartAVStream wants: idle, start, continue or stop.

Device presence

Whether the encoder has polled recently.

Reported state

Whether the Device says it is idle or streaming.

Provider input

Whether the media platform is actually receiving video.

Audience availability

Whether viewers may watch the intended Event.

Onlinelast poll ≤ 3 minutes
Connection delayed> 3 through 5 minutes
Offline> 5 minutes

Reliability

Retry without creating duplicates

Event writes

Reuse the same Idempotency-Key and identical body when a response is lost. PATCH also requires the current numeric If-Match revision.

Device outage

If a poll is unavailable, a running encoder continues and an idle encoder remains idle. A successful current stop or revoked credential is not an outage.

Rate limits

Respect Retry-After on 429/503 responses and use bounded exponential backoff with jitter. Do not retry unchanged validation or authentication failures.

Secrets

Redact Authorization and stream-key values from source control, URLs, logs, crash reports, support tickets, analytics and audit metadata.

Release boundary

Current versus planned

Available

Stage 2

Live Event create/read/edit, idempotency, Device bootstrap, heartbeat/polling, manual encoder start, credential revoke/reissue and previous-Event stop guard.

Planned

Next controlled stage

Automatic movement of Event B, independent provider enforcement at the 30-minute boundary, and full intended-Event public-player gating.