Skip to main content

Samples

Pin and unpin sample documents on a Spec via the API. Samples are the preview anchor set: up to five documents that drive deterministic, cached Spec previews.

Samples are the Spec preview anchor set: a small, pinned group of documents (at most five per Spec) used to generate deterministic, cached previews of how the Spec behaves. Pinning the same document twice is idempotent. These documents are also the filenames that appear on the customer-facing Spec document, never the cell values. Samples anchor preview surfaces only — they are never part of delivery.

Pinning takes a document_id and an optional label (a human note like "typical invoice" or "edge case: handwritten"). The document must already exist on the platform and belong to your organization — a foreign or unknown id 404s. Re-pinning an already-pinned document is a no-op, with one useful exception: sending a different label updates the label in place, so you can rename a sample without unpinning it.

Listing returns the pinned set ordered by pinned_at, oldest first. Each entry carries the sample row plus a trimmed document object (id and filename only) and a content_rev — an MD5 of the document's extracted markdown. content_rev is the preview cache key on document content: it changes when OCR re-runs on the same document id, and reads null for a document whose markdown is not yet extracted. The list is also filtered by Sources-IAM visibility for the API key's minting user, so a sample whose document a viewer cannot see is dropped from their read.

Unpinning removes one document by its id and returns { "deleted": true }; unpinning a document that is not pinned 404s. Because previews are cached against the anchor set, changing the samples is how you refresh which documents a preview runs over.

GET/v1/schemas/{id}/samples
POST/v1/schemas/{id}/samples

Body parameters

document_id*stringThe document UUID to pin.
labelstringOptional label for the sample (max 200 characters).
DELETE/v1/schemas/{id}/samples/{documentId}

Path parameters

id*stringSpec (schema) UUID.
documentId*stringThe pinned document UUID to remove.

Pin a sample

curl -X POST https://api.talonic.com/v1/schemas/a1b2c3d4-e5f6-7890-abcd-ef1234567890/samples \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "b8b00d51-eecc-49b3-affc-89fee95b9518",
    "label": "October invoice"
  }'

Response

Pinning returns the sample row. Listing returns an array of the same rows, each augmented with the trimmed document object and the content_rev cache key.

Sample fields (GET list)

idstringSample row UUID.
user_schema_idstringSpec (schema) UUID the sample is pinned to.
document_idstringPinned document UUID.
labelstring | nullOptional sample label.
pinned_atstringISO 8601 timestamp the document was pinned. The list is ordered by this, oldest first.
document.idstringThe pinned document UUID (same as document_id).
document.filenamestringSource document filename.
content_revstring | nullMD5 of the document's extracted markdown — the preview cache key on content. null until OCR markdown exists.

Response (GET samples)

[
  {
    "id": "a261aeef-49f3-49f7-abc4-d41a55d9a64f",
    "user_schema_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "document_id": "b8b00d51-eecc-49b3-affc-89fee95b9518",
    "label": "October invoice",
    "pinned_at": "2026-07-14T21:04:11.312Z",
    "document": {
      "id": "b8b00d51-eecc-49b3-affc-89fee95b9518",
      "filename": "invoice_oct.pdf"
    },
    "content_rev": "9b2ff02efbdf649b28e5f67ac3166f9c"
  }
]
A Spec holds at most five samples — the sixth pin fails with a 400 telling you to unpin one first. Pinning is idempotent, so re-pinning the same document does not add a duplicate or raise an error; re-pinning with a new label updates the label.

Errors

Error responses

400validation_errorInvalid document_id, or the five-sample cap is already reached ("A Spec can pin at most 5 sample documents — unpin one first").
401unauthorizedMissing or invalid API key.
404not_foundNo Spec (schema) with this ID, the document to pin does not belong to your organization, or the document to unpin is not currently pinned.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

How many samples can a Spec have?+
Up to five. The samples form the preview anchor set used to generate deterministic, cached previews of the Spec. The sixth pin is rejected with a 400 asking you to unpin one first.
What happens if I pin the same document twice?+
Pinning is idempotent. The second pin is a no-op: it does not create a duplicate and does not error. The one side effect is label maintenance — a re-pin that sends a different label updates the stored label.
Are sample document values exposed publicly?+
No. Only the sample filenames appear on the customer-facing Spec document. Cell values and document ids are never shared through that surface.
What is content_rev for?+
It is the MD5 of the document's extracted markdown, so previews can cache on document content rather than document id: re-running OCR on the same document changes content_rev and busts the preview cache instead of replaying stale cells. It reads null while the document has no extracted markdown yet.

Related

Spec Document
Delivery Config
List Documents