Create a scoped API key, send it as a Bearer token and list your matches, then handle includes, pagination, errors, rate limits and versions.
The LIGR REST API lives at https://api.ligr.live/rest and takes an API key as a Bearer token on every request. A key belongs to one organisation, carries per-resource scopes such as matches:read or overlays:write, and expires after 7, 30, 60 or 90 days, one year or a custom date. This guide follows Your first request and Authentication in the LIGR developer docs, then covers what you meet next.
Who this is for
Developers connecting a fixtures system, a score feed, a results website or a broadcast automation to LIGR, and the AI coding agents they hand that work to. You need a LIGR organisation, and an owner or admin of that organisation to create the key. If you do not have an organisation yet, ask your LIGR contact or talk to us.
What you can build
The API reads and writes the same matches, facts, teams, overlays, streams and themes the dashboard uses. Starting points by sport, with the scope each needs:
| Sport | Integration | Scope |
|---|---|---|
| Football | A fixtures system that creates each round's matches with POST /v2/matches and scores them with facts | matches:write |
| Basketball | A results page that reads the score, clock and team statistics LIGR computes, from GET /v2/matches/{matchId}/summary | matches:read |
| Tennis | A tournament draw that creates singles or doubles matches, with player competitors in place of teams | matches:write |
| AFL | A club site that lists a competition's teams with GET /v1/competitions/{competitionId}/teams | competitions:read |
| Netball | A ladder pushed from a spreadsheet into a theme data source, so every overlay of the competition shows it | data-sources:write |
| American football | A graphic built against the gridiron data shape from GET /v2/schemas/sports/gridiron | themes:read |
Your first request, step by step
Create a read key
In the dashboard, open the account menu at the bottom of the sidebar and select Developers. On the API keys tab, select Create API key, set Matches to Read, keep the 30 day expiry and select Create key. Only owners and admins see Developers. LIGR shows the full key once, then only its first and last four characters. Keys start with ligr_.
List one match
Send the key in the Authorization header. This call is copied from Your first request:
curl 'https://api.ligr.live/rest/v2/matches?limit=1' \
-H 'Authorization: Bearer YOUR_READ_KEY'The answer holds a matches array, total, the number of matches your organisation owns, and returned, the number in this response. Keep the match id: most other endpoints need it.
Fetch related entities with include
Add include to get related entities in the same answer. GET /v2/matches/{matchId}?include=o,cp adds the overlay and the competitors. Includes go one level deep, and an unknown value is ignored without an error, so check the response for what you asked for.
Page through lists
List endpoints take limit and offset. Increase offset by limit until it reaches total. The maximum limit is 100 on match lists and 500 on the other lists. See Includes and pagination.
Scopes: give each integration the smallest key
A scope is <resource>:read or <resource>:write, and write includes read on the same resource. The resource is the first path segment after the version, so /v1/competitions/{competitionId}/teams sits under competitions. Each operation in the REST reference names its scope.
| Resource | Covers |
|---|---|
matches | Matches, facts, lineups and match summaries |
competitions | Competitions, under /v1/competitions |
teams | Teams, rosters and adding players to a team |
players | Players and match officials |
venues | Venues |
overlays | Overlays, graphics commands and control room graphics |
streams | Streams, going live, and overlay show and hide on a stream |
data-sources | Pushes to theme data sources |
themes | Themes, code graphics, sport schemas and scenarios |
The docs give two examples: a score feed needs matches:write, and a results website needs matches:read and competitions:read. LIGR checks the scopes of the key, not the role of the person who created it.
Errors you can branch on
Every error is JSON with a message, and many also carry a code.
| Status and code | Meaning | Retry? |
|---|---|---|
401 UNAUTHENTICATED | A missing or unknown key, or an invalid Authorization format | No. Fix the request |
401 API_KEY_EXPIRED | The key passed its expiry date | No. Create a new key |
403 INSUFFICIENT_SCOPE | The key lacks the scope. The message names it | No. Use a key with that scope |
429 | The rate limit is exceeded while enforcement is on | Yes, after RateLimit-Reset seconds |
500 | Unexpected | Once, then send support the traceparent you used |
One trap: another organisation's resource is always refused, but the status varies today. Theme routes answer 404, and match, team, player, overlay, stream and data source routes answer 403. Do not read ownership from the status code. See Errors.
Rate limits
LIGR applies fair-use limits and does not publish a fixed request budget. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. Enforcement is being phased in. Until it starts, an over-limit request still succeeds and carries x-ligr-rate-limit-observe: 1. Treat that header as a 429 and back off. Use webhooks instead of polling, batch reads with include and cache GET responses. See Rate limits.
Versions, beta routes and the changelog
- Versions are per resource.
/v1and/v2run side by side, and a resource moves to v2 only when its shape would break v1 clients. Use the higher version for new work. - Additive changes need no new version. New optional fields, parameters, endpoints and enum values can ship at any time, so write your client to ignore unknown fields.
- Beta is marked three ways. A beta operation carries
x-betain the OpenAPI document, a Beta line on its reference page andX-Ligr-Beta: trueon every response. Graphics creation is in beta. A removed or renamed beta field keeps working for at least 30 days after its changelog entry. - Deprecation is slow. A deprecated endpoint keeps working for at least 12 months and returns
DeprecationandSunsetheaders. - Generate a client from the spec. The docs recommend generating one from
https://api.ligr.live/rest/swagger.json. Follow the changelog, which also has an RSS feed. See Versioning.
Environments and key rotation
The examples in the docs use production: api.ligr.live for REST and overlay.ligr.live for overlays. If LIGR gave you a non-production environment, use its origins instead. A key works only in the environment that issued it.
A No expiration option exists for integrations that cannot rotate keys, and the dashboard warns you first. There is no REST endpoint for keys today. To rotate one, create a new key with the same scopes, deploy it, then delete the old key. Both work during the overlap, and deletion takes effect at once. Keep keys in a secrets store, never in a browser or a shared spreadsheet. New work uses Authorization: Bearer. The legacy x-ligr-api-key header still works, and REST routes ignore keys in the query string.
Handing this to an AI agent? Give it https://docs.ligr.live/llms.txt, a scoped key with a short expiry and the six rules on the For AI agents page. Rule 6: never publish a theme version with activate: true during a live match.
Frequently asked questions
How do I authenticate with the LIGR API?
Create an API key in the LIGR dashboard under Developers, API keys, then send it as Authorization: Bearer <key> to https://api.ligr.live/rest. Keys start with ligr_, belong to one organisation, and carry per-resource scopes and an optional expiry date. Only owners and admins can create keys.
Which scopes does my API key need?
The smallest set that works. Each operation in the REST reference names its scope, as <resource>:read or <resource>:write, and write includes read. A score feed needs matches:write. A results website needs matches:read and competitions:read.
Does LIGR publish a rate limit?
There is no fixed budget. LIGR applies fair-use limits and reports them in RateLimit headers on every response. While enforcement is phased in, treat x-ligr-rate-limit-observe: 1 as a 429 and back off.
Is there a client library for the LIGR REST API?
The docs recommend generating one from the OpenAPI document at https://api.ligr.live/rest/swagger.json. The packages LIGR ships, @ligrsystems/graphics-sdk and @ligrsystems/graphics-cli, are for graphics, and they are in beta.
What happens when LIGR changes an endpoint?
Additive changes ship without a new version, and breaking changes ship in a new path version. A deprecated endpoint keeps working for at least 12 months, with Deprecation and Sunset headers. Beta operations can change between minor versions.
Make your first request
The Get started section of the docs covers authentication, concepts, errors, rate limits and versioning, with a Markdown twin of every page.