External data sources
A theme can declare external data sources: a standings table, a fact file, a sponsor line. Your graphics read them. You fill them over REST, from a script, a spreadsheet or an automation tool.
POST /v2/data-sources/{competitionThemeSettingId}/{alias}Needs the data-sources:write scope. One data source is one alias in one competition theme setting. Each push
replaces the whole snapshot. Every open overlay that uses that theme profile receives the new data.
Where the ids come from
Section titled “Where the ids come from”| Id | Where you get it |
|---|---|
competitionThemeSettingId | GET /v2/competitions/{competitionId}/theme-profiles: the id of a theme profile. That list holds the profiles of themes your organization can use: owned, linked or public, and not inbuilt. In the dashboard, the push endpoint under How to update holds the id |
alias | The data sources of the theme in the dashboard. Each data source shows its alias, its shape and its schema. To create a data source over REST, see Data schemas |
The dashboard links to the LIGR for Sheets add-on, which pushes a sheet to this endpoint. Open the competition, then Theme Profiles. Under External Data, select How to update on the data source.
Two payload formats
Section titled “Two payload formats”Send data or csv. A body with neither returns 400.
Pre-formatted JSON
Section titled “Pre-formatted JSON”Send the object that matches the schema of the data source. Use this format for a nested schema and for any integration that already has structured data.
curl -X POST 'https://api.ligr.live/rest/v2/data-sources/8123/standings' \ -H 'Authorization: Bearer YOUR_WRITE_KEY' \ -H 'Content-Type: application/json' \ -d '{ "data": { "rows": [ { "team": "Eagles", "score": 42 }, { "team": "Hawks", "score": 38 } ] } }'Send the sheet as one string. The server parses it into the shape of the data source. Use this format for flat tables, for example from a spreadsheet export or a copy and paste.
curl -X POST 'https://api.ligr.live/rest/v2/data-sources/8123/standings' \ -H 'Authorization: Bearer YOUR_WRITE_KEY' \ -H 'Content-Type: application/json' \ -d '{ "csv": "team,score\nEagles,42\nHawks,38" }'CSV cannot express a nested object. If the schema nests objects, build the JSON yourself.
How CSV is parsed
Section titled “How CSV is parsed”- The delimiter is detected from the first line. Tab wins, then comma, then semicolon.
- Quoted fields can hold the delimiter and line breaks. Two double quotes inside a quoted field are one quote.
- Empty rows are dropped.
trueandfalsebecome booleans. An empty cell and the wordnullbecomenull.- A cell that is a number of 15 characters or fewer becomes a number. Longer digit strings stay strings, so phone numbers and long ids survive.
- A cell that holds a JSON array of strings, numbers or booleans becomes that array, for example
["a","b"].
Shapes
Section titled “Shapes”The shape of a data source is fixed in the theme. The parser turns the sheet into that shape.
| Shape | Sheet | Result |
|---|---|---|
rows | Row 1 holds the headers. Each later row is one record | { "rows": [ { "header": value, … }, … ] } |
kv | Each row is key,value | { "key": value, … } |
cell | One cell | { "value": value } |
name,score,tags,activeAlice,95,"[""sports"",""music""]",trueBob,88,"[""art""]",false{ "rows": [ { "name": "Alice", "score": 95, "tags": ["sports", "music"], "active": true }, { "name": "Bob", "score": 88, "tags": ["art"], "active": false } ]}Parse hints
Section titled “Parse hints”Add parse next to csv when the sheet is not in the default layout.
| Hint | Values | Meaning |
|---|---|---|
orientation | row (default), col | col reads headers down the first column and one record per column |
headerIndex | 1 (default) | The 1-based row, or column, that holds the headers |
{ "csv": "name\tAlice\tBob\nscore\t95\t88", "parse": { "orientation": "col" } }Images in rows
Section titled “Images in rows”A row can hold an image URL, for example the crest of a club that is not a team in LIGR. Host the image first, then put its URL in the row.
- Send
POST /v1/media/images/uploadswith thecontentType,sizeandsha256of a PNG or JPEG file. - Send the file with one PUT to the returned
url. Include the returnedheaders. - Send
PUT /v1/media/imageswith theuploadIdand aname. The response has the imageurl.
These routes need the media:write scope. Do the PUT before expiresAt, and send the uploadId within one hour.
API=https://api.ligr.live/restAUTH='Authorization: Bearer YOUR_WRITE_KEY'FILE=rovers-crest.png
SESSION=$(curl -sS -X POST "$API/v1/media/images/uploads" -H "$AUTH" -H 'Content-Type: application/json' \ -d "$(jq -n --argjson size "$(wc -c < "$FILE" | tr -d ' ')" \ --arg sha256 "$(shasum -a 256 "$FILE" | cut -d ' ' -f 1)" \ '{contentType: "image/png", size: $size, sha256: $sha256}')")
curl -sS --fail-with-body -X PUT "$(jq -er '.url' <<< "$SESSION")" \ -H "x-amz-checksum-sha256: $(jq -er '.headers["x-amz-checksum-sha256"]' <<< "$SESSION")" \ --data-binary "@$FILE"
curl -sS -X PUT "$API/v1/media/images" -H "$AUTH" -H 'Content-Type: application/json' \ -d "$(jq -n --argjson uploadId "$(jq -er '.uploadId' <<< "$SESSION")" \ '{uploadId: $uploadId, name: "Rovers crest"}')" | jq -r '.url'team,crestEagles,<url of the Eagles image>Hawks,<url of the Hawks image>The URL does not change and does not expire. The image appears in the dashboard Media section. If you archive it, the URL keeps working, so rows that use it do not break.
Schema validation
Section titled “Schema validation”The server validates the result against the schema of the data source. A mismatch does not reject
the push. The data is stored, the response carries a warning, and the dashboard shows the warning
on the data source. Fix the data and push again to clear it.
The response
Section titled “The response”{ "success": true, "alias": "standings", "competitionThemeSettingId": 8123, "lastPushedAt": "2026-09-08T01:14:02.000Z", "warning": "Schema validation warning: /rows/0/score: must be number"}warning is present only when validation failed.
Errors
Section titled “Errors”| Status | Cause |
|---|---|
| 400 | Neither data nor csv, an empty CSV string, or a CSV the parser cannot read |
| 403 | The key lacks data-sources:write, or a competition theme setting that your organization does not own |
| 404 | No competition theme setting with that id, or no data source with that alias in the theme |