Skip to content

Changelog

One entry per change to the public API, webhooks or Graphics SDK. Subscribe with theRSS feed.

API 0.0.49changed

Sending the current input or destinations keeps an automatic selection

  • POST /v1/streams/{streamSettingsId} with the current inputId no longer moves inputSelection to specific. A different inputId still does.
  • The same rule applies to destinationIds. The order of the ids does not matter.
  • To pin the current input or destinations, send inputSelection or destinationSelection set to specific.
API 0.0.48changed

Creating a stream requires a name

  • POST /v1/streams now requires name. A body without name answers 400 with the missing field. Before, it answered 500 and created no stream.
  • Updates do not change. POST /v1/streams/{streamSettingsId} without name keeps the current name.
API 0.0.47addedchanged

Update competitions and set match rules over REST

  • Added PATCH /v1/competitions/{competitionId}. It changes name, gfxName, shortName, age, gender, gradeId and matchConfig. Omitted fields keep their stored value. The route needs the competitions:write scope. It is beta: its responses carry X-Ligr-Beta: true.
  • matchConfig holds the match rules that every match of the competition inherits: the periods, the clock and the data coverage. A matchConfig in the body applies onto the stored one. A key that you omit keeps its value. Send null for rules, periods.overtime, periods.shootout or dataCoverage.players to remove it. If the config fails the check, the route returns 400 with the reason and changes nothing.
  • Competition responses now include matchConfig.
  • POST /v2/matches accepts config and description. POST /v2/matches/{matchId} accepts config, description, homeTeamKitKey, awayTeamKitKey, homeTeamFormation and awayTeamFormation. A match config applies onto the competition matchConfig for that match only.
  • GET /v2/matches/{matchId} now returns config, the match rules that apply to the match, and the fields above.
  • GET /v1/teams/{teamId} now returns kits, the kit colours of the team. A kit that the team does not set comes from its club. PATCH /v1/teams/{teamId} and the team logo routes return kits too.
  • Changed The answer of POST /v2/matches and POST /v1/matches lists the overlays and streams that the competition templates made for the new match. Before, overlays and streams were always empty. A competition without templates still gives empty lists.
API 0.0.47added

Highlight rules and moments over REST (beta)

You can now make clips with an API key. Before, only the dashboard set the highlight rules of a competition, so a competition set up through REST made no clips, even with generateHighlights on.

  • GET /v2/competitions/{competitionId}/highlight-rules lists the rules of a competition. PUT /v2/competitions/{competitionId}/highlight-rules/{factName} creates or replaces the rule for one event, with lead, lag and conditions. DELETE on the same path removes it. Settings that only the dashboard edits, such as auto-posting, keep their value. These routes need the competitions:read or competitions:write scope.
  • POST /v2/matches/{matchId}/moments adds a manual moment to a match and cuts its clip from the recording of the match. It answers { factId, highlightId }. With no recording that covers the moment, it answers 409 NO_RECORDING and creates nothing. Send highlight: false to save the moment only. The route needs the matches:write scope.
  • A competition with two rules for one event, saved in the dashboard, answers 409 HIGHLIGHT_RULE_AMBIGUOUS to PUT and DELETE for that event.

The routes are beta. See Make clips.

API 0.0.47addedchanged

Use linked and public themes over REST

  • An API key can now use a linked or a public theme in theme profiles and control rooms. Before, it could use only a theme that its organization owns.
  • A key can use a theme when your organization can use the theme in the dashboard, and the theme is an external Rive or code theme. Your organization owns the theme, LIGR linked the theme to your organization, or the theme is public. Inbuilt themes, the legacy themes built into LIGR, are not available through REST.
  • GET /v2/themes?access=usable lists these themes. Without access, or with access=owned, the list holds only the themes your organization owns, as before.
  • Each item of GET /v2/themes now has access: owned, linked or public.
  • These routes now accept a linked or public theme: create, list, read and update theme profiles under /v2/competitions/{competitionId}/theme-profiles, create, list and read control rooms under /v2/control-rooms, and create sections and presets in those rooms.
  • Another organization’s private theme still answers 404. A theme without an active version still answers 400 on the routes that need one.
  • Only a theme your organization owns accepts changes. GET /v2/themes/{themeId} and the routes below it answer 404 for a linked or public theme, as before.

See Themes you can use.

API 0.0.46added

A Rive write warns when an enum binding reads a theme variable that the enum does not list

  • A binding on a Rive enum property can read an enum theme variable, for example $t.Typeface. Rive ignores a value that its enum does not list, so on air the property keeps its last value. Before, the API saved such a binding and said nothing.
  • The operation routes under /v2/themes/{themeId}/rive-graphics/{graphicId} and POST /v2/themes/{themeId}/rive-graphics/candidates/{candidateId}/graphics now answer enumMismatches when the draft has such a binding. Each entry names the binding, the theme variable, the options that the Rive enum does not list, and the enum values that no option sets.
  • The write still succeeds. A draft with no such binding gets no enumMismatches.
  • ligr graphic rive replace, ligr graphic rive bind set and ligr graphic rive push print the warning. The MCP bindings and files answers include enumMismatches. See Edit through REST.
API 0.0.45added

A Rive replacement lists the bindings that it removed

  • When POST /v2/themes/{themeId}/rive-graphics/candidates/{candidateId}/graphics replaces a Rive asset, the response has droppedBindings. It lists the IDs of the draft’s bindings that the new file does not have. The replacement removed those bindings with their expressions. Before, the response did not name them.
  • A repeated attachment of the same candidate returns the same list. A response that creates a graphic has no droppedBindings.
  • ligr graphic rive replace prints the removed bindings. The MCP files replace answer includes droppedBindings. See Import through REST.
API 0.0.45changed

An unknown reference error lists every unknown reference

  • 422 UNKNOWN_REFERENCE has one entry in details for each unknown $v or $u reference in the Rive configuration. Before, it named only the first one.
  • A Rive replacement validates the expressions that it keeps from the draft. You can now fix every unknown reference before you start the next replacement import. See Import through REST.
  • The error code and the HTTP status stay the same.
API 0.0.45changed

