Get one Spec's full structure: identity and version state, the schema it materializes onto, nodes[] — the rail as authored, in editing order — and phases[] — the compiled execution plan, in run order. A validation checkpoint expands to one phase per gate, so the two lists differ on purpose. fields[] maps Spec fields to schema fields. Pass include_versions to also fetch versions[], the Spec's published version history, newest first.
When to use
You need to explain what a run will do before starting it.
You want to confirm a Spec is published (version non-null) before calling talonic_run_spec.
You need to map Spec field names to schema field keys.
When not to use
You want to list all Specs — use talonic_list_specs.
You are ready to execute the pipeline — use talonic_run_spec.
Parameters
Parameter
Type
Description
spec_id *
string
Spec UUID (from `talonic_list_specs`).
include_versions
boolean
Also fetch the published versions list (adds `versions[]`).
Response shape
Fields
Parameter
Type
Description
id
string
Spec UUID.
name
string
Spec name.
version
number|null
Published version number, or null if never published.
materialized_version
number|null
Version currently materialized onto the schema, or null.
schema.id
string
The schema this Spec materializes onto.
nodes[].type
string
Stage type in the authored rail: one of `source`, `registry`, `schema`, `resolve`, `valid`, `assembly`, `deliver`, `reconcile`, `sanitize`, `triage`, `switch`.
nodes[].name
string
Node display name.
phases[].number
number
Phase order in the compiled execution plan.
phases[].type
string
Compiled phase type, derived from the rail stage it came from (`rail_stage_id` joins back to `nodes[].node_id`); Source and Data Product stages produce no phase, and a validation checkpoint expands to one phase per gate.
phases[].name
string
Phase display name.
fields[].name
string
Spec field name, mapped to its schema field.
versions[].version
number
Published version number (present when `include_versions` is true).
versions[].is_materialized
boolean
Whether this version is the one currently materialized onto the schema.
Frequently asked questions
Why do nodes and phases differ?+−
nodes[] is the rail as authored, in editing order; phases[] is the compiled execution plan, in run order. A validation checkpoint expands into one phase per gate, so a single authored node can produce several phases — the two lists differ on purpose.