Specs

Get a Spec's structure

Spec identity, version state, and its stages with their live ids.

Two stage lists, and they differ on purpose.

  • nodes — the rail as authored, in editing order. Includes non-executing stages such as Source and Data Product.
  • phases — the compiled execution plan, in run order. Source and Data Product produce no phase; a validation checkpoint expands to one phase per member gate. So the two lists rarely have the same length.

rail_stage_id on a phase is the join key back to nodes[].node_id. It is also the per-step cost-attribution key, so a phase here lines up with its spend on GET /v1/usage/pipelines/{id}.

phases describes what a new run would execute, compiled from the current rail. To see what a specific run actually executed, read its frozen plan via GET /v1/pipelines/{id}?include=phases — same shape, same join key.

Structure and ids only: no rules, gate configuration, prompts, samples, or ground truth. Editing stays in the Spec editor.

get/v1/specs/{id}

Request

  • Base URL: https://api.talonic.com
  • URL: https://api.talonic.com/v1/specs/{id}
  • Auth: HTTP bearer

Path parameters

idstring uuid required

Response

Spec structure.

idstring uuid required

The Spec id — the one in the /specs/{id} editor URL.

namestring required
descriptionstring nullable
schema_idstring uuid nullable

The schema this Spec is materialized onto — a DIFFERENT record from the Spec. null until the Spec is first published. Use it against /v1/schemas/{schema_id} and its sub-resources.

versioninteger nullable

Published head version — what the editor shows. null if never published.

materialized_versioninteger nullable

The version whose configuration is live on the schema — what a run executes. Normally equal to version; it lags when a publish was refused by the acknowledgement gate or a stale activation no-opped.

materialized_atstring date-time nullable
field_countinteger

Fields declared by the Spec.

node_countinteger

Stages in the rail — the nodes count on the detail route. NOT the number of executable phases: a Source or Data Product marker compiles to no phase and a validation checkpoint expands to one per gate, so read phases on GET /v1/specs/{id} for the executable plan.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "e2144027-39c0-44e8-a196-72be1e360749",
  "name": "Bridgeway V25",
  "schema_id": "2e3ddf8c-b9ab-4934-bb11-a371e9c5d7a8",
  "version": 3,
  "materialized_version": 3,
  "field_count": 60,
  "node_count": 7,
  "nodes": [
    {
      "node_id": "s-schema",
      "position": 1,
      "type": "schema",
      "name": "Extraction"
    }
  ],
  "phases": [
    {
      "number": 3,
      "phase_id": "phase-3",
      "type": "matching",
      "name": "Matching",
      "rail_stage_id": "3a76507f-00ef-4ebd-b8f1-e78a02139634"
    }
  ],
  "fields": [
    {
      "field_id": "c086cb2d-06bf-4c22-9007-c6e455531133",
      "user_schema_field_id": "a3952c40-9f78-41a3-975f-57c5c79c3fae",
      "name": "shipper_number",
      "type": "string"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.