New stream inputs default to 500 ms latency

POST /v1/streams/inputs without latencyMs now creates the input with a 500 ms receive latency. Before this change, the default was 1000 ms. The dashboard uses the same default for new inputs.

Existing inputs keep their latency. To set a latency, send latencyMs. It is one of 20, 50, 100, 150, 250, 350, 500, 1000, 1500, 2000, 2500 or 3000.

The receive latency delays the picture by the same amount. A longer latency lets an SRT input resend more lost packets on a slow or lossy link. See Configure a stream.

API 0.0.45added

Theme settings over REST

PATCH /v2/themes/{themeId} changes the settings of a theme. It takes name, requireRiveSource and rendererRelease. Omitted fields keep their stored value. The route needs the themes:write scope.

  • requireRiveSource: true refuses Rive imports without editable source (.rev or project ZIP) with SOURCE_REQUIRED.
  • rendererRelease sets the Rive renderer release of the theme’s working graphics: { "policy": "latest" }, or { "policy": "pinned", "release": "2.44.0-r1" }. A published graphic version keeps the release it recorded.

POST /v2/themes now also takes requireRiveSource and rendererRelease. POST /v2/themes, GET /v2/themes/{themeId} and PATCH /v2/themes/{themeId} return requireRiveSource, rendererRelease and public.

No setting on this route changes what an overlay shows. Overlays render the active theme version.

API 0.0.45added

Theme responses include the sports

POST /v2/themes and GET /v2/themes/{themeId} now return sports, the sport keys the theme supports. Before, only GET /v2/themes returned them. Use the answer to confirm the sports a new theme saved.

API 0.0.41added

Guide for competition colours with theme profiles

  • Added the guide Give each competition its own colours.
  • The guide defines a colour theme variable, sets it per competition with POST /v2/competitions/{competitionId}/theme-profiles and themeVariableValues, and binds it in a Rive expression as $t.<name>.
  • No API change.
API 0.0.40added

Game plans over REST (beta)

You can now build automation game plans with an API key. GET /v2/game-plans lists the plans of your organization, and POST /v2/game-plans creates a plan on a theme you own. GET /v2/game-plans/{gamePlanId} returns the plan with its playlists, their steps, and its triggers. PATCH /v2/game-plans/{gamePlanId} renames the plan and reorders its playlists.

POST /v2/game-plans/{gamePlanId}/playlists and POST /v2/game-plans/{gamePlanId}/triggers add a playlist and a trigger. PATCH on /playlists/{playlistId} and /triggers/{triggerId} changes them. POST /v2/game-plans/{gamePlanId}/duplicate copies a plan with its playlists and triggers, and each copied trigger runs the copied playlist.

The routes need the themes:read or themes:write scope. They are beta. See Build a game plan.

API 0.0.39changeddeprecated

The graphics CLI is now ligr graphic, from @ligr/cli on npm

  • The CLI is now the npm package @ligr/cli. Install it with npm i -g @ligr/cli. It gives you the ligr command.
  • The graphics commands are under ligr graphic. For example, run ligr graphic push, ligr graphic rive import <file> or ligr graphic mcp. The options and the --json output do not change.
  • To run the CLI once without an install, use npx @ligr/cli graphic <command>. For example, run npx @ligr/cli graphic init my-graphic.
  • ligr-graphic is deprecated. npx ligr-graphic <command> still runs ligr graphic <command> and prints one deprecation line on stderr. A later release removes it. Replace ligr-graphic <command> with ligr graphic <command>.
  • For an MCP client, change the server command from npx ligr-graphic mcp to npx @ligr/cli graphic mcp.
  • New projects pin the CLI as @ligr/cli. To upgrade a project, run npm uninstall @ligrsystems/graphics-cli, then npm i -D @ligr/cli. Change the SDK URL in package.json to v0.6.0.
  • @ligrsystems/graphics-sdk 0.6.0 has no changes. The SDK and CLI versions stay equal.
API 0.0.42added

Entity control variables when you create a Rive graphic

  • POST /v2/themes/{themeId}/rive-graphics/candidates/{candidateId}/graphics accepts the entity types team, player, match, fact, stat, teamStat, period, set, round and court in configuration.controlVariables[].type. Before, it accepted only string, number, boolean and enum, and an entity type answered 400 Validation Failed.
  • The server adds the reference data shape as dataSchema. Bind the selected entity with an expression, for example $v.player.data.lastName.
  • You can now create a graphic with its entity controls and bindings in one call. See Import through REST.
API 0.0.40added

Rive expressions can use Date, NaN and Infinity

  • Rive expressions can use Date, NaN and Infinity. Before this release, each one was undefined and new Date() stopped the expression.
  • Date with arguments, Date.UTC and Date.parse work as in JavaScript, for example new Date(2026, 9, 21 + 14).getDate().
  • Date.now(), new Date() and Date() with no arguments return the time of the evaluation. A binding evaluates again only when its data changes, so the value does not tick. In the video editor and in exports, it is the time of the render.
  • See Dates.
API 0.0.44changed

A Rive replacement updates control variables

  • POST /v2/themes/{themeId}/rive-graphics/candidates/{candidateId}/graphics accepts configuration.controlVariables when it replaces a Rive asset. Before, a replacement with control variables answered 422 INVALID_CONFIGURATION.
  • A submitted control variable updates the control variable that has the same name. It keeps its ID. The replacement sets the submitted type, options, default, description and exit mode.
  • If you do not send a default, the control variable keeps its default. If the new type or options make that default invalid, the replacement removes it.
  • Control variables that you do not send stay unchanged. A new name adds a control variable.
  • User expressions and layout on a replacement still answer 422 INVALID_CONFIGURATION. See Import through REST.
API 0.0.38changed

A Rive replacement keeps enum binding expressions

  • When you replace a Rive asset and the values of a Rive enum change, the enum binding keeps its expression. Before, the replacement cleared the expression, the default and the value of that binding.
  • The replacement drops a default or a value that the new enum values do not list.
  • A binding whose property changes type still loses its configuration.
  • A bindings override in the replacement request still wins. See Import through REST.
