Skip to content

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.

IdWhere you get it
competitionThemeSettingIdGET /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
aliasThe 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.

Send data or csv. A body with neither returns 400.

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.

Push JSON
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.

Push CSV
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.

  • 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.
  • true and false become booleans. An empty cell and the word null become null.
  • 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"].

The shape of a data source is fixed in the theme. The parser turns the sheet into that shape.

ShapeSheetResult
rowsRow 1 holds the headers. Each later row is one record{ "rows": [ { "header": value, … }, … ] }
kvEach row is key,value{ "key": value, … }
cellOne cell{ "value": value }
Sheet
name,score,tags,active
Alice,95,"[""sports"",""music""]",true
Bob,88,"[""art""]",false
Stored snapshot, shape rows
{
"rows": [
{ "name": "Alice", "score": 95, "tags": ["sports", "music"], "active": true },
{ "name": "Bob", "score": 88, "tags": ["art"], "active": false }
]
}

Add parse next to csv when the sheet is not in the default layout.

HintValuesMeaning
orientationrow (default), colcol reads headers down the first column and one record per column
headerIndex1 (default)The 1-based row, or column, that holds the headers
Headers in the first column
{ "csv": "name\tAlice\tBob\nscore\t95\t88", "parse": { "orientation": "col" } }

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.

  1. Send POST /v1/media/images/uploads with the contentType, size and sha256 of a PNG or JPEG file.
  2. Send the file with one PUT to the returned url. Include the returned headers.
  3. Send PUT /v1/media/images with the uploadId and a name. The response has the image url.

These routes need the media:write scope. Do the PUT before expiresAt, and send the uploadId within one hour.

Host a crest
API=https://api.ligr.live/rest
AUTH='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'
Sheet with crest URLs
team,crest
Eagles,<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.

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.

{
"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.

StatusCause
400Neither data nor csv, an empty CSV string, or a CSV the parser cannot read
403The key lacks data-sources:write, or a competition theme setting that your organization does not own
404No competition theme setting with that id, or no data source with that alias in the theme