Graphics commands

POST /v2/overlays/{overlayId}/graphics/commands fires one command on one graphic. You name the graphic and you send the variable values. The server applies nothing else.

Use Presets instead when you want the values an operator configured. That endpoint is POST /v2/overlays/{overlayId}/control-room/graphics, and it takes action with presetId rather than command with graphicUuid. Both write the same state. The Rive import walkthrough uses the preset form; see Import through REST.

The request

Show a graphic with values

curl -X POST 'https://api.ligr.live/rest/v2/overlays/2300003/graphics/commands' \
  -H 'Authorization: Bearer YOUR_WRITE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "show",
    "graphicUuid": "8efdf988-1f4d-43ac-873b-06b9b4f3e379",
    "variableValues": { "CustomText": "Centre Court" }
  }'

Field	Required	Meaning
command	yes	show, update, hide or hideAll
graphicUuid	one of two	The UUID of the graphic. It must be a graphic of the theme of the overlay
name	one of two	The name of the graphic in the theme of the overlay. The server resolves it to the UUID
variableValues	no	A map of variable name to value. Values are strings, numbers, booleans or null

hideAll takes no target. Every other command needs graphicUuid or name. If you send both, graphicUuid wins. If you send neither, the response is 400.

name is the human name of the graphic, as the theme shows it. Do not pass a UUID in name.

What each command does

Command	Effect on the graphic
show	The graphic is visible with the variableValues you send
update	The same as show. The graphic is visible with the values you send
hide	The graphic is hidden. Its last values stay in the state
hideAll	Every graphic on the overlay is hidden. Media playback stops

show and update replace the variable values of the graphic. They do not merge with the values in force. Send the complete set on every call. A variable you omit falls back to its default in the graphic.

Do not send hide in variableValues. The command sets it.

Update the score on a visible scoreboard

{ "command": "update", "name": "Scoreboard", "variableValues": { "scoreA": 1, "scoreB": 0 } }

Hide one graphic

{ "command": "hide", "graphicUuid": "8efdf988-1f4d-43ac-873b-06b9b4f3e379" }

Clear the screen

{ "command": "hideAll" }

Variable values

A graphic declares its control variables in the theme. Each variable has a name, a type and a default. GET /v2/control-rooms/{roomId}/presets lists them per graphic, with the configured value.

Send the JSON type that matches the variable type: boolean, number, string, enum, and entity references such as team, player and fact. See Control variable types for the full catalogue.

A value you send for a variable the graphic does not declare is stored and ignored.

Errors

Status	Cause
400	No graphicUuid and no name, or the overlay has no theme so name cannot resolve
403	The key lacks overlays:write
404	The overlay belongs to another organization, or the theme of the overlay has no graphic with that graphicUuid or name

The command fails on an overlay that follows another overlay. Send it to the controller. See Linked overlays.

The response

The response is the overlay id and the full manualGraphicState, keyed by graphic UUID. See The state you get back. The dashboard and every open browser source receive the same state at the same moment.