API 0.0.43addedchanged

Update a theme profile over REST

PATCH /v2/competitions/{competitionId}/theme-profiles/{profileId} changes a theme profile. It takes name, defaultControlRoomId, themeVariableValues and automationGamePlanId. Omitted fields keep their stored value. themeVariableValues replaces the stored list. null removes the default control room or the game plan. The game plan must belong to your organization and use the profile theme and the competition sport. The route needs the competitions:write scope.

Theme profile responses now include automationGamePlanId.

A null value in themeVariableValues now stays null, so the variable uses the theme default. Before this change, POST on the same path turned null into false. It then stored false for a boolean variable and answered 400 for the other variable types.

LIGR does not push a profile change to an open overlay. Reload the overlay page to show the new values. See Give each competition its own colours.

API 0.0.36changedbreaking

Competition grades route is removed

  • Removed GET /v1/competitions/grades. A request to that path now answers 400, because the API reads grades as a competition id.
  • No route replaces it. Omit gradeId when you create a competition or a team. The competition or team then gets the Unknown grade.
API 0.0.38changed

GET /v1/competitions returns competitions in id order

GET /v1/competitions now returns competitions ordered by id, so pages do not repeat or skip a competition.

Before this change, the list had no fixed order. If a competition changed between two page requests, the next page could repeat it and skip another competition.

API 0.0.38addedchanged

Copy a Rive graphic into another theme

  • POST /v2/themes/{themeId}/rive-graphics/copies copies a working Rive graphic from another theme into this theme. Send sourceThemeId, sourceGraphicId and a new name. Your key must be able to read the source theme and write this theme.
  • The copy keeps the control variables, data bindings, user expressions, assets, schemas and settings. If the expressions use theme variables, add those variables to this theme first.
  • organizationId on a Rive graphic can now be null. null marks a theme that LIGR owns. Your organization’s themes always carry your organization id.
API 0.0.33changed

A new fact sends match.update

  • A new fact now sends a match.update webhook after its fact.create and summary.update. Before, a new fact sent no match.update, and the new score, clock and period arrived only in summary.update.
  • When LIGR adds several facts at once, for example from one provider update, it sends one match.update for the batch.
  • A MATCH_CANCELLED, MATCH_ABANDONED or MATCH_FINISHED_EARLY fact now sends a match.update with finishedStatus set.
  • A webhook that subscribes to match receives more events during a live match. See Events.
API 0.0.35changed

REST rate limits count per organization

  • LIGR counts each REST request with a valid API key against the organization that owns the key. Before, LIGR counted all requests from one client IP address together.
  • All API keys of one organization share one budget. A new key does not add budget.
  • Organizations behind one IP address no longer share one budget.
  • An over-limit request with a valid API key gets the 429 body { "message": "Organization has made too many requests" }. Before, the body was { "message": "Api key has made too many requests" }.
  • A request without a valid API key still counts against its client IP address. Its 429 body is { "message": "Client IP address has made too many requests" }.
  • The limits, the RateLimit headers and observe mode do not change. See Rate limits.
API 0.0.34changed

Deleting a stream input or destination in use answers 409

DELETE /v1/streams/inputs/{inputId} and DELETE /v1/streams/destinations/{destinationId} refuse an input or a destination that a running stream uses. These deletes answered 500 before. They now answer 409 with the code IN_USE_BY_STREAM. details names each stream that uses the input or the destination, by its id. Stop the stream, then delete again. For a destination, you can also remove it from the stream first.

API 0.0.37added

The webhook event log shows the payload and the response body

  • In the dashboard Event Logs tab of a webhook, select View on a row to see the payload and the response body of that attempt.
  • The payload is the exact request body that LIGR sent, for a delivered attempt and for a failed one. A delivered attempt logged before this release shows the entity record that LIGR read instead.
  • A JSON body is formatted for reading. A body larger than 16 KiB stops at 16 KiB and shows a “Truncated” note.
  • LIGR keeps a response body only for a failed attempt that got a response. See Delivery health & logs.
API 0.0.32changedbreaking

Graphics CLI 0.5.0 removes the local dev harness

  • ligr-graphic dev is removed. The CLI no longer runs a local harness, a local server or a scenario cache in .ligr/.
  • The templates no longer have a dev script. The React template no longer has a start script.
  • Test a graphic on the LIGR platform. Run npx ligr-graphic push, then open the graphic in the dashboard code viewer. Show it on the preview overlay of a test match before you use it on air. See Test and troubleshoot.
  • To upgrade, change both package URLs in package.json to v0.5.0 and delete the dev script. Delete the .ligr/ folder.
  • @ligrsystems/graphics-sdk 0.5.0 has no changes. The SDK and CLI versions stay equal.
API 0.0.32changedbreaking

REST API keys require organization-level API access

Every REST API key now requires its organization to have the api_access entitlement through an active product. This applies to existing scoped and legacy keys. Without the entitlement, requests return 403 with code: "API_ACCESS_REQUIRED", even when the key is valid and has the required route scope.

Rollout order: grant the api_access entitlement to organizations with existing REST integrations and verify that access is active before enabling enforcement. Enabling enforcement first interrupts those integrations until their organizations are granted access. Existing keys do not need to be rotated.

See Authentication and Errors.

API 0.0.31added

Code graphics can declare a renderer

  • A code graphic’s runtime.renderer is optional. When you set it, it must be cpu or gpu. Any other value fails validation with runtime.renderer must be "cpu" or "gpu".
  • ligr-graphic validate checks the same rule before you push, from CLI 0.5.0.
  • Graphics without runtime.renderer keep working as before.
API 0.0.30changed

Graphics CLI 0.4.1 fixes import status and lock messages in the MCP server

  • files action status answers cancelled for an import that files action cancel stopped. Before, it answered that the server did not start the import.
  • files actions select, repair and cancel on a cancelled or expired import tell you to start the import again.
  • A 409 LOCKED error names the lock holder once. Before, the holder name showed in the message and again at the end of the line.
  • @ligrsystems/graphics-sdk 0.4.1 has no changes. The SDK and CLI versions stay equal.
API 0.0.29addedchanged

