Skip to content

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.

  1. 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[].id is the streamSettingsId every stream route takes. overlays[].id is the overlay you can switch to in step 4.

  2. 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.

  3. 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 }

    …/start starts the stream. Without destinationIds it 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/start with the same body. An operator can also start the destinations from the dashboard.

    Poll GET …/state every 5 seconds until state reads ONLIVE. The transition takes about 4 minutes. ERROR means 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.

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

  5. 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 …/state until state reads IDLE. The stream is then ready for the next start.

GET …/state returns one of these values.

stateMeaning
IDLENo stream is running. A start is allowed
CREATINGThe start was accepted and the infrastructure is starting
ONLIVEThe stream runs, with or without destinations. A stop is allowed
TRANSIT_TO_STOPPEDThe stop was accepted and the infrastructure is stopping
ERRORThe 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.

RouteEffect
POST …/startStart the stream. Allowed from IDLE. destinationIds picks the destinations that publish at once
POST …/stopStop the stream. Allowed from ONLIVE
POST …/destinations/startStart publishing to the given destinations of a running stream
POST …/destinations/stopStop 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.

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.

StatusCause
400The 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
403A read key on …/start, …/stop, …/destinations/… or an overlay route, or a stream of another organization. Use a write key
404The streamSettingsId does not exist

See Streams in the REST reference.