Everything the stream settings page does, over REST: an input for the camera, destinations for the platforms, a stream for the match, and the calls that start, watch and stop it.
The LIGR streaming API configures and runs a match stream over REST. Create a reusable input that gives you RTMP and SRT ingest URLs, save destinations such as YouTube or any custom RTMP or SRT server, and create the stream for a match. Start it with POST /v1/streams/{streamSettingsId}/start and stop it with /stop. This guide follows Configure a stream and the Streams reference in the LIGR developer docs.
Who this is for
Broadcasters, production companies and leagues that stream many matches and want each one set up and run from their own scheduling system. Every call needs a key with the streams scope: streams:read to read, streams:write to change anything. The REST API quick start covers keys.
What you can build
| Sport | Set-up |
|---|---|
| Football | A league with a fixed camera at each ground sets inputSelection to venue, so every match uses the input assigned to its venue |
| Basketball | A club that streams its home games from its own camera: inputSelection: home uses the input assigned to the home team |
| Tennis | One input per court camera, reused match after match, because an input belongs to a camera feed, not to a match |
| AFL | A programme feed with graphics to YouTube and a clean feed without graphics to a partner's custom SRT server, set per destination with feedType |
| Netball | Highlights cut from the facts of the match with generateHighlights, and published as they are cut with publishHighlights |
| American football | Auto Stream starts and stops each game at the automation times of the match, with no manual start |
destinationSelection works the same way as inputSelection. You assign inputs and destinations to teams and venues in the dashboard.
How it works
Create an input
Send POST /v1/streams/inputs with a name and a latencyMs. LIGR generates the host, the application name and the stream key, and answers with rtmpUrl, streamKey and srtUrl. Send the picture to either. latencyMs absorbs network jitter and adds the same delay to the picture: it is one of 20, 50, 100, 150, 250, 350, 500, 1000, 1500, 2000, 2500 or 3000. For a source LIGR pulls instead, send "type": "pull" and a sourceUrl.
Save a destination
Send POST /v1/streams/destinations with a name, a type, a url and a key. type is youtube, facebook, twitter, linkedin, tiktok, twitch, custom or a partner platform, and custom takes any RTMP or SRT server. feedType is program, with graphics, or clean, without. A pull destination answers with a pullUrl that a player or relay pulls from.
Create the stream for the match
matchId, resolution, fps and region are required, and the stream takes its competition from the match. region is the AWS region the stream runs in: pick the one nearest the input, for example ap-southeast-2 for Sydney or eu-west-2 for London. This call is copied from Configure a stream:
curl -X POST 'https://api.ligr.live/rest/v1/streams' \
-H "Authorization: Bearer $LIGR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"matchId": 1188213,
"name": "Main feed",
"resolution": "1920 * 1080",
"fps": "50",
"region": "ap-southeast-2",
"inputId": 412,
"destinationIds": [3301],
"overlayId": 2300003
}'The id in the answer is the streamSettingsId every lifecycle route takes. overlayId is an overlay of the same match, which GET /v2/matches/{matchId}?include=o returns.
Start it, and preview first
Call POST /v1/streams/{streamSettingsId}/start. Without destinationIds, the picture runs and publishes nowhere: that is the preview. Poll GET /v1/streams/{streamSettingsId}/state every 5 seconds until state reads ONLIVE. The transition takes tens of seconds.
Publish when the picture is right
Call POST /v1/streams/{streamSettingsId}/destinations/start with the destinationIds to publish, or let an operator start them in the dashboard. To publish as soon as the stream is up, pass destinationIds to /start instead.
Stop it
Call POST /v1/streams/{streamSettingsId}/stop. Every destination stops publishing, the state moves through TRANSIT_TO_STOPPED to IDLE, and the stream is ready for the next start. There is no pause: stop and start again.
state | Meaning |
|---|---|
IDLE | No stream is running |
CREATING | The start was accepted and the infrastructure is starting |
ONLIVE | The stream is live |
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 to read the cause |
While the stream runs
- Switch the graphics.
POST …/overlay/changewith anoverlayIdlinks another overlay, andnullunlinks it.…/overlay/showand…/overlay/hidetoggle the linked overlay, and…/overlay/refreshrestarts it. - Look after the input.
POST …/input/refreshrestarts the stream input, andPOST …/input/latencysets a newlatencyMs. - Change only what a live stream allows. While it runs, you can change
autoStream,autoStreamConfig, the three automation times,generateHighlights,publishHighlightsanddestinationIds. Anything else answers 400: stop the stream first.
Automation, recording and highlights
| Field | What it does |
|---|---|
autoStream | Starts and stops the stream at the automation times of the match, which needs pregame and postgame times set. POST …/automation turns it on or off |
streamPreviewStartTime, streamLiveStartTime | Minutes relative to the scheduled start of the match |
streamAutoStopTime | Minutes relative to the time the match stopped |
archiveFullFeed, archiveCleanFeed | Keep the recording of the programme feed, or of the clean feed |
generateHighlights, publishHighlights | Cut highlights from the facts of the match, and publish them as they are cut. Turning on highlights while the stream runs needs archiveFullFeed already on |
Limits and notes
resolutionis1280 * 720or1920 * 1080, andfpsis 25, 30, 50 or 60.- A running stream, an input in use by a running stream and a destination linked to a running stream all refuse to delete.
- Inputs and destinations are reusable. Create one input per camera feed, not one per match, and list what your organisation has with
GET /v1/streams/destinations.
Older examples. Some examples drive a stream with POST /v1/streams/{streamSettingsId}/manage and the GoLive and StopStream commands. That route is deprecated: it keeps working until 8 September 2027 and returns Deprecation and Sunset headers. Use /start and /stop for new work. See the changelog.
Frequently asked questions
Can I start and stop a LIGR stream through the API?
Yes. POST /v1/streams/{streamSettingsId}/start starts the stream and POST /v1/streams/{streamSettingsId}/stop stops it, with a key that has streams:write. Poll GET /v1/streams/{streamSettingsId}/state until it reads ONLIVE or IDLE.
How do I preview a stream before it goes public?
Start it without destinationIds. The picture runs and publishes nowhere. When it is right, call POST /v1/streams/{streamSettingsId}/destinations/start with the destinations to publish, or let an operator start them in the dashboard.
Which ingest protocols does a LIGR input accept?
RTMP and SRT. An input answers with an rtmpUrl and a stream key, and an srtUrl. For a source LIGR pulls instead, create the input with type: pull and a sourceUrl.
Can one stream send a feed without graphics?
Yes. Each destination has a feedType: program carries the graphics and clean does not. Recording works the same way, with archiveFullFeed for the programme feed and archiveCleanFeed for the clean feed.
Is there a pause command for a LIGR stream?
No. Stop the stream and start it again. A stopping stream reads TRANSIT_TO_STOPPED, and it is ready for the next start once it reads IDLE.
Configure your first stream
The Configure a stream guide creates an input, a destination and a match stream with curl, and the Streams reference lists every lifecycle route.