Graphics CLI 0.4.0 adds an MCP server for Rive graphics (beta)

  • ligr-graphic mcp starts a Model Context Protocol server on stdio. An agent, for example Claude Desktop, Claude Code or Codex, uses it to edit a Rive graphic. Set LIGR_API_KEY and LIGR_MCP_ROOT.
  • The server has 14 tools:
    • read tools: list_rive_graphics, get_graphic_state;
    • the edit session: edit_session;
    • edit tools: bindings, list_items, control_variables, user_expressions, settings;
    • theme tools: theme_variables, data_sources;
    • file tools: files, images;
    • release tools: publish, check.
  • Every graphic write needs an edit session. An open builder goes read-only and shows each change live. edit_session end with discard restores the draft.
  • publish never activates a theme version. Activate it in the dashboard.
  • The server reads and writes local files only inside LIGR_MCP_ROOT. Without it, the server uses the folder it started in. It refuses every file action when that folder is /, the home folder, or a folder that holds the home folder.
  • The MCP server has no tool that deletes a theme variable or a data source. Use the dashboard or the CLI.
  • Changed for all CLI commands:
    • an id that holds / or \ is refused;
    • the CLI no longer follows HTTP redirects;
    • API calls time out after 120 seconds and file transfers after 600 seconds;
    • upload and download URLs must use https.
  • @ligrsystems/graphics-sdk 0.4.0 has no changes. The SDK and CLI versions stay equal.
API 0.0.27changed

Graphics CLI 0.3.1 warns about deprecated Rive bindings

  • ligr-graphic rive asset set, expose and unexpose print a warning. Asset bindings are deprecated. Bind an image view-model property with ligr-graphic rive bind instead.
  • ligr-graphic rive input set prints a warning. Input bindings are deprecated. Bind a view-model property with ligr-graphic rive bind instead.
  • @ligrsystems/graphics-sdk 0.3.1 has no changes. The SDK and CLI versions stay equal.
API 0.0.26changed

The Graphics Builder locks a Rive graphic on the first edit

  • The dashboard Graphics Builder takes a Rive graphic’s edit lock on the first edit, not when it opens. A builder tab that is only open no longer makes REST and CLI writes answer 409 LOCKED.
  • The builder releases the lock after 5 minutes with no edit, or when its tab closes.
  • See Edit through REST.
API 0.0.28added

Rive rename, layer, revisions and thumbnail over REST (beta)

  • PATCH /v2/themes/{themeId}/rive-graphics/{graphicId}/user-expressions/{id} accepts name to rename a user expression. The API does not change expressions that read the old name. The response lists them in staleReferences.
  • PATCH …/{graphicId}/settings accepts layer, an integer from -100000 to 100000. A higher layer covers a lower one. Without a layer, a Rive graphic has depth 100 and a code graphic 200. null clears it. GET …/{graphicId} returns it as stateMachine.layer and leaves it out when unset. It also returns organizationId.
  • GET …/{graphicId}/revisions lists every runtime revision of the graphic, newest first. GET …/{graphicId}/files/{kind} accepts revisionId to download one exact revision. version is still required. If you send revisionId, it wins.
  • PUT …/{graphicId}/thumbnail sets the thumbnail from an image that you uploaded with POST …/rive-graphics/images.
  • A write no longer fails on a $v or $u reference that was already unknown before the write. A reference to a new unknown name still answers 422 UNKNOWN_REFERENCE.
  • POST …/{graphicId}/versions, POST …/rive-graphics/uploads with a target, and POST …/candidates/{candidateId}/graphics accept the x-ligr-edit-session header.
  • DELETE …/edit-sessions/{sessionToken}?outcome=discard restores the draft as it was at the session start, or at the last publish, replace or thumbnail in the session.
  • See Edit through REST.
API 0.0.25added

Choose the Rive runtime for themes and graphics

  • LIGR bundles Rive web runtime 2.44.0 next to 2.41.0. Each bundled runtime is a renderer release, for example 2.44.0-r1.
  • A theme follows latest or pins one release. Set a graphic override with rendererRelease in PATCH /v2/themes/{themeId}/rive-graphics/{graphicId}/settings.
  • A published graphic version keeps the release it was published with.
  • GET /v2/themes/{themeId}/rive-graphics/{graphicId} returns rendererRelease, the release the working graphic renders with.
  • Existing themes and published graphic versions stay on 2.41.0-r1. New themes follow latest.
  • See How Rive imports work.
API 0.0.25added

Repair stale references in Rive source imports

  • A .rev import that fails on references to deleted items now shows where each problem is in the Rive editor (error.problems[].location).
  • When every problem has a proven repair, error.repair.available is true. Send POST /rest/v2/themes/{themeId}/rive-graphics/imports/{jobId}/repair to apply it, or send repair: true with preparation.
  • A ready import lists the changes in repairs. The uploaded .rev stays unchanged.
  • See Import through REST.
API 0.0.25added

Update many Rive data bindings in one request (beta)

  • PATCH /v2/themes/{themeId}/rive-graphics/{graphicId}/data-bindings changes the expression or default value of many data bindings in one save.
  • The API checks every change first. If one change fails, it saves no change.
  • See Edit through REST.
API 0.0.24changedbreaking

Rive expressions no longer have helper functions

  • The helper functions startsWith, endsWith, contains, find, findIndex, filter, map and reduce are removed from Rive expressions. No published graphic used them.
  • Use the string and array methods instead. They also work on a missing value when the data schema declares its type: $d.1.name.startsWith('A'), $d.tags.includes('live'), $d.1.squad.filter(p => p.live).
  • See Expressions.
API 0.0.24deprecatedbreaking

Rive state machine input and asset bindings are deprecated

Data bindings replace state machine input bindings and asset bindings. Bind a view-model property with PATCH data-bindings/{id}. To expose an image, use PUT data-bindings/{id}/exposure.

These routes are deprecated:

  • PATCH /v2/themes/{themeId}/rive-graphics/{graphicId}/inputs/{id}
  • PATCH /v2/themes/{themeId}/rive-graphics/{graphicId}/assets/{id}
  • PUT /v2/themes/{themeId}/rive-graphics/{graphicId}/assets/{id}/exposure
  • DELETE /v2/themes/{themeId}/rive-graphics/{graphicId}/assets/{id}/exposure

