Skip to content

Graphics commands

POST /v2/overlays/{overlayId}/graphics/commands fires one command. Each command except hideAll targets 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.

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" }
}'
FieldRequiredMeaning
commandyesshow, update, hide or hideAll
graphicUuidone of twoThe UUID of the graphic. It must be a graphic of the theme of the overlay
nameone of twoThe name of the graphic in the theme of the overlay. The server resolves it to the UUID
variableValuesnoA 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.

CommandEffect on the graphic
showThe graphic is visible with the variableValues you send
updateThe same as show. The graphic is visible with the values you send
hideThe graphic is hidden. Its last values stay in the state
hideAllEvery 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. A code graphic reads that default in controlVariableData. Its controlVariables hold only the values you sent.

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" }

A graphic declares its control variables in the theme. Each variable has a name, a type and a default. For a theme your organization owns, GET /v2/themes/{themeId}/code-graphics/{graphicId} and GET /v2/themes/{themeId}/rive-graphics/{graphicId} return them. GET /v2/control-rooms/{roomId}/presets lists the variables that each preset exposes, with the configured values.

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. A Rive graphic ignores it. A code graphic receives it in controlVariables.

StatusCause
400No graphicUuid and no name, or the overlay has no theme so name cannot resolve
403The key lacks overlays:write, or the overlay belongs to another organization
404The overlay does not exist, 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 is the overlay id and the full manualGraphicState, keyed by graphic UUID. See The state you get back. The API also sends the same state to the dashboard and to every open browser source.