Skip to main content

Program

The Program Service is the core API for orchestrating live video. It models live content as programs and the streams that feed them, manages real-time sessions, and exposes historical stream sessions for reporting.

The v2 endpoints are token-scoped: your project is resolved from the service-account JWT you authenticate with, so requests omit the projectID from the path. Use these for new integrations.

Projects, programs, and streams

These three nest — and telling them apart is the key to a successful create-stream call:

  • Project — your account/tenant. For the core v2 program and stream calls it’s read from your service-account token, so you don’t pass it; v1 takes it from the URL path (/v1/projects/{projectID}/…). A few v2 endpoints are still explicitly project-scoped — e.g. the Assets API uses /v2/projects/{projectID}/assets, and the multi-project stream queries take a projectIds array in the body.
  • Program — a container with its own id (a UUID) and slug. One program can hold many streams.
  • Stream — a single live ingest/broadcast feed, belonging to exactly one program.

Lifecycle: from program to report

A typical v2 integration moves a live experience through these stages, in order:

  1. Create a program. POST /v2/programs establishes the container that groups related streams — or reuse an existing program to gather several streams under one.
  2. Start a stream. POST /v2/streams attaches a stream to that program (by programID or programSlug), and POST /v2/streams/start marks it live. Push the feed to the RTMP ingest URL the platform issues for the stream.
  3. Participants join sessions. As participants connect, join-session and end-session track each real-time connection to the program.
  4. End the stream. POST /v2/streams/end stops the live feed; ping keeps a running stream marked active in the meantime.
  5. Report on stream sessions. Once activity has occurred, read per-stream and project-wide stream-session summaries and concurrent-peak metrics for analytics.

Core concepts

Programs

A program is the top-level container for a live experience — its identity (id and slug) and configuration. Create, fetch, update, and delete programs, or look one up by id or slug.

Streams

A stream is a single live ingest/broadcast feed associated with the platform. Manage the stream lifecycle — start, end, and ping — search and list active streams, read stream counts, drive RTMP push destinations, and signal encoding format changes.

Creating a stream: a program ID is not a project ID

POST /v2/streams attaches the stream to an existing program, so the body must include either programID (a program’s UUID) or programSlug. Create one first with POST /v2/programs, or reuse a program to group several streams. A missing/invalid field program ID error means neither was sent — or that a project ID was passed as programID. For this call your project comes from your service-account token, so it isn’t part of the body.

Ingesting with an external encoder (RTMP)

Push a feed from OBS, GStreamer, or any RTMP encoder using the ingest URL the platform issues for the stream — use it exactly as provided. The issued URL has the shape rtmp://{host}/origin/{streamKey}?authKey={secret}&ns={projectId}. If you assemble it yourself, note that ns is your Project ID (the same UUID shown on your project, lowercase ns) — not an environment name. The stream key alone does not identify the project, so ns must carry it.

Sessions

A session represents a participant's live connection to a program. Begin and end a session (join / end) to manage that real-time lifecycle.

Stream Sessions

Stream sessions are the historical and aggregate record of streaming activity. Retrieve per-stream and project-wide session summaries, concurrent-peak metrics, and detailed session listings for analytics and reporting.

Versioning

v1 → v2: what changed
  • Project scoping. v1 identifies the project in the URL path (/v1/projects/{projectID}/…). v2 resolves it from your service-account token, so v2 paths drop projectID.
  • Streams replace broadcasts. In v1 a live feed was a broadcast, started and stopped with PUT /v1/broadcast/{streamId} and DELETE /v1/broadcast/{streamId}. In v2 it's a stream with an explicit lifecycle — POST /v2/streams/start and POST /v2/streams/end (with format-begin, format-end, and ping under /v2/streams). Use start / end stream instead of broadcast.
  • Action-style routes. v1 used RESTful resource routes with the id in the path; v2 uses body-driven action POSTs under /v2/streams.
  • New in v2. Participant sessions (join-session / end-session) and stream-session reporting — per-stream and project-wide summaries plus concurrent-peak metrics.