An input that has an expression keeps it. You can change or clear that expression. An input with no expression cannot get one. The request returns 422 INPUT_BINDINGS_DEPRECATED. This rule also applies to the inputs list of a Rive import or replacement configuration.

Existing asset bindings and exposures continue to work. PUT assets/{id}/file is not deprecated. Use it to supply the image of an unresolved asset.

API 0.0.22added

Publish a theme version from the command line (beta)

  • Added ligr-graphic theme publish --theme <id> to @ligrsystems/graphics-cli. It publishes one theme version and does not publish a graphic version. See Push and publish.
  • Every graphic takes its latest published version. A graphic with no published version is not in the theme version.
  • The command prints the new version, each pinned graphic version, and whether the new version is active.
  • Add --activate to set the new version active. Add --dry-run to print the version and the graphic versions, and write nothing.
  • The command uses the same POST /themes/{themeId}/versions endpoint as publish --theme-version.

Graphics creation stays in beta. Shapes can change between minor versions. See Beta status.

API 0.0.22added

Set a competition logo and watermarks over REST

POST /v1/competitions/{competitionId}/logo/uploads opens a signed upload for one PNG or JPEG logo of 500 KB or less. The logo must be exactly 300x300 pixels, the same as in the dashboard. Watermarks have no fixed size. Declare the type, the size, and the SHA-256 of the file. Upload the bytes with one PUT to the returned URL.

PUT /v1/competitions/{competitionId}/logo sets the logo from the upload. The API checks the size, the SHA-256, and the image type before it stores the logo. DELETE /v1/competitions/{competitionId}/logo removes the logo. Graphics show the logo as competitionLogo.

The primary and secondary watermarks have the same three routes under /v1/competitions/{competitionId}/watermark and /v1/competitions/{competitionId}/secondary-watermark. All nine routes need the competitions:write scope.

Competition responses now carry logoUrl, watermarkUrl, and secondaryWatermarkUrl when the competition has that image. The fields are in GET /v1/competitions, GET /v1/competitions/{competitionId}, and the image routes.

API 0.0.22added

Control room update action and full room read

POST /v2/overlays/{overlayId}/control-room/graphics accepts action: "update". The action sends the preset values and your variableValues to a preset graphic that is already on air. It returns 400 when the graphic is not on air. You no longer need the graphic UUID and /graphics/commands to change a live preset.

GET /v2/control-rooms/{roomId} now returns the theme and every preset with its graphicId, graphicName and exposedVariables. When the key has overlays:read, it also returns the overlays that use the room, each with monitoringUrl. You can check a prepared room without a dashboard login. See Set up through REST.

API 0.0.24added

Set player, team and competition images per image template over REST

GET /v1/players/{playerId}/images lists the player’s image for each player image template of your organization. Each item holds imageTemplateId, templateName, width, height, url and defaultImageUrl. url is null when the player has no image for the template.

POST /v1/players/{playerId}/images/{imageTemplateId}/uploads opens a signed upload for one PNG or JPEG file of 5 MB or less. PUT /v1/players/{playerId}/images/{imageTemplateId} sets the image from the upload. The image must have the exact pixel size of the template. Another size returns 400 IMAGE_DIMENSIONS_MISMATCH. DELETE /v1/players/{playerId}/images/{imageTemplateId} removes the image. Live overlays show the change.

Teams and competitions have the same four routes under /v1/teams/{teamId}/images and /v1/competitions/{competitionId}/images. A template of another entity type returns 400 INVALID_INPUT. The GET routes need the read scope of their entity, for example players:read. The upload, set and delete routes need the write scope, for example players:write. See Manage image templates.

API 0.0.22changed

Fact update and delete check the match

POST /v2/matches/{matchId}/facts/{factId} and DELETE /v2/matches/{matchId}/facts/{factId} now check that the fact belongs to the match in the path. If the fact belongs to another match, the API returns 404, the same as for a missing fact. The fact does not change.

Before this change, the API ignored matchId and acted on the fact of any match in your organization.

API 0.0.21changed

The overlay no longer sends SCHEMAS to code graphics

  • The ligr.gfx.v1 handshake is now HELLO, READY, then LOAD_GRAPHIC. The overlay no longer sends SCHEMAS. No graphic used it at runtime.
  • HELLO now carries { width, height } only. sport is still in every LOAD_GRAPHIC and GRAPHIC_UPDATE.
  • @ligrsystems/graphics-sdk 0.3.0 removes onSchemas and the GraphicSchemasPayload type. If your graphic passes onSchemas, remove it. A graphic built with 0.2.0 keeps working without changes.
  • Get the schemas during development: GET /v2/schemas/sports/{sport} and GET /v2/schemas/control-variables. See Data binding.
API 0.0.24added

Image template on code graphic images

Each entry in the code graphic images surface now has imageTemplateId and imageTemplateName. Use them to select an image when one entity has more than one image template, for example a Headshot and a Cutout.

The change adds fields only. Existing graphics keep working. See Images.

API 0.0.22added

Manage image templates over REST

/v1/image-templates lists, creates, reads, renames and deletes image templates. A template is a named image slot with a fixed pixel size for players, teams or competitions. List filters are entityType and sport.

GET /v1/image-templates/{imageTemplateId} returns usage: the entity images and the theme mappings that use the template. DELETE refuses a template in use with 409 IMAGE_TEMPLATE_IN_USE and the same usage.

POST /v1/image-templates/{imageTemplateId}/default-image/uploads and PUT /v1/image-templates/{imageTemplateId}/default-image set the default image with a signed upload. The image must have the exact pixel size of the template. DELETE /v1/image-templates/{imageTemplateId}/default-image removes it. Template responses carry defaultImageUrl and defaultFileId.

The routes need the new images:read or images:write scope. Legacy keys get the scope with their read or write permission. See Manage image templates.

API 0.0.23changed

Clarify competitorsType and entityType on matches

