Overview

An overlay is the per-match graphics session. It is the browser source that your vision mixer loads. Everything you fire over REST lands on an overlay.

Browser source, 1920×1080

https://overlay.ligr.live/production-3b2b1c0e-…

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

Endpoint	Use it when
POST /v2/overlays/{overlayId}/graphics/commands	You address a graphic by name or UUID and you own every variable value. See Graphics commands.
POST /v2/overlays/{overlayId}/control-room/graphics	You 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.

What a control room is

A control room is the button layout an operator uses during a match. Your organization owns it, and it uses one theme. 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.

Set up a code graphic control room

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 any browser rendering library.

Manual mode

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, the overlay follows a controller, or its ad type is Free. For Free overlays, change the ad type to Brands or No Brands in overlay settings before enabling manual mode. 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.

Check what is on screen

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 exists only while it is shown. 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, so opening that URL during a match can take the session from the mixer, or fail because the mixer already holds it. A production session also counts against ad metrics and the account balance. 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.

Linked overlays

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.

Where the ids come from

Id	Where you get it
overlayId	A match with include=o, or create an overlay
graphicUuid and graphic name	GET /v2/themes/{themeId}/code-graphics or GET /v2/themes/{themeId}/rive-graphics returns graphicId and name
presetId	POST or GET /v2/control-rooms/{roomId}/presets
competitionThemeSettingId	POST or GET /v2/competitions/{competitionId}/theme-profiles
Data source alias	External data sources

To list every preset of a room with its UUID and 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'

Find the overlays of every match in a competition

curl 'https://api.ligr.live/rest/v2/matches?competitionId=4821&include=o&page=1&pageSize=50' \
  -H 'Authorization: Bearer YOUR_READ_KEY'

The state you get back

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 and the preset that set them.

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.