Skip to content

Overview

An overlay is the per-match graphics session. It is the browser source that your vision mixer loads. Each graphics command that you send over REST targets one overlay.

Browser source, 1920×1080
https://overlay.ligr.live/production-3b2b1c0e-…

Two endpoints drive graphics on an overlay. Both need the overlays:write scope.

EndpointUse it when
POST /v2/overlays/{overlayId}/graphics/commandsYou address a graphic by name or UUID and you own every variable value. See Graphics commands.
POST /v2/overlays/{overlayId}/control-room/graphicsYou fire a control room preset by id, and the server fills in the values the operator configured. See Presets.

A third endpoint feeds data into the theme, not commands. See External data sources.

A control room is the button layout an operator uses during a match. Your organization owns it, and it uses one theme. The theme can be a theme your organization owns, a theme LIGR linked to your organization, or a public theme. See Themes you can use. Each button is a preset. A preset names one graphic and the values of the variables the operator can see. The dashboard groups presets into sections.

A competition’s theme profile can assign a default control room. An overlay can select another control room for the same theme. Fire the same preset over REST, and an automation does what the operator does in manual mode.

Use Set up through REST to prepare the full session before opening the dashboard. The sequence creates the competition, teams, venue, match, theme profile, room, sections, presets, and manual overlay. It returns a controlRoomUrl that opens the finished setup.

Publish and activate your code graphic first through REST or the CLI. The same flow supports plain HTML and browser rendering libraries that work within the bundle rules.

Dashboard preset commands and both REST command endpoints update manual graphic state. The overlay must use manual mode to display that state. Sending a REST command does not switch the overlay into manual mode.

The MANUAL switch is unavailable when no overlay is selected or the overlay follows a controller. For linked overlays, select the controller and enable manual mode there.

Theme activation is separate from manual mode. Reload existing overlay pages after activating a different theme version.

No endpoint reads the live state of an overlay. manualGraphicState comes back only from the command you just sent. It proves the server accepted the command. It does not prove a graphic appeared.

Open the monitoring view of the overlay to see the result. Read monitoringUrl from the overlay response. GET /v2/overlays/{overlayId} and POST /v1/overlays return it. GET /v2/control-rooms/{roomId} returns it for every overlay that uses the room when the key has overlays:read. Do not build the URL yourself.

Monitoring view, safe to open at any time
https://overlay.ligr.live/monitoring-{key}

The example shows the production host, overlay.ligr.live. Other environments use their own overlay host, and monitoringUrl always carries the correct one.

Keep the monitoring tab visible and focused. Background tabs pause animation.

A graphic’s element can stay in the page while the graphic is hidden. Do not use DOM presence to check visibility.

Use monitoring- for every check of your own. The production- URL of the same key belongs to the vision mixer. One production session can hold an overlay at a time. Opening that URL fails while the mixer holds the session. If the mixer page stops, your page can take the session, and the mixer then cannot load the overlay. A production session on any overlay also opens a graphics billing session, and it reports ad metrics when it shows an ad. A monitoring view does neither.

A command can answer 200 for a graphic that never appears. The graphic loads, and its own visibility never turns on. Check these in order.

  • The overlay uses manual mode. See Manual mode above.
  • The theme version you activated holds the graphic version you published.
  • A Rive graphic binds its artboard visibility to the reserved hide variable. A graphic that binds visibility to a variable of its own accepts every command and never appears. See How it works.
  • A code graphic declares each variable you send in its manifest. See Graphics commands for what happens to a value the graphic does not declare.

An overlay can follow another overlay. The follower shows what the controller shows. Send commands to the controller. The API applies the state to the controller and to every follower in one write. A command sent to a follower fails. The dashboard calls the controller the leader overlay. Set it in the Leader Overlay field of the overlay settings.

IdWhere you get it
overlayIdA match with include=o, or create an overlay
graphicUuid and graphic nameFor a theme your organization owns, GET /v2/themes/{themeId}/code-graphics or GET /v2/themes/{themeId}/rive-graphics returns graphicId and name. For a linked or public theme, GET /v2/control-rooms/{roomId}/presets returns the graphicId of each preset
presetIdPOST or GET /v2/control-rooms/{roomId}/presets
competitionThemeSettingIdPOST or GET /v2/competitions/{competitionId}/theme-profiles
Data source aliasExternal data sources

To list every preset of a room with its id, its graphic UUID and its configured values, call GET /v2/control-rooms/{roomId}/presets. Find the room with GET /v2/control-rooms?themeId={themeId}.

Find the overlays of a match
curl 'https://api.ligr.live/rest/v2/matches/1188213?include=o' \
-H 'Authorization: Bearer YOUR_READ_KEY'

The match list does not return overlays. List the matches of a competition, then read each match with include=o.

List the matches of a competition
curl 'https://api.ligr.live/rest/v2/matches?competitionId=4821&limit=50&offset=0' \
-H 'Authorization: Bearer YOUR_READ_KEY'

Every command returns the overlay id and the full manualGraphicState. The state is a map keyed by graphic UUID. Each entry holds the variableValues in force. An entry that a preset set also holds the preset id.

Response
{
"overlayId": 2300003,
"manualGraphicState": {
"8efdf988-1f4d-43ac-873b-06b9b4f3e379": {
"_ligr_presetId": 1091,
"variableValues": { "CustomText": "Centre Court", "hide": false }
}
}
}

Keys that start with _ligr_ are server bookkeeping. Read them if you want. Never send them.