The REST reference and the guides now explain the two competitor fields on POST /v2/matches and POST /v2/matches/{matchId}. competitorsType is the match format: singles, doubles, teams or group. entityType is the kind of each row in competitors: team or player. For example, a doubles match has competitorsType: doubles and four entityType: player rows. The API behaviour does not change.

API 0.0.23added

Upload a media image and get its URL over REST

POST /v1/media/images/uploads opens a signed upload for one PNG or JPEG image of 3 MB or less. Declare the type, the size, and the SHA-256 of the file. Upload the bytes with one PUT to the returned URL.

PUT /v1/media/images creates a media image from the upload and returns its id, name, url, width and height. The url is a public CDN URL that does not change. Use it in data source rows, for example as the crest of a club that is not a team in LIGR. The image also appears in the dashboard Media section.

GET /v1/media/images lists the images in pages. DELETE /v1/media/images/{imageId} archives an image, as the dashboard does. The url of an archived image keeps working.

The routes need the new media scope: media:write to upload and archive, media:read to list. Legacy keys already have it.

API 0.0.22changed

Provider syncs keep team edits

The docs now say what happens when you edit a team that a data provider supplies. A provider team has dataProvider in GET /v1/teams/{teamId}.

Your organization has its own copy of each provider team. PATCH /v1/teams/{teamId} and the logo routes change only that copy. Other organizations that use the same provider team keep their values.

A provider sync keeps these fields:

  • name, gfxName, gfxFullName and abbreviation
  • primaryBackgroundColor, primaryTextColor, secondaryBackgroundColor and secondaryTextColor
  • age, gender, gradeId and defaultVenueId
  • the logo
  • nonPlayerStaff, with one exception

The exception: when an admin connects SPORT_RADAR_FOOTBALL to your organization, the initial load replaces nonPlayerStaff with the provider manager. Set the staff again after the initial load if you need other values.

The API behaviour does not change.

API 0.0.22changed

Bench players have starting set to false

Every lineup player in the sport data now has starting as a boolean. This applies to football, Australian rules, rugby league and volleyball. A starter has starting: true. A bench player has starting: false. Before this change, a bench player had no starting value, so $d.1.benchLineup[0].starting returned null. To find bench players, use benchLineup, or test starting for false.

API 0.0.22added

Set team kit colours over REST

PATCH /v1/teams/{teamId} accepts kits. Each kit (home, away, alt or alt2) has primaryColor and secondaryColor, as hex colours. Both colours are required. Kits that you omit keep their colours. Send null for a kit to remove it.

API 0.0.22changed

Team logos must be 300x300 pixels

PUT /v1/teams/{teamId}/logo now checks the image dimensions. A logo must be 300x300 pixels, as in the dashboard. Any other size returns 400 FileWrongDimensions, and the upload stays open for a retry with the same uploadId. Resize the image before you upload it.

API 0.0.22addedchanged

Set a team player photo over REST

POST /v1/teams/{teamId}/players/{playerId}/photo/uploads opens a signed upload for one PNG or JPEG photo. The photo must be exactly 300x300 pixels and 500 KB or less. Declare the type, the size, and the SHA-256 of the file. Upload the bytes with one PUT to the returned URL.

PUT /v1/teams/{teamId}/players/{playerId}/photo sets the photo from the upload. The API checks the size, the SHA-256, the image type, and the pixel size before it stores the photo. DELETE /v1/teams/{teamId}/players/{playerId}/photo removes the photo. The player must be on the roster of the team. The photo belongs to that team only. Graphics show it as the player photo. All three routes need the teams:write scope.

photoUrl is now a full asset URL. Before this change, the match lineup routes returned the storage key in photoUrl. GET /v1/teams/{teamId}/players now also returns photoUrl for players with a team photo.

API 0.0.22added

Update a team player over REST

PATCH /v1/teams/{teamId}/players/{playerId} changes a player on the roster of a team in your organization. It needs the teams:write scope. Send only the fields to change: firstName, lastName, number, position, positionType, gfxFirstName, gfxLastName, defaultStarter, defaultBench and captain. Fields that you omit keep their current value.

Use gfxFirstName and gfxLastName to set shorter names for graphics, 1 to 16 characters each. firstName and lastName change on every team of the player. All other fields change on this team only. The player must be on the roster of the team. Otherwise the call returns 404.

If a data provider supplies the player, the next provider sync replaces firstName, lastName, number, position and positionType. The sync does not change the graphics names, the default starter flags or captain.

The response has the shape of an item of GET /v1/teams/{teamId}/players.

API 0.0.20changed

Data source templates accept empty cells

A data source template made from a CSV sample now converts each cell the same way a data source push does. A number cell becomes a number and an empty cell becomes null. The inferred schema marks every column nullable: true. Templates made in the dashboard get the same schema. A push of the CSV that made the template no longer returns warnings for empty cells.

Existing templates keep their stored schema. To accept empty cells in an existing template, send a new sample with PATCH.

API 0.0.20added

Find entities by data provider id

The list routes take two new filters: providerName and providerIds. Use them to find the entities that a data provider supplies, by the ids that the provider uses.

  • GET /v2/matches, GET /v1/matches, GET /v1/competitions and GET /v1/venues take the filters.
  • GET /v1/teams and GET /v1/players are new. They list the teams and the players of your organization, sorted by id, and take the same filters.
  • GET /v1/officials and GET /v1/officials/{officialId} are new. They return the match officials of your organization, such as referees and umpires. They use the players:read scope. The list takes the same filters.
  • providerIds is a comma-separated list of up to 100 ids. It needs providerName, because provider ids are unique only within one provider. An id that your organization does not have is not in the results.
  • providerName without providerIds lists all the entities from that provider.

Teams, players, competitions, venues and officials carry dataProvider (id and name), as matches already do. The field is absent when no data provider supplies the entity.

API 0.0.20added

Set a match lineup over REST

PUT /v2/matches/{matchId}/lineup sets the starting players and the substitutes of one or both teams. It needs the matches:write scope. The call replaces the lineup of each team you send, and open overlays show the new lineup. Graphics use the lineup to show the teams, list the scorers and fill the player variables. Each player must be on the team roster. An invalid player returns 400 with a details entry for each bad value.

