Skip to content

Build a game plan

A game plan tells overlay automation what to show during a match. It holds playlists and triggers.

  • A playlist is a list of steps. Each step shows a graphic, hides graphics, or plays an ad or a media item at an offset in seconds.
  • A trigger starts a playlist. A live trigger fires on a match fact, such as GOAL, and runs a live playlist. A break trigger fires on a break event, such as aboutToStart, and runs a break playlist.

This guide builds a football plan that shows the scorebug after a goal, then copies the plan for a second competition. It needs a key with the themes:write scope and a theme that your organization owns.

  1. Find the graphic.

    Terminal
    curl 'https://api.ligr.live/rest/v2/themes/203' \
    -H "Authorization: Bearer $LIGR_API_KEY"

    Keep the graphicId and the name of the graphic that the playlist shows. This guide uses the scorebug, 9cfd8a5a-3082-4a69-810f-f3b1f566c225.

  2. Create the game plan.

    Terminal
    curl -X POST 'https://api.ligr.live/rest/v2/game-plans' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{ "name": "League match", "themeId": 203, "sport": "football" }'
    201 Created
    {
    "id": 512,
    "name": "League match",
    "sport": "football",
    "themeId": 203,
    "updatedAt": "2026-10-21T09:12:44.120Z",
    "playlists": [],
    "triggers": []
    }

    The theme must support the sport. Keep the id.

  3. Add a playlist.

    Terminal
    curl -X POST 'https://api.ligr.live/rest/v2/game-plans/512/playlists' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "name": "Goal",
    "scope": "live",
    "priority": 1,
    "transitions": [
    { "id": "4f0c2a8e-0d43-4a52-9a43-0b6e1f6f2a10", "type": "action", "name": "Hide All", "code": "action:hideAll", "offset": 0 },
    {
    "id": "363bfff6-6898-4687-9286-ec14202f9212",
    "type": "graphic",
    "name": "Scorebug",
    "code": "Scorebug",
    "offset": 1,
    "graphicUuid": "9cfd8a5a-3082-4a69-810f-f3b1f566c225",
    "desiredState": { "updateType": "update", "variableValues": { "StatOne": "shots" } }
    }
    ]
    }'
    201 Created
    {
    "id": 9031,
    "name": "Goal",
    "scope": "live",
    "priority": 1,
    "guard": null,
    "transitions": [
    { "id": "4f0c2a8e-0d43-4a52-9a43-0b6e1f6f2a10", "type": "action", "name": "Hide All", "code": "action:hideAll", "offset": 0 },
    { "id": "363bfff6-6898-4687-9286-ec14202f9212", "type": "graphic", "name": "Scorebug", "code": "Scorebug", "offset": 1, "graphicUuid": "9cfd8a5a-3082-4a69-810f-f3b1f566c225", "desiredState": { "updateType": "update", "variableValues": { "StatOne": "shots" } } }
    ],
    "sortOrder": null
    }

    The first step hides every graphic. One second later, the second step shows the scorebug. Give each step a new UUID as its id. desiredState is JSON that the graphic reads. To see the keys your graphics use, read a plan that you built in the dashboard with GET /v2/game-plans/{gamePlanId}.

    The scope of a playlist cannot change. A live playlist runs only on live triggers.

  4. Add a trigger.

    Terminal
    curl -X POST 'https://api.ligr.live/rest/v2/game-plans/512/triggers' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{ "playlistId": 9031, "type": "live", "group": "regular", "code": "GOAL" }'
    201 Created
    {
    "id": 20417,
    "playlistId": 9031,
    "type": "live",
    "group": "regular",
    "code": "GOAL",
    "period": null,
    "overtimeIndex": null,
    "triggerSeconds": null,
    "triggerConditions": null
    }

    Every goal fact now runs the Goal playlist. The playlist must belong to the same plan.

  5. Duplicate the plan.

    Terminal
    curl -X POST 'https://api.ligr.live/rest/v2/game-plans/512/duplicate' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{ "name": "Cup match" }'

    The copy gets new playlists and new triggers. Each copied trigger runs the copied playlist, so a change to the copy does not change the original. Without a name, the copy is named League match (Copy). Send "includeAdSlots": true to copy the ad slots of each playlist too.

  6. Read the copy.

    Terminal
    curl 'https://api.ligr.live/rest/v2/game-plans/513' \
    -H "Authorization: Bearer $LIGR_API_KEY"

    The response lists the playlists in plan order with their steps, then the triggers. Each trigger names the copied playlist in playlistId.

TaskRequest
Rename the plan or reorder its playlistsPATCH /v2/game-plans/{gamePlanId} with name, playlistOrder, or both
Change the steps, name, priority or guard of a playlistPATCH /v2/game-plans/{gamePlanId}/playlists/{playlistId}
Change the event, period or playlist of a triggerPATCH /v2/game-plans/{gamePlanId}/triggers/{triggerId}

transitions in a playlist update replaces the whole list. Send every step that the playlist keeps.

A trigger update stores the trigger as a new row. The response carries the new id, and the old id stops working. Use the returned id for the next update.

The REST API cannot delete a game plan, a playlist or a trigger. Use the dashboard for these tasks, and to assign the plan to a competition theme.