Presets

POST /v2/overlays/{overlayId}/control-room/graphics fires one preset. A preset is one button in a control room. The server resolves the graphic the preset points at, applies the values the operator set on the preset, then applies your overrides on top.

Use Graphics commands instead when you own every value.

The request

Show a preset

curl -X POST 'https://api.ligr.live/rest/v2/overlays/2300003/control-room/graphics' \
  -H 'Authorization: Bearer YOUR_WRITE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "action": "show", "presetId": 1091 }'

Field	Required	Meaning
action	yes	show, update or hide
presetId	yes	The numeric id returned by preset creation or listing
variableValues	no	Overrides. A value here wins over the value on the preset

update sends new values to a preset graphic that is already on air. The live values become the preset values plus your variableValues, the same as a show. If the graphic is not on air, update returns 400 and changes nothing. Use show first. update writes the same command as an update through Graphics commands, and also records the preset id. For hideAll, use Graphics commands.

Show a preset and override one value

{ "action": "show", "presetId": 1091, "variableValues": { "CustomText": "Centre Court" } }

Update a preset that is on air

{ "action": "update", "presetId": 1091, "variableValues": { "CustomText": "Court 2" } }

Hide a preset

{ "action": "hide", "presetId": 1091 }

How values are resolved

The values in force after show come from three layers. A later layer wins.

1. The defaults of the graphic in the theme. The server does not copy these into the state. The renderer reads them at draw time.
2. The values the operator set on the preset. Only variables the preset exposes carry a value.
3. Your variableValues.

So a show with no variableValues shows exactly what the button shows. A show with overrides changes only the variables you name.

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

Extensions

A control room can define a preset as an extension of a base preset. An example is a lower-third variant that adds a line to the base lower-third. The layering is a control room setting. Fire the extension preset by id and the server does the rest.

• show on an extension shows it over the base and keeps the base values.
• hide on an extension reverts the graphic to the base preset.
• hide on a base preset hides the graphic, extension included.

Errors

Status	Cause
400	action is not show, update or hide, or presetId is missing
400	update targets a preset graphic that is not on air
403	The key lacks overlays:write
404	The overlay or the preset belongs to another organization, or the preset was deleted

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. The entry for the graphic carries _ligr_presetId with the preset you fired. See The state you get back.

Where to find a preset id

Call GET /v2/control-rooms/{roomId} with themes:read to read the room, its theme, and every preset with its graphic name and exposed variables. Call GET /v2/control-rooms/{roomId}/presets to list preset IDs, graphic IDs, sections, and configured values. Use GET /v2/control-rooms?themeId={themeId} to discover the room.

Create a preset with POST /v2/control-rooms/{roomId}/presets and themes:write. Send sectionId, graphicId, name, optional variableValues keyed by manifest variable name, and optional exposeVariables. exposeVariables names fact, stat, team, player and match variables that the operator picks live. The API reads the active published graphic manifest and creates the preset’s internal structure. Change a preset with PUT /v2/control-rooms/{roomId}/presets/{presetId}: rename it, move it to another section, or replace its variable set. Every preset response lists exposedVariables. See Set up through REST for the complete sequence.

The control room in the dashboard shows the same presets as buttons.