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.

curl 'https://api.ligr.live/rest/v2/matches/1188213?include=s,o' \
  -H "Authorization: Bearer $LIGR_API_KEY"

{
  "id": 1188213,
  "streams": [{ "id": 90412, "name": "Main feed", "destinations": [{ "id": 3301, "name": "YouTube", "type": "youtube" }] }],
  "overlays": [{ "id": 2300003, "name": "Broadcast", "key": "…" }]
}

streams[].id is the streamSettingsId every stream route takes. overlays[].id is the overlay you can switch to in step 4.

Read the state.

curl 'https://api.ligr.live/rest/v1/streams/90412/state' \
  -H "Authorization: Bearer $LIGR_API_KEY"

{ "streamSettingsId": 90412, "state": "IDLE", "matchId": 1188213 }

An idle stream is ready for GoLive.

Go live.
Terminal
```
curl -X POST 'https://api.ligr.live/rest/v1/streams/90412/manage' \
  -H "Authorization: Bearer $LIGR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "command": "GoLive" }'
```
200 OK
```
{ "streamSettingsId": 90412, "state": "CREATING", "matchId": 1188213, "transitioning": true }
```
GoLive starts the stream. Without startDestinationsImmediately it publishes nowhere: the picture runs, and an operator starts the destinations from the dashboard when it is right. That is the preview. To publish at once, list the destination ids to start:
Go live and publish to one destination at once
```
{ "command": "GoLive", "startDestinationsImmediately": [3301] }
```
Poll GET …/state every 5 seconds until state reads ONLIVE. The transition takes tens of seconds. ERROR means the start failed. Open the stream in the dashboard to read the cause.

Switch the overlay.

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": null to unlink the overlay. …/overlay/show and …/overlay/hide toggle the linked overlay without unlinking it. …/overlay/refresh restarts it.

Stop.

curl -X POST 'https://api.ligr.live/rest/v1/streams/90412/manage' \
  -H "Authorization: Bearer $LIGR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "command": "StopStream" }'

{ "streamSettingsId": 90412, "state": "TRANSIT_TO_STOPPED", "matchId": 1188213, "transitioning": true }

Poll GET …/state until state reads IDLE. The stream is then ready for the next GoLive.

States

GET …/state returns one of these values.

`state`	Meaning
`IDLE`	No stream is running. `GoLive` is allowed
`CREATING`	`GoLive` was accepted and the infrastructure is starting
`ONLIVE`	The stream is live. `StopStream` is allowed
`TRANSIT_TO_STOPPED`	`StopStream` was accepted and the infrastructure is stopping
`ERROR`	The start or the stop failed. Open the stream in the dashboard

The manage answer adds transitioning. It is true for CREATING and TRANSIT_TO_STOPPED. A command sent while the stream is transitioning is refused with 400. The state endpoint does not carry transitioning. Poll on state.

Commands

`command`	Effect
`GoLive`	Start the stream. Allowed from `IDLE`. `startDestinationsImmediately` picks the destinations that publish at once
`StopStream`	Stop the stream. Allowed from `ONLIVE`

There is no pause. Stop the stream and go live again. There is no separate preview command. GoLive without destinations is the preview.

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

Status	Cause
400	The command is not allowed from the current state, or the stream is transitioning
403	A read key on `…/manage` or an overlay route. Use a write key
404	The `streamSettingsId` belongs to another organization, or the match has no stream

See Streams in the REST reference.