Automate a stream
A stream has an input, destinations and an overlay. Configure it in the dashboard, or over REST with Configure a stream. This guide drives a configured stream for one match. It needs a write key and a match that already has a stream.
The endpoints are under Streams in the REST reference.
-
Find the stream of the match.
Terminal curl 'https://api.ligr.live/rest/v2/matches/1188213?include=s,o' \-H "Authorization: Bearer $LIGR_API_KEY"200 OK (excerpt) {"id": 1188213,"streams": [{ "id": 90412, "name": "Main feed", "destinations": [{ "id": 3301, "name": "YouTube", "type": "youtube" }] }],"overlays": [{ "id": 2300003, "name": "Broadcast", "key": "…" }]}streams[].idis thestreamSettingsIdevery stream route takes.overlays[].idis the overlay you can switch to in step 4. -
Read the state.
Terminal curl 'https://api.ligr.live/rest/v1/streams/90412/state' \-H "Authorization: Bearer $LIGR_API_KEY"200 OK { "streamSettingsId": 90412, "state": "IDLE", "matchId": 1188213 }An idle stream is ready to start.
-
Go live.
Terminal curl -X POST 'https://api.ligr.live/rest/v1/streams/90412/start' \-H "Authorization: Bearer $LIGR_API_KEY" \-H 'Content-Type: application/json' \-d '{}'200 OK { "streamSettingsId": 90412, "state": "CREATING", "matchId": 1188213, "transitioning": true }…/startstarts the stream. WithoutdestinationIdsit publishes nowhere: the picture runs, and no destination receives it. That is the preview. To publish at once, list the destination ids to start:Go live and publish to one destination at once { "destinationIds": [3301] }To publish after a preview, send
POST …/destinations/startwith the same body. An operator can also start the destinations from the dashboard.Poll
GET …/stateevery 5 seconds untilstatereadsONLIVE. The transition takes about 4 minutes.ERRORmeans the start failed. Open the stream in the dashboard to read the cause.A start needs a streaming balance above 0 minutes. A running stream uses the streaming balance of the organization, also during a preview without destinations. When the balance reaches 0 minutes, LIGR can stop the stream.
-
Switch the overlay.
Terminal curl -X POST 'https://api.ligr.live/rest/v1/streams/90412/overlay/change' \-H "Authorization: Bearer $LIGR_API_KEY" \-H 'Content-Type: application/json' \-d '{ "overlayId": 2300003 }'Send
"overlayId": nullto unlink the overlay.…/overlay/showand…/overlay/hidetoggle the linked overlay without unlinking it.…/overlay/refreshrestarts it. -
Stop.
Terminal curl -X POST 'https://api.ligr.live/rest/v1/streams/90412/stop' \-H "Authorization: Bearer $LIGR_API_KEY"200 OK { "streamSettingsId": 90412, "state": "TRANSIT_TO_STOPPED", "matchId": 1188213, "transitioning": true }Poll
GET …/stateuntilstatereadsIDLE. The stream is then ready for the next start.
States
Section titled “States”GET …/state returns one of these values.
state | Meaning |
|---|---|
IDLE | No stream is running. A start is allowed |
CREATING | The start was accepted and the infrastructure is starting |
ONLIVE | The stream runs, with or without destinations. A stop is allowed |
TRANSIT_TO_STOPPED | The stop was accepted and the infrastructure is stopping |
ERROR | The start or the stop failed. Open the stream in the dashboard |
The start and stop answers add transitioning. It is true for CREATING and
TRANSIT_TO_STOPPED. A start or stop sent while the stream is transitioning is refused with 400.
The state endpoint does not carry transitioning. Poll on state.
Commands
Section titled “Commands”| Route | Effect |
|---|---|
POST …/start | Start the stream. Allowed from IDLE. destinationIds picks the destinations that publish at once |
POST …/stop | Stop the stream. Allowed from ONLIVE |
POST …/destinations/start | Start publishing to the given destinations of a running stream |
POST …/destinations/stop | Stop publishing to the given destinations. The stream keeps running |
There is no pause command. To stop publishing and keep the stream running, use
…/destinations/stop. There is no separate preview command. A start without destinations is the
preview.
POST …/manage with GoLive or StopStream is deprecated. It works until 2027-09-08.
Polling
Section titled “Polling”Poll GET …/state every 5 seconds while a transition is in progress. Stop polling when the
stream reaches the state you wait for. See Rate limits.
Errors
Section titled “Errors”| Status | Cause |
|---|---|
| 400 | The start or stop is not allowed from the current state, the stream is transitioning, or a start with a streaming balance of 0 minutes or less |
| 403 | A read key on …/start, …/stop, …/destinations/… or an overlay route, or a stream of another organization. Use a write key |
| 404 | The streamSettingsId does not exist |
See Streams in the REST reference.