> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Set Ground Truth
> Create or replace one dataset document's complete ground truth
*Rate limit tier: **general**, 600 requests/min. See [Rate limits](/api-reference-v3/introduction#rate-limits).*
Creates or replaces the ground truth of one dataset document packet, the expected values an [eval](/concepts/evals) grades the document against. The first write answers `201`, a replace answers `200`, and both return the stored document in the shape [Get ground truth](/api-reference-v3/datasets/get-ground-truth) returns.
Send the **complete** document in `ground_truth`: every field of the workflow must be present. A list field may be `[]` and any value may be `null`. Keys are the workflow schema's field identifiers: use `persistent_id` (the API also accepts `sanitized_name`). The stored document is always keyed by `persistent_id`. A scalar field maps to `string | null`; a table or object field maps to an array of row objects keyed the same way.
Omit `version_id` to write to the workflow's current version, the one an eval grades by default. `node_id` is the extract node's `id` in the [workflow graph](/api-reference-v3/workflows/get), required only when the version has more than one extract node.
Only a dataset document packet holds ground truth. A production packet answers `409 NOT_IN_DATASET`: [upload the document to the dataset](/api-reference-v3/datasets/upload) and set ground truth on the packet it returns.
## Errors
| Status | `error_code` | When |
| - | - | - |
| `403` | `ACCESS_DENIED` | The key's user is a Viewer of the organization. |
| `403` | `insufficient_api_key_scope` | The API key has no `write` scope. |
| `404` | `NOT_FOUND` | `params.resource_type` is `document_packet` (unknown, or in another organization) or `workflow_version`. |
| `409` | `NOT_IN_DATASET` | The packet is not a dataset document. |
| `409` | `ZERO_DATA_RETENTION_REFUSES_DATASET` | The organization keeps no data, so it has no dataset. |
| `422` | `GT_INVALID` | `detail` lists each offending key as `{ type, loc, msg }`; `loc` is the path to it, such as `["line_items", 0, "sku"]`. |
| `422` | `EXTRACT_NODE_UNRESOLVED` | The version has more than one extract node and no `node_id` was sent, or `node_id` names no extract node. |
```bash curl theme={null}
curl -X PUT 'https://api.anyformat.ai/v3/document-packets/069dcc2c-e14c-7606-8000-2ee4fb17b4e1/ground-truth/' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ground_truth": {
"0686bb978c3070f0800097669e00aaaa": "INV-001",
"0686bb978c3070f0800097669e00bbbb": [
{ "0686bb978c3070f0800097669e00cccc": "12.00" }
]
}
}'
```
```python Python (SDK) theme={null}
from anyformat.sdk import Client
client = Client(api_key="YOUR_API_KEY")
packet_id = "069dcc2c-e14c-7606-8000-2ee4fb17b4e1"
stored = client.get_ground_truth(packet_id)
corrected = {**(stored.ground_truth or {}), "0686bb978c3070f0800097669e00aaaa": "INV-002"}
client.set_ground_truth(packet_id, corrected, version_id=stored.version_id)
```
```typescript TypeScript (SDK) theme={null}
import { Anyformat } from "@anyformat/sdk";
const af = new Anyformat({ apiKey: "YOUR_API_KEY" });
const packetId = "069dcc2c-e14c-7606-8000-2ee4fb17b4e1";
const stored = await af.getGroundTruth(packetId);
await af.setGroundTruth(
packetId,
{ ...stored.ground_truth, "0686bb978c3070f0800097669e00aaaa": "INV-002" },
{ versionId: stored.version_id },
);
```
```json Response (201 Created) theme={null}
{
"ground_truth": {
"0686bb978c3070f0800097669e00aaaa": "INV-001",
"0686bb978c3070f0800097669e00bbbb": [
{ "0686bb978c3070f0800097669e00cccc": "12.00" }
]
},
"version_id": "FGaV4I2JAA",
"node_id": "extract_1"
}
```
```json Response (422 GT_INVALID) theme={null}
{
"error": "The ground truth is not valid.",
"detail": [
{
"type": "missing",
"loc": ["0686bb978c3070f0800097669e00bbbb", 0, "0686bb978c3070f0800097669e00cccc"],
"msg": "Field required"
}
],
"error_code": "GT_INVALID",
"retryable": false,
"request_id": "req_abc123",
"doc_url": "https://docs.anyformat.ai/api-reference-v3/errors#error-code-gt_invalid"
}
```
## OpenAPI
````yaml PUT /v3/document-packets/{document_packet_id}/ground-truth/
openapi: 3.1.0
info:
title: anyformat API
description: >
Document extraction and workflow automation API.
AnyFormat lets you define extraction workflows that pull structured data
from any document — PDFs, images, scanned files, or plain text. Upload a
file, run it through a workflow, and get back structured fields with
confidence scores and source evidence.
## Quick start
See the [Quick start
guide](https://docs.anyformat.ai/api-reference-v3/introduction) for a
walkthrough.
## Authentication
All endpoints (except `/health/`) require a Bearer token in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from
[app.anyformat.ai/api-key](https://app.anyformat.ai/api-key).
## Versioning
Endpoints are versioned by path prefix (`/v3/`). Every response under
a versioned prefix includes `X-API-Version`.
version: 3.0.0
servers:
- url: https://api.anyformat.ai
description: API server
security: []
tags:
- name: workflows
description: >-
Workflows define extraction templates — what fields to extract from
documents. Create workflows, upload files, run extractions, and fetch
results.
- name: document-packets
description: >-
Document packets group uploaded documents for a workflow. Address a packet
directly to (re-)run its workflow.
- name: runs
description: >-
Extraction runs — the first-class result entity. Each run is a single
execution of a workflow against a document packet; fetch its status and
results flat by run id.
- name: splits
description: >-
Splits — the sub-documents a splitter node carves out of a packet.
Download any one of them as a PDF, built from the source documents on
request and never stored.
- name: parse
description: >-
Parse a single document with the platform's fast lite parse — a one-call
shortcut over the workflow upload + run primitives, backed by your
organization's system parse workflow.
- name: health
description: Health check endpoints to verify API availability.
paths:
/v3/document-packets/{document_packet_id}/ground-truth/:
put:
tags:
- datasets
summary: Set ground truth
description: |-
Create or replace a dataset document packet's complete ground truth.
Answers `201` on the first write and `200` on a replace, both with the
stored document keyed by `persistent_id`. Only a dataset document packet
holds ground truth: a production packet returns `409 NOT_IN_DATASET`. A
Viewer, or an API key without the `write` scope, gets `403`.
operationId: v3_set_ground_truth
parameters:
- name: document_packet_id
in: path
required: true
schema:
type: string
title: Document Packet Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroundTruthSetRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GroundTruthV3'
headers:
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
'201':
description: Ground truth was created.
content:
application/json:
schema:
$ref: '#/components/schemas/GroundTruthV3'
headers:
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
'400':
description: >-
Validation failed — the request body or query parameters are
invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
VALIDATION_ERROR:
value:
error: The request failed validation.
detail: The request failed validation.
error_code: VALIDATION_ERROR
retryable: false
request_id: req_abc123
'401':
description: >-
Authentication failed — the API key is not valid (`INVALID_API_KEY`)
or the request carries none (`MISSING_API_KEY`).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INVALID_API_KEY:
value:
error: The API key is not valid.
detail: The API key is not valid.
error_code: INVALID_API_KEY
retryable: false
request_id: req_abc123
MISSING_API_KEY:
value:
error: The request carries no API key.
detail: The request carries no API key.
error_code: MISSING_API_KEY
retryable: false
request_id: req_abc123
'403':
description: >-
Access denied — the API key lacks access to this resource or the
scope this call needs (`ACCESS_DENIED`,
`insufficient_api_key_scope`).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
ACCESS_DENIED:
value:
error: You do not have access to this resource.
detail: You do not have access to this resource.
error_code: ACCESS_DENIED
retryable: false
request_id: req_abc123
insufficient_api_key_scope:
value:
error: The API key does not carry the scope this call needs.
detail: The API key does not carry the scope this call needs.
error_code: insufficient_api_key_scope
retryable: false
request_id: req_abc123
'404':
description: >-
Resource not found — the workflow, document packet, or run ID does
not exist or is not visible to this API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
NOT_FOUND:
value:
error: The resource does not exist.
detail: The resource does not exist.
error_code: NOT_FOUND
retryable: false
request_id: req_abc123
'409':
description: >-
`NOT_IN_DATASET` — The document is not in the workflow's dataset.
`ZERO_DATA_RETENTION_REFUSES_DATASET` — This organization keeps no
data, so it has no dataset.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
NOT_IN_DATASET:
value:
error: The document is not in the workflow's dataset.
detail: The document is not in the workflow's dataset.
error_code: NOT_IN_DATASET
retryable: false
request_id: req_abc123
ZERO_DATA_RETENTION_REFUSES_DATASET:
value:
error: This organization keeps no data, so it has no dataset.
detail: This organization keeps no data, so it has no dataset.
error_code: ZERO_DATA_RETENTION_REFUSES_DATASET
retryable: false
request_id: req_abc123
'422':
description: >-
`GT_INVALID` — The ground truth is not valid. `detail` is a list of
`{type, loc, msg}`, one per failure; `loc` holds the field's
`persistent_id`, or an unknown key as sent.
`EXTRACT_NODE_UNRESOLVED` — The request does not say which extract
node to use. `detail` is a list of one `{type, loc, msg}`; `msg` is
`ambiguous` or `unknown`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
GT_INVALID:
value:
error: The ground truth is not valid.
detail:
- type: missing
loc:
- 069dcc2ce14c760680002ee4fb17b4f0
msg: Field required
error_code: GT_INVALID
retryable: false
request_id: req_abc123
EXTRACT_NODE_UNRESOLVED:
value:
error: The request does not say which extract node to use.
detail:
- type: extract_node
loc:
- node_id
msg: ambiguous
error_code: EXTRACT_NODE_UNRESOLVED
retryable: false
request_id: req_abc123
'429':
description: >-
Rate limited — retry after the `Retry-After` header. Default
windows: 60 requests/minute for extraction submission, 600
requests/minute for general endpoints.
headers:
Retry-After:
description: Seconds until the next request is allowed.
schema:
type: integer
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
RATE_LIMITED:
value:
error: Too many requests.
detail: Too many requests.
error_code: RATE_LIMITED
retryable: true
request_id: req_abc123
'500':
description: >-
An internal error stopped the request — `retryable=true`. Retry with
backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INTERNAL_ERROR:
value:
error: An internal error stopped the request.
detail: An internal error stopped the request.
error_code: INTERNAL_ERROR
retryable: true
request_id: req_abc123
'502':
description: >-
An upstream service failed. Retry with backoff when `retryable` is
true.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INTERNAL_ERROR:
value:
error: An internal error stopped the request.
detail: An internal error stopped the request.
error_code: INTERNAL_ERROR
retryable: true
request_id: req_abc123
'503':
description: >-
An upstream service is unavailable. Retry with backoff when
`retryable` is true.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INTERNAL_ERROR:
value:
error: An internal error stopped the request.
detail: An internal error stopped the request.
error_code: INTERNAL_ERROR
retryable: true
request_id: req_abc123
'504':
description: An upstream service did not answer in time. Retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
GATEWAY_TIMEOUT:
value:
error: The upstream service did not answer in time.
detail: The upstream service did not answer in time.
error_code: GATEWAY_TIMEOUT
retryable: true
request_id: req_abc123
security:
- ApiKeyAuth: []
components:
schemas:
GroundTruthSetRequest:
properties:
ground_truth:
additionalProperties: true
type: object
title: Ground Truth
description: >-
The complete expected document. Keys are the workflow schema's field
identifiers: advertise `persistent_id` (the API also accepts
`sanitized_name`). A scalar field maps to `string | null`; a table
or object field maps to an array of row objects. Every field must be
present; a list field may be `[]`.
examples:
- 0686bb978c3070f0800097669e00aaaa: INV-001
version_id:
anyOf:
- type: string
- type: 'null'
title: Version Id
description: >-
A `version_id` from `GET /v3/workflows/{workflow_id}/versions/`.
Omit it for the workflow's current version, the one an eval grades
by default.
examples:
- FGaV4I2JAA
node_id:
anyOf:
- type: string
- type: 'null'
title: Node Id
description: >-
The extract node's `id` in the workflow graph, as `GET
/v3/workflows/{workflow_id}/` returns it. Required only when the
version has more than one extract node.
examples:
- extract_1
type: object
required:
- ground_truth
title: GroundTruthSetRequest
description: Body for `PUT /v3/document-packets/{document_packet_id}/ground-truth/`.
GroundTruthV3:
properties:
ground_truth:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Ground Truth
description: >-
The expected document, keyed by the workflow's field
`persistent_id`s. A scalar field maps to `string | null`; a table or
object field maps to an array of row objects keyed the same way.
`null` until ground truth is first set for this version and node.
examples:
- 0686bb978c3070f0800097669e00aaaa: INV-001
version_id:
type: string
title: Version Id
description: The workflow version the ground truth belongs to.
examples:
- FGaV4I2JAA
node_id:
type: string
title: Node Id
description: The extract node's `id` in the workflow graph.
examples:
- extract_1
type: object
required:
- ground_truth
- version_id
- node_id
title: GroundTruthV3
description: >-
A document packet's stored ground truth and the `(version, node)` it
belongs to.
ErrorEnvelope:
type: object
title: ErrorEnvelope
description: >-
Uniform error response. `retryable=true` means the same request may
succeed on retry (with backoff); `retryable=false` means the caller must
change the request before retrying.
required:
- error
- error_code
- retryable
- request_id
properties:
error:
type: string
description: Short human-readable summary.
detail:
description: >-
Machine-readable detail, any JSON value. A string for most errors, a
list of field errors for validation failures, and an object for a
structured error such as `FILENAME_CONFLICT` (`detail.conflicts`).
error_code:
type: string
enum:
- ACCESS_DENIED
- AGENTIC_MULTIFILE_UNSUPPORTED
- AUTH_FAILED
- CONCURRENT_EDIT
- DATASET_DOCUMENT_REJECTED
- DATASET_GROUND_TRUTH_SAVE_FAILED
- DATASET_INVALID_REQUEST
- EMPTY_EVAL
- ENDPOINT_RETIRED
- EXTRACT_MODE_FORBIDDEN
- EXTRACT_NODE_UNRESOLVED
- FILENAME_CONFLICT
- FILE_TOO_LARGE
- GATEWAY_TIMEOUT
- GRAPH_READBACK_FAILED
- GT_INVALID
- IDEMPOTENCY_KEY_REUSED
- IMMUTABLE_WORKFLOW
- INSUFFICIENT_CREDIT
- INTERNAL_ERROR
- INTERNAL_INCONSISTENCY
- INVALID_API_KEY
- INVALID_JSON
- INVALID_LOOKUP_FILE_ENCODING
- INVALID_VALUE
- INVALID_WORKFLOW_CONFIG
- KNOWLEDGE_NOT_ENABLED
- KNOWLEDGE_NOT_READY
- KNOWLEDGE_THREAD_MISMATCH
- KNOWLEDGE_UNSUPPORTED_SNAPSHOT_FORMAT
- LOOKUP_FIELD_WITHOUT_FILE
- METHOD_NOT_ALLOWED
- MISSING_API_KEY
- NOT_ACCEPTABLE
- NOT_FOUND
- NOT_IMPLEMENTED
- NOT_IN_DATASET
- OBJECT_STORAGE_UNAVAILABLE
- OPERATOR_DEPRECATED
- OPERATOR_NOT_AVAILABLE
- PARSE_MODE_FORBIDDEN
- PAYMENT_REQUIRED
- PRECONDITION_FAILED
- RATE_LIMITED
- REQUEST_TOO_LARGE
- RUN_IN_PROGRESS
- SPLIT_HAS_NO_PAGES
- SPLIT_SOURCE_NOT_PDF
- SPLIT_WORKFLOW_DATASET_UNSUPPORTED
- TOPOLOGY_INVALID
- UNSUPPORTED_FILE_TYPE
- UNSUPPORTED_LOOKUP_FILE
- UNSUPPORTED_MEDIA_TYPE
- UPLOAD_SNIFF_BUDGET_EXCEEDED
- VALIDATION_ERROR
- WORKFLOW_CONCURRENT_EDIT
- WORKFLOW_NAME_CONFLICT
- ZERO_DATA_RETENTION_REFUSES_DATASET
- ZERO_DATA_RETENTION_REFUSES_KNOWLEDGE
- deprecated_operator_ack_required
- insufficient_api_key_scope
- terms_acceptance_required
description: >-
Stable identifier for programmatic handling. New values can be added
at any time, so a client must accept a code it does not know.
examples:
- VALIDATION_ERROR
- AUTH_FAILED
- NOT_FOUND
- PRECONDITION_FAILED
- RATE_LIMITED
- INTERNAL_ERROR
- GATEWAY_TIMEOUT
retryable:
type: boolean
description: True when the caller should retry (with backoff for 429/412/5xx).
request_id:
type: string
description: Correlates this response with server logs.
params:
type: object
additionalProperties: true
description: >-
Values specific to this occurrence of the error that a caller needs
to recover, such as `node_ids` or `required_scope`, keyed by name.
Absent when the code relays none.
doc_url:
type: string
format: uri
description: Link to the documentation of this `error_code`.
securitySchemes:
ApiKeyAuth:
type: http
description: >-
API key issued from app.anyformat.ai/api-key. Send as `Authorization:
Bearer `.
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.