Node Jobs

Run a single engine stage at a time with the node jobs API: transfer, extract, resolve, validate, or assemble over a shared record set chained by record_set_id.

Node jobs expose the individual stages of Talonic's structuring pipeline as standalone API primitives. Where a Spec pipeline runs the whole rail end to end, node jobs let you run one stage at a time (Transfer, Extraction, Resolution, Validation, or Assembly) and chain them yourself over a shared record set. Each call is asynchronous: it returns 202 with a node-run id you poll for status and results.

The typical chain starts with POST /v1/nodes/transfer (or extract) against a set of document_ids and a schema_id, which creates a record set and fills cells. Each subsequent stage takes the record_set_id from the previous one: extract fills gaps the registry could not, resolve applies Data Policies, validate runs your gates, and assemble composes grouped documents into a product record set. This gives you fine-grained control over the structuring flow when a single Spec run is too coarse.

Stage endpoints

curl -X POST https://api.talonic.com/v1/nodes/transfer \
  -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"]
  }'

The node run object

Every stage endpoint returns 202 Accepted with a node run: a standalone run of a single engine stage over a record set. Cell-producing stages carry the record_set_id you chain into the next stage; an assembly run additionally carries product_record_set_id for the composed records.

{
  "id": "nr_uuid_1",
  "node_type": "transfer",
  "status": "queued",
  "record_set_id": "rs_uuid_1",
  "product_record_set_id": null,
  "total": 2,
  "completed": 0,
  "errors": 0,
  "error_message": null,
  "created_at": "2024-09-14T10:32:00.000Z",
  "links": {
    "self": "/v1/nodes/nr_uuid_1",
    "results": "/v1/nodes/nr_uuid_1/results"
  }
}

Polling a node run

Each stage call returns a node-run id. Poll GET /v1/nodes/:id for its status and progress counters, and read GET /v1/nodes/:id/results once it completes. For a validation node, results are the per-record and per-field verdicts. For cell-producing nodes (transfer, extract, resolve, assemble), results point you to the record-set read endpoints where the cells live. Carry the record_set_id forward to the next stage to chain the pipeline.

Errors