Each lineup player now carries teamId. The field is in GET /v1/matches/{matchId}/lineup and in the p include of GET /v1/matches/{matchId} and GET /v2/matches/{matchId}.

API 0.0.20changed

Match requests no longer take matchTier

POST /v1/matches, POST /v2/matches and the match update routes no longer take matchTier. Leave it out. If a request still sends it, the API ignores it.

API 0.0.21added

Overlay responses return the monitoring URL

Overlay responses now carry monitoringUrl. The URL opens the read-only monitoring view of the overlay on the overlay host of the environment. The field is in POST /v1/overlays, GET /v1/overlays/{overlayId}, GET /v2/overlays/{overlayId} and the o include of GET /v1/matches/{matchId} and GET /v2/matches/{matchId}. Read the field instead of building the URL from key. Staging and other environments do not use overlay.ligr.live.

API 0.0.21changed

Rive color bindings ignore values that are not colors

A Rive color binding now applies only a #rgb, #rrggbb or #rrggbbaa string, or a finite number read as ARGB. Any other value is ignored, and the graphic keeps its current color. Before, a value such as '' became ARGB 0 and hid the shape. A numeric string such as '4294901760' is now ignored. Send a number instead. See Expressions.

API 0.0.21added

Field details in Rive configuration errors

A Rive 4xx error can now have a details array. Each entry has field and reason. field is the path of the value that failed, for example controlVariables[stage].defaultValue. reason states what is wrong, for example must be a JSON number. A 500 error has no details. See Edit through REST.

ligr-graphic prints each detail on its own line as field: reason.

API 0.0.21changed

Evaluate checks Rive user expressions

POST /v2/themes/{themeId}/rive-graphics/{graphicId}/evaluate now checks every user expression, not only the data bindings. The response has a new userExpressions array with one row per user expression. unresolved counts the failed rows in bindings and in userExpressions.

The graphics runtime now reads backslash escapes in expressions correctly. "a\nb" holds a line break, {"\"": 1} is a valid object, and /\d+/.test("12") returns true. Before this change, the runtime removed each backslash, so these expressions failed or returned a wrong value.

API 0.0.21added

Set a team logo over REST

POST /v1/teams/{teamId}/logo/uploads opens a signed upload for one PNG or JPEG logo of 500 KB or less. Declare the type, the size, and the SHA-256 of the file. Upload the bytes with one PUT to the returned URL.

PUT /v1/teams/{teamId}/logo sets the logo from the upload. The API checks the size, the SHA-256, and the image type before it stores the logo. DELETE /v1/teams/{teamId}/logo removes the logo. All three routes need the teams:write scope.

Team responses now carry logoUrl. The field is in GET /v1/teams/{teamId}, PATCH /v1/teams/{teamId}, and the logo routes. A team without a logo returns the club logo, if the club has one.

API 0.0.21addedchanged

Add a player to a team roster over REST

POST /v1/teams/{teamId}/players creates a player and adds the player to the roster of a team in your organization. It needs the teams:write scope. Send firstName and lastName. You can also send number, position, positionType, gfxFirstName, gfxLastName, defaultStarter and defaultBench. gfxFirstName and gfxLastName take 1 to 16 characters. The response has the shape of an item of GET /v1/teams/{teamId}/players. Use the returned id as a playerId in PUT /v2/matches/{matchId}/lineup.

In the TeamPlayer and MatchPlayer schemas, number and position are now nullable. A roster or lineup entry without a squad number or a position returns null for that field.

API 0.0.21added

Set the team coach over REST

PATCH /v1/teams/{teamId} accepts nonPlayerStaff. The field is a list of staff members. Each member has firstName, lastName and role. The role is manager or assistantManager. The list replaces the stored staff. Send an empty list to remove all staff.

Graphics show the manager entry as the coach, for example on line-up graphics. If no entry has the manager role, graphics show the first entry.

The team response now carries nonPlayerStaff when the team has staff. The field is in GET /v1/teams/{teamId} and in the PATCH response.

API 0.0.21added

Update a team over REST

PATCH /v1/teams/{teamId} updates a team in your organization. It needs the teams:write scope. Send only the fields you change. Omitted fields keep their stored value. You can send name, gfxName, gfxFullName, abbreviation, age, gender, gradeId, defaultVenueId, primaryBackgroundColor, primaryTextColor, secondaryBackgroundColor and secondaryTextColor. A request with no field, or with a blank name, returns 400. The response is the updated team.

The route uses the same update as the dashboard. The team history records the API key that made the change.

API 0.0.19changed

Verify graphic assets before publication

Graphic and theme publication now reads each referenced asset and thumbnail from storage before creating a version. The API checks size and SHA-256 when a digest exists. A missing file returns 409 GRAPHIC_ASSET_MISSING. An unreadable or changed file returns 409 GRAPHIC_ASSET_INVALID. Repair the file before publishing again.

API 0.0.18changedbreaking

Stream video bitrate is stored in whole megabits

  • videoBitrateKbps on POST /v1/streams and POST /v1/streams/{streamSettingsId} now accepts 2000 to 10000 and is rounded to the nearest 1000 kb/s. The encoder runs at whole megabits, and the previous range (500 to 30000) was written into the setting unconverted, which produced a value the encoder could not run.
  • Stream responses return videoBitrateKbps as whole thousands, for example 6000, converted from the stored value. A stream that was created before this change reads back the same way; nothing needs to be resent.
API 0.0.17added

Control-room presets expose entity variables and accept updates (beta)

  • POST /v2/control-rooms/{roomId}/presets accepts exposeVariables: names of fact, stat, team, player and match variables to show on the preset without a value. The operator picks the value live. Before this change, only the dashboard editor exposed these variables.
  • PUT /v2/control-rooms/{roomId}/presets/{presetId} renames a preset, moves it to another section, or replaces its variable set from the active published manifest. Position, scale and other dashboard settings are kept. A variable that stays in the set keeps its dashboard display type, exit mode and hidden state; naming it in exposeVariables shows it again. REST cannot pin a value on a fact, stat, team or player variable, and cannot set display type or exit mode; use the dashboard editor for those.
  • Preset responses carry exposedVariables: every variable the operator can see, with or without a stored value.

