Start and stop a Live stream
Available in: UI · API
Use this how-to to start a configured Live stream on the right encoder and stop it again. Both the UI and the public API drive the same backend — pick the surface that fits your caller.
When to use this
When a service, an external scheduler, an automation script or an operator needs to bring a Live stream on air. For supervised, calendar-driven starts use the Scheduler instead.
Prerequisites
- The numeric identifier of a Live stream that has already been configured (Channel, Encoding and Destination bound). Read it from the Live streams list or from
GET /c21apiv2/livestreams. - A user with the Operator or System Administrator role. Both roles can start and stop Live streams.
- For API callers: a valid API token issued from Preferences → API tokens. See API → Authentication.
- A valid C21 Live Control product license on the instance. See Licenses.
Via UI
Navigation: Live streams → <name> or On air. Selecting a row in On air exposes the Start / Stop buttons in the toolbar.
Open the Live stream
On the Live streams list (left rail), pick the row of the Live stream to bring on air; or, if it is already running, open On air.
Click Start
The toolbar's Start button opens the Start with options dialog. Pick the Encoder group and the Preferred encoder; the picker remembers the last selection on this device (a single-encoder shop only sees the picker once).
Confirm
The UI presents the Start Live stream dialog:
Do you want to start this Live stream?
Primary action: Start Live stream. Secondary action: Cancel. On confirm, the row appears on On air and transitions to Live within a few seconds.
Stop
Click the Stop button. The dialog copy depends on whether the broadcast was started manually or by the Scheduler:
- Regular: "Do you want to stop this Live stream?"
- Scheduled: "Do you want to stop this Scheduled Live stream?" with the second line "The associated Schedule will be deleted." — confirming also removes the active Schedule.
Via API
The lifecycle of a Live stream lives at /c21apiv2/livestreams/{livestreamId}:
| Action | Method + path | operationId |
|---|---|---|
| Start configuration preconditions | GET /c21apiv2/livestreams/{livestreamId}/start/config | getLivestreamStartConfig |
| Start | POST /c21apiv2/livestreams/{livestreamId}/start | startLivestream |
| Status | GET /c21apiv2/livestreams/{livestreamId}/status | getLivestreamStatus |
| Detail | GET /c21apiv2/livestreams/{livestreamId} | getLivestreamById |
| Stop | POST /c21apiv2/livestreams/{livestreamId}/stop | stopLivestream |
Pass the API token in the standard bearer header — Authorization: Bearer <YOUR_API_TOKEN> — for every call.
Start
curl -s "https://<your-host>/c21apiv2/livestreams/<livestreamId>/start/config" \
-H "Authorization: Bearer <YOUR_API_TOKEN>"
getLivestreamStartConfig returns the last saved startConfig[], the preferred encoder group and the startAllowed boolean. startAllowed = false means the Live stream is missing a bound Channel, Encoding or Destination.
curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/start" \
-H "Authorization: Bearer <YOUR_API_TOKEN>" \
-H "Idempotency-Key: <unique-key-per-logical-start>" \
-H "Content-Type: application/json" \
-d '{ "idEncoderGroup": <from-config-response>, "startConfig": [] }'
Idempotency-Key is honoured on startLivestream; replaying the same key returns the original response without re-issuing the start.
Poll status
curl -s "https://<your-host>/c21apiv2/livestreams/<livestreamId>/status" \
-H "Authorization: Bearer <YOUR_API_TOKEN>"
LiveStream.status returns one of four values:
status | UI label | Meaning |
|---|---|---|
0 | Off | stopped / idle |
1 | (transient) | starting |
2 | Live | running |
3 | (transient) | error / failed |
Stop
curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/stop" \
-H "Authorization: Bearer <YOUR_API_TOKEN>"
stopLivestream does not honour Idempotency-Key — stopping an already-stopped Live stream is a safe no-op. The public stop does not touch any Schedule; to stop a scheduled broadcast and remove its Schedule in one move, mirror the UI flow (list and delete the active Schedule for the Live stream).
Verify
- The row on On air reads Live and the entrypoint arrows are green.
- A subsequent
getLivestreamStatusreturnsstatus = 2. - After stop, the row leaves On air;
getLivestreamStatusreturnsstatus = 0.
FAQ
addChannel, addLivestream, startLivestream, addSchedule and executeEditor. stopLivestream does not require an idempotency key because stopping an already-stopped Live stream is a safe no-op.dry_run flag. Use getLivestreamStartConfig to inspect the start preconditions before posting the start; that call is read-only and surfaces the startAllowed boolean.stopLivestream does not touch the Schedule; mirror the UI flow if you want both actions.Preferences → API tokens, switch the integration over to the new value, confirm it works, then revoke the old one. See API → Authentication.