Get Rail

Read a Spec's pipeline rail with GET /v1/schemas/:id/rail: the ordered stages (source, extraction, resolution, validation, assembly) and per-stage config.

The rail is the ordered list of pipeline stages composed onto a Spec (a user_schema). It is what POST /v1/pipelines compiles and runs, so it is the prerequisite for running a Spec from the API without the UI. This endpoint returns the rail as it is stored. It reads back as an empty array until a rail has been set.

Each stage carries a type plus optional name, sub, and a per-stage json config. 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. The source, deliver, reconcile, sanitize, and triage types are composition markers in the rail order.

Every stored stage also carries an id — the handle the Spec editor uses to select and reorder stages. Ids are assigned at write time when omitted (s-<type>, deduplicated), so a rail you set programmatically reads back with ids filled in even if you never sent any. Treat the read as the canonical form of what you last wrote: round-tripping the returned array back into [Set Rail](set-spec-rail) is always a legal no-op.

Read the rail before composing changes: because the PUT counterpart replaces the rail wholesale, the safe editing pattern is GET, modify the returned array, PUT it back. The read also tells you which validation checkpoints and Data Policies the Spec currently references (json.stage_ids, json.policy_ids), which you can dereference via the [validation-stages](validation-stages) and Data Policies endpoints.

curl -H "Authorization: Bearer $TALONIC_API_KEY" \
  "https://api.talonic.com/v1/schemas/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rail"

Response

Returns { "rail": [...] }, where each element is a stage object. The array reflects the stored composition order. An empty array means no rail has been set yet, in which case the Spec cannot be run until you set one.

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

Errors