Skip to main content

Samples

Pin and unpin sample documents on a Spec. 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.

Pinning takes a document_id and an optional label. Listing returns the current pinned set. Unpinning removes one document by its id. 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
DELETE/v1/schemas/{id}/samples/{documentId}

Response

Sample fields

data[].document_idstringPinned document UUID.
data[].labelstring | nullOptional sample label.
data[].filenamestringSource document filename.

Response (GET samples)

[
  {
    "document_id": "d0c00001-1111-2222-3333-444455556666",
    "label": "October invoice",
    "filename": "invoice_oct.pdf"
  },
  {
    "document_id": "d0c00002-1111-2222-3333-444455556666",
    "label": null,
    "filename": "invoice_nov.pdf"
  }
]
A Spec holds at most five samples. Pinning is idempotent, so re-pinning the same document does not add a duplicate or raise an error.

Errors

Error responses

400validation_errorInvalid document_id, or the five-sample limit was exceeded.
401unauthorizedMissing or invalid API key.
404not_foundNo Spec (schema) or sample document with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Spec Document
Delivery Config