Library Datasets

List the datasets a workspace can read, create or replace a workspace dataset, and read a dataset's source again with the /v1/data-library/datasets routes.

A dataset is the definition of a collection of records: its key, label, publisher, licence, the connector that reads its source, and how often it is re-read. GET /v1/data-library/datasets lists every dataset the workspace can read, the shared library together with the workspace's own, ordered by key. Each entry carries its sync state (last_synced_at, last_status, last_error, last_stored) and the number of records the workspace can read in it, so one call shows both what exists and how fresh it is.

{
  "data": [
    {
      "id": "0d6c1a52-3b7e-4f09-8a41-5e2c9b7d1f33",
      "customer_id": "b1c2d3e4-0000-4000-8000-0123456789ab",
      "key": "acme.heat-tariff",
      "label": "Acme district heat tariff",
      "kind": "records",
      "publisher": "Acme Fernwaerme GmbH",
      "source_url": "https://example.com/tariffs/heat-2026.pdf",
      "licence": null,
      "connector": "manual",
      "record_schema": null,
      "params": {},
      "sync_hours": 720,
      "active": true,
      "last_synced_at": null,
      "last_status": null,
      "last_error": null,
      "last_stored": null,
      "created_at": "2026-10-21T08:10:44.000Z",
      "updated_at": "2026-10-21T08:10:44.000Z",
      "shared": false,
      "records": 1
    }
  ]
}

Create or Replace a Dataset

POST /v1/data-library/datasets creates the workspace's dataset with the given key, or replaces its definition when the workspace already has one. It replaces the whole definition: every field the body omits returns to its default, so send the complete definition each time. The dataset belongs to the workspace of the key, and shared datasets are written by Talonic only. The response is 201 with the stored row under data.

The connector decides where records come from. A manual dataset has no source and receives records only through the records endpoint. A document.extract dataset reads a published document: it needs a record_schema and a string params.url, and source_url defaults to params.url when omitted. The platform fetches the document over HTTPS, extracts records with the named schema, and keeps a record only when its quote occurs in the document and prints its value. An unknown connector or record schema, a key that does not match the pattern, and a document.extract dataset without its schema or URL are refused with 422.

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.district-heat",
    "label": "Acme district heat prices 2026",
    "publisher": "Acme Fernwaerme GmbH",
    "connector": "document.extract",
    "record_schema": "district_heat_prices",
    "params": { "url": "https://example.com/tariffs/heat-2026.pdf" },
    "sync_hours": 720
  }'

Read a Source Again

POST /v1/data-library/datasets/{key}/sync reads the source of the workspace's own dataset immediately, through its connector, and stores what it finds. A re-read replaces what the source states for the periods it covers and keeps the other periods. The result says what happened: stored counts the records written, rejected counts extracted records dropped because their quote does not occur in the source or does not print the value, and error is null on success. A failing read does not fail the request: the reason comes back in error, is recorded on the dataset (last_status, last_error), and the stored records stay.

The route reaches only the workspace's own datasets. A manual dataset has no source and returns stored: 0. A dataset of the shared library is not reachable here and answers 404, as does an unknown key. Shared datasets are re-read on their own schedule; a workspace dataset with a connector other than manual is re-read every sync_hours while it is active, and this route reads it ahead of that schedule.

curl -X POST "https://api.talonic.com/v1/data-library/datasets/acme.district-heat/sync" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

{
  "data": {
    "dataset": "acme.district-heat",
    "stored": 14,
    "rejected": 1,
    "error": null
  }
}