Run Pipeline

Run a document processing pipeline via API: POST /v1/pipelines compiles a configured Spec's rail and runs extraction, resolution, and validation over documents.

POST /v1/pipelines is Talonic's document processing pipeline API: it runs a configured Spec over a set of documents in one call. A Spec is a Schema plus a composed rail — Source → Field Registry → Extraction → Resolution → Validation → Data Product — together with its Data Policies and validation gates. A pipeline is one run of that Spec on the engine. You name the Spec by its schema_id and pass the documents to run. The server does the rest: it compiles the Spec's saved rail into the pipeline's phase config, so you never hand-build phases. Every Spec compiles to the same engine.

Compilation is server-side and governed. The rail expands into one resolution phase per active policy, one validation phase per member gate at its checkpoint position, an enforced extraction phase, and a pipeline-scoped assembly step appended after all documents finish. The run is created, the documents are attached, and processing starts immediately. The response status is active.

This is the governed tier. For a quick one-off job that does not justify configuring a Spec, use POST /v1/jobs instead: jobs run the standard 4-phase pipeline against a schema with no saved rail, no policy-driven resolution phases, and no validation checkpoints. Pipelines are the right choice when you have curated a Spec with resolution policies and positional validation gates and want review holdback enforced.

A pipeline's row results are read through the data product it produces. After the run finishes, call POST /v1/pipelines/{id}/data-product and then read rows through the data-products endpoints. The data product is also where per-cell review holdback is enforced: fields a blocking gate parked for review surface with status only until a reviewer resolves them. This endpoint requires an API key with the write scope.

The pipeline_mode parameter controls how the call targets pipelines. The default, new, always creates a fresh pipeline. append adds the documents to the newest eligible existing pipeline on the Spec instead, so repeated calls accumulate into one growing table — the response then reports appended: true and reuses that pipeline's id. Omitted, the Spec's own Source-stage setting applies. Every call also returns a run_id: the submission-group id stamped on this call's documents, usable as the run_id filter on GET /v1/pipelines/{id}/results to read back exactly what this call submitted.

curl -X POST https://api.talonic.com/v1/pipelines \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "sch_uuid_1",
    "document_ids": ["doc_uuid_1", "doc_uuid_2"],
    "name": "Lease Agreements September"
  }'

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "active",
  "schema": { "id": "sch_uuid_1", "name": "Lease Agreement" },
  "document_count": 24,
  "enqueued_documents": 24,
  "appended": false,
  "run_id": "7d5c3b1a-9e8f-4021-b6a4-2c8d0e1f3a5b",
  "message": "Pipeline created and queued for processing.",
  "links": {
    "self": "/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "progress": "/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890/progress",
    "data_product": "/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890/data-product"
  }
}

Errors