Set Rail

Compose a Spec's pipeline rail so it can run via POST /v1/pipelines without the UI. Replace the ordered stages and their per-stage config in one PUT call.

Set the Spec composed pipeline rail. This is what makes a Spec runnable from the API: once a rail is set, POST /v1/pipelines compiles it and runs your documents through it, no UI required. The PUT replaces the stored rail wholesale, so send the full ordered list each time. Passing an empty array clears the rail.

A minimal runnable rail is a single extraction stage: {"rail":[{"type":"schema","name":"Extraction"}]}. From there you compose the stages you need in order. The compiler maps registry to transfer, schema to extraction, resolve to resolution (one phase per active policy), valid to a positional validation checkpoint, and assembly to a post-run compose.

Stages that need configuration carry it under json. A resolve stage carries json.policy_ids (the Data Policies it runs). A valid stage carries json.stage_ids (the member validation-stage ids, configured via the validation-stages endpoints) and an optional json.target_phases. An assembly stage carries json.grouping_field and json.anchor_field. The rail accepts at most 50 stages.

Two write-boundary behaviors matter for integrations. First, stage ids: any stage sent without an id gets one assigned before the rail is persisted (s-<type>, deduplicated), and the response echoes the rail with ids filled in — the Spec editor selects stages by id, so this keeps a programmatically composed rail editable in the UI. Second, extraction model settings are Talonic-managed: a rail write that would change the extraction stage's json.settings.model or json.settings.input_mode is rejected with 403 forbidden. Round-tripping an exported rail with those settings unchanged stays legal.

curl -X PUT https://api.talonic.com/v1/schemas/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rail \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rail":[{"type":"schema","name":"Extraction"}]}'

{
  "rail": [
    { "type": "schema", "name": "Extraction" },
    {
      "type": "resolve",
      "name": "Resolution",
      "json": { "policy_ids": ["b2c3d4e5-f6a7-8901-bcde-f23456789012"] }
    },
    {
      "type": "valid",
      "name": "Totals checkpoint",
      "json": {
        "stage_ids": ["f1e2d3c4-b5a6-7890-abcd-ef1234567890"],
        "target_phases": ["resolve"]
      }
    },
    {
      "type": "assembly",
      "name": "Compose",
      "json": { "grouping_field": "contract_number", "anchor_field": "document_kind" }
    }
  ]
}

Response

Returns { "rail": [...] } echoing the rail you set, with server-assigned stage ids filled in. After setting a rail, compile and run it with POST /v1/pipelines followed by POST /v1/pipelines/:id/start.

{
  "rail": [
    { "type": "schema", "name": "Extraction", "id": "s-schema" }
  ]
}

Errors