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.
The request
Section titled “The request”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
Section titled “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. 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.
{ "command": "update", "name": "Scoreboard", "variableValues": { "scoreA": 1, "scoreB": 0 } }{ "command": "hide", "graphicUuid": "8efdf988-1f4d-43ac-873b-06b9b4f3e379" }{ "command": "hideAll" }Variable values
Section titled “Variable values”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.
Errors
Section titled “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, or the overlay belongs to another organization |
| 404 | The 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
Section titled “The response”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.