Data Library Overview
Read the workspace data library: shared reference data, your own datasets and records with sources, and the needs your apps still report, via /v1/data-library.
The Data Library holds reference data that the results of a workspace depend on but that the workspace does not produce: grid-fee price sheets, district-heat and default-supply tariffs, grid-operator and municipality registers, EU ETS installations. A dataset is a named collection of records read from a published source. Every record keeps the address it came from (source_url), the publisher's own wording that states it (quote), and the time it was retrieved (retrieved_at), so a value read from the library can always be traced back to a document a person can open.
Two kinds of dataset meet in one view. The shared library is Talonic's: public sources that every workspace benefits from, maintained and re-read on a schedule. A workspace's own datasets are its private additions: a tariff sheet from a supplier, a register the workspace curates. A key reads both together, and shared on each dataset and record says which is which. A key writes only its own workspace's datasets and records. Talonic promotes a workspace dataset into the shared library when its source is public; no endpoint on this surface writes to the shared library.
Records are identified by dataset, record key and start date (valid_from). A record with the same record key and start date replaces the stored one, and a record with a different start date is a separate period of the same thing: the library accumulates history rather than overwriting it. valid_from and valid_to bound the period in which a record is in force, and an open end matches every date, so a query for a given day (on=2026-03-15) returns the record that was valid that day.
The second half of the surface is data needs. An app of the workspace that cannot finish a computation reports what it is missing (an index value, a grid fee, a quantity, an invoice) per scope, for example a year. A need stays listed until the app no longer reports it, and its status says what could close it: the library could answer it, the customer can, or only the invoices can. The need endpoints let a workspace see what is missing, what the library could answer, and which datasets nobody has loaded yet.
/v1/data-library routes take the read scope for reads and the write scope for writes, and act on the workspace of the authenticated key. A write also requires the key's person to be a member or above in the workspace. App service keys do not reach these routes.Worked Example: Load a Tariff and Read It for a Date
A workspace keeps a supplier's heat tariff in the library so apps can price against it. First create a manual dataset (a dataset with no source connector, written only through the records endpoint). The dataset key is lowercase letters, digits and . _ : - /, and it names the collection.
cURL: 1. Create the dataset
curl -X POST "https://api.talonic.com/v1/data-library/datasets" \
-H "Authorization: Bearer $TALONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "acme.heat-tariff",
"label": "Acme district heat tariff",
"publisher": "Acme Fernwaerme GmbH",
"source_url": "https://example.com/tariffs/heat-2026.pdf"
}'Then add the records. Each carries the quote from the sheet that prints the value; a record needs only a record_key and its attributes, and the attributes are free-form for a manual dataset. Re-sending the same record key and valid_from replaces the record.
cURL: 2. Add records with their sources
curl -X POST "https://api.talonic.com/v1/data-library/records" \
-H "Authorization: Bearer $TALONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataset": "acme.heat-tariff",
"records": [
{
"record_key": "base-price",
"attributes": { "eur_per_mwh": 98.4 },
"valid_from": "2026-01-01",
"valid_to": "2026-12-31",
"source_url": "https://example.com/tariffs/heat-2026.pdf",
"quote": "Arbeitspreis 98,40 EUR/MWh"
}
]
}'Finally read the record in force on a given day. Without on, every period of every matching record is returned.
cURL: 3. Read what was in force on a date
curl "https://api.talonic.com/v1/data-library/records?dataset=acme.heat-tariff&on=2026-03-15" \
-H "Authorization: Bearer $TALONIC_API_KEY"Response: Records
{
"data": [
{
"id": "6f3b2c0e-8d1a-4b57-9c2e-1d4f7a90b3c5",
"shared": false,
"dataset_key": "acme.heat-tariff",
"record_key": "base-price",
"attributes": { "eur_per_mwh": 98.4 },
"valid_from": "2026-01-01",
"valid_to": "2026-12-31",
"source_url": "https://example.com/tariffs/heat-2026.pdf",
"quote": "Arbeitspreis 98,40 EUR/MWh",
"retrieved_at": "2026-10-21T08:14:02.311Z"
}
]
}data field, and list reads are bounded by a limit that is clamped rather than rejected: a value outside the allowed range is moved to the nearest bound. A read that returns exactly limit rows may have more, so narrow it with dataset, prefix, record or on instead of assuming the page is complete.