Create Ground Truth Dataset

Create a ground truth dataset with POST /v1/quality/ground-truth, linked to one schema. The dataset holds verified values used for accuracy benchmarking.

POST /v1/quality/ground-truth creates an empty ground truth dataset: a schema-scoped container for manually verified field values that benchmark runs compare extraction output against. Create the dataset first, then populate it with entries; it becomes the baseline for measuring extraction accuracy.

The typical workflow is: create the dataset, then populate it using POST /v1/quality/ground-truth/:id/entries for each entry. Once populated, create a benchmark run with POST /v1/quality/benchmarks.

The response returns the dataset with document_count: 0 since it is initially empty. user_schema_id echoes the schema_id you passed in. The links.self URL points to the detail endpoint where you can retrieve the dataset with its entries.

For best results, aim for at least 30-50 entries per dataset. The schema_id scoping ensures ground truth field names align with your extraction schema, producing more meaningful benchmark comparisons.

Plan dataset boundaries around what you want to compare: one dataset per document type (invoices, contracts, delivery notes) keeps per-field accuracy interpretable, and a fresh dataset per major schema revision keeps historical scores comparable. Because benchmarks score against the dataset's exact expected keys, a schema change that renames fields silently turns old entries into permanent misses — recreate the affected entries rather than reusing them.

Dataset metadata is immutable through the public API: there is no update or delete route for the dataset object itself, only entry-level POST and DELETE under [/entries](quality-entries). Treat the dataset as a stable benchmark anchor — keep its entries fixed while you compare runs against it, and spin up a new dataset when your verification standard changes.

curl -X POST https://api.talonic.com/v1/quality/ground-truth \
  -H "Authorization: Bearer tlnc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Accuracy Set",
    "schema_id": "5e6f7a8b-9c0d-1234-abcd-ef0123456789",
    "description": "Manually verified invoices for Q3"
  }'

The endpoint verifies schema_id before inserting: a value that is not a UUID fails validation with 400 ("schema_id must be a UUID"), and a well-formed UUID that does not match a schema in your organization returns 404 not_found rather than a foreign-key failure. Requires a key with the write scope; read-only keys receive 403 insufficient_scope.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Invoice Accuracy Set",
  "description": null,
  "user_schema_id": "5e6f7a8b-9c0d-1234-abcd-ef0123456789",
  "document_count": 0,
  "created_at": "2024-09-01T10:00:00.000Z",
  "links": {
    "self": "/v1/quality/ground-truth/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Errors