Skip to main content

Run a Spec

Upload documents and run a Spec pipeline in a single call with POST /v1/run: mixed file and URL inputs, optional batch_id and metadata tagging, 202 with a poll URL.

The Run endpoint, POST /v1/run, is the one-call front door for Spec pipelines: send one or more documents together with a spec_id, and the platform ingests every input, waits for OCR, compiles the Spec's saved rail into a pipeline, and starts it — extraction, resolution, validation, and delivery exactly as composed in the Spec editor. It replaces the two-step "upload documents, then POST /v1/pipelines" flow for integrations that push files as they arrive.

Inputs are flexible: attach up to 20 files as multipart parts, pass remote file_urls for documents the platform should download, or mix both in one call. At least one input is required. The endpoint always answers 202 Accepted immediately with a run_id and a poll_url — ingestion and the pipeline run continue asynchronously, so the caller never blocks on OCR or LLM work.

Two optional tagging fields ride along and are stamped on every document the call ingests: batch_id, an opaque grouping key for correlating the run with an external job or batch, and metadata, a flat key-value object for anything else the caller wants to carry through. Both are echoed back by GET /v1/run/:id, and both surface on the ingested documents (batch_id / metadata on the document reads).

Unlike POST /v1/process, this endpoint does not deduplicate submissions — every call starts a fresh run. Byte-identical documents are still content-deduplicated at the ingestion layer (the run reads the canonical document's data).
POST/v1/run

curl

Response

Response fields (202)

run_iduuidThe run request id — the polling handle.
spec_iduuidThe Spec being run.
statusstringAlways processing on acceptance.
input_countintegerTotal inputs accepted (files + file_urls).
poll_urlstringRelative URL to poll: /v1/run/:id.

Response (202)

{
  "run_id": "a8716d18-978d-4d19-8ca5-8b3784ca857c",
  "spec_id": "1fc7807e-e1aa-4504-b796-5709986e78ed",
  "status": "processing",
  "input_count": 2,
  "poll_url": "/v1/run/a8716d18-978d-4d19-8ca5-8b3784ca857c"
}
For push-style consumption, subscribe to the run.completed / run.failed webhooks (POST /v1/webhooks), or configure a delivery binding on the document.structured signal to receive each document's structured fields as its own webhook payload the moment it finishes.

Errors

Error responses

400missing_spec_id / no_input / invalid_metadataspec_id absent or malformed, no file or file_url supplied, or metadata is not a valid flat JSON object.
401unauthorizedMissing or invalid API key.
402insufficient_creditsCredit balance too low for the ingest work — no documents are ingested and no run is created.
413file_too_largeA file exceeds your tier's per-file size cap.
429rate_limit_exceededDaily submission quota for the run namespace exhausted.

Related

Poll a Run
Run a Pipeline (documents already uploaded)
Webhook Events
Credits & Usage