See Set up through REST.

API 0.0.16added

Rive graphics from the command line (beta)

  • Added the rive command group to @ligrsystems/graphics-cli 0.2.0. It imports a Rive file, edits the working draft, and publishes it, without a browser and without a dashboard session. See Command line.
  • ligr-graphic rive import <file> uploads a .riv, a .rev or a project ZIP, waits for preparation, and creates the graphic. It writes rive.json, which holds the theme id and the graphic id. Add --retain-source to keep the editable source. rive replace <file> replaces the Rive asset of an existing draft.
  • rive control, rive bind, rive input, rive asset, rive expr, rive schema and rive settings change one value at a time. Each command sends one REST operation, and the server validates the whole configuration on every write.
  • rive pull writes the working configuration into rive.json. rive push compares that file with the draft and sends one operation for each change. Add --dry-run to print the operations and send none. A push is not atomic: if one operation fails, run rive pull, then push again.
  • Every write carries the timestamp of the last read. A draft that changed answers 409 TARGET_CHANGED, and the CLI reads it again and retries once. A draft that a builder session holds answers 409 LOCKED, and the message names the editor.
  • rive publish creates a graphic version. Add --theme-version to publish a theme version that pins it, and --activate to make that theme version active.
  • Add --json to any command to print one JSON document and no human lines.
  • @ligrsystems/graphics-sdk moves to 0.2.0 with the CLI. The two packages must hold the same version.

Graphics creation stays in beta. Shapes can change between minor versions. See Beta status.

API 0.0.15added

Graphics SDK package and the ligr-graphic CLI (beta)

  • Graphics creation is in beta: the Graphics SDK, the CLI, and the theme and code graphics REST routes. You create the theme. Shapes can change between minor versions. See Beta status.
  • Added the @ligrsystems/graphics-sdk package: createGraphic(options) runs the ligr.gfx.v1 protocol in the browser, and useLigrGraphic(onHide) does the same for React. The protocol types ship under @ligrsystems/graphics-sdk/protocol.
  • Added the @ligrsystems/graphics-cli package. ligr-graphic init scaffolds a graphic, dev runs a local harness with real match scenarios, validate applies the API rules locally, and create, push and publish drive the code graphics REST routes.
  • Added POST /v2/themes, GET /v2/themes and DELETE /v2/themes/{themeId}: create, list and delete the themes your organization owns. An organization can own up to five themes (409 THEME_LIMIT_REACHED). A theme a competition uses cannot be deleted (409 THEME_IN_USE). The CLI drives them with ligr-graphic theme create|list|delete.
  • The Graphics SDK pages now start from the CLI. The REST calls stay documented under “Without the CLI” on Push and publish.

See Quick start.

API 0.0.14addedchanged

Scoped API keys with expiry

  • Added per-resource scopes to API keys. A scope is <resource>:read or <resource>:write. Each operation in the REST reference names the scope it needs. See Authentication.
  • Added an expiry date to API keys. The dashboard offers 7, 30, 60, 90 days, one year, a custom date, or no expiration.
  • Added 401 with code: "API_KEY_EXPIRED" for an expired key. Every 401 body now carries a code.
  • Changed the 403 INSUFFICIENT_SCOPE message. It names the missing scope, for example matches:write.
  • Changed key format. A new key starts with ligr_. LIGR stores a hash and shows the key once.
  • Existing keys keep working as legacy keys with read or write on every resource and no expiry. You cannot create a new legacy key.
API 0.0.13addeddeprecatedbreaking

Stream start, stop and monitor routes

  • Added POST /v1/streams/{streamSettingsId}/start and POST /v1/streams/{streamSettingsId}/stop. Start takes an optional destinationIds list. Without it the stream runs and publishes nowhere until an operator starts the destinations, which is how you preview.
  • Added the stream monitor operations for a running stream: POST …/destinations/start and POST …/destinations/stop with a destinationIds list, POST …/input/refresh, and POST …/input/latency with latencyMs.
  • Added POST …/automation with autoStream, and the autoMode field (Auto Graphics) on POST /v1/overlays/{overlayId}.
  • Deprecated POST /v1/streams/{streamSettingsId}/manage. It keeps working until 2027-09-08 and returns Deprecation and Sunset headers. It accepts GoLive and StopStream only.
  • Removed the StartPreview, PauseStream and IdlyStream values from manage. The service treated each of them as a stop, so a client that sent one from a live stream stopped it, and one that sent StartPreview from an idle stream got a 400.

See Automate a stream.

API 0.0.14added

Stream configuration over REST, and overlay webhooks

  • Added stream settings: GET /v1/streams?matchId=, POST /v1/streams, and GET, POST, DELETE on /v1/streams/{streamSettingsId}. Create takes the competition from the match.
  • Added destinations: GET, POST on /v1/streams/destinations, and GET, POST, DELETE on /v1/streams/destinations/{destinationId}. A pull destination answers with pullUrl.
  • Added inputs: GET, POST on /v1/streams/inputs, and GET, POST, DELETE on /v1/streams/inputs/{inputId}. LIGR generates the host, the application name and the stream key, and answers with rtmpUrl and srtUrl.
  • Added the overlay webhook entity with create, update and delete events. LIGR turns on webhooks per organization. See Events and Payloads.

See Configure a stream.

API 0.0.13addedchanged

Themes and code graphics over REST

  • Added GET /v2/themes/{themeId} and POST /v2/themes/{themeId}/versions.
  • Added /v2/themes/{themeId}/code-graphics: list, create, get, uploads, bundle and versions.
  • UserInputError now returns 400. It returned 500 before. This changes overlay v2 command validation.
  • Lock conflicts return 409 with code: "LOCKED" and a holder object.

See Themes and Code graphics in the REST reference, and the Graphics SDK.

Deprecation policy

A deprecated endpoint keeps working for at least 12 months after its changelog entry. It returns a Deprecation header and a Sunset header. Breaking changes ship only in a new path version.