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 overlay of that competition receives the new data at once.

Where the ids come from

Id	Where you get it
competitionThemeSettingId	GET /v2/competitions/{competitionId}/theme-profiles: the id of a theme profile. Also under the competition, then the theme, in the dashboard
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 offers a Google Apps Script per theme that pushes a sheet to this endpoint. Find it under the theme settings of the competition.

Two payload formats

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

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.

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 } ] } }'

CSV

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.

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.
• 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"].

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 }

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 }
  ]
}

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

Headers in the first column

{ "csv": "name\tAlice\tBob\nscore\t95\t88", "parse": { "orientation": "col" } }

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

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

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