Skip to main content

List Specs

List every Spec in your workspace with its schema, published version, and links. A Spec and the schema it runs on are two records with two different IDs.

A Spec is the authoring document behind /specs/{id} in the app. Publishing a Spec *materializes* it onto a schema, which is what pipelines actually run. The two are separate records with separate IDs: the ID in the Spec editor URL is not the schema ID, and vice versa.

This is the single most common surprise on this API. If you take the UUID out of a /specs/... browser URL and look it up under /v1/schemas/{id}, you will get a 404 — not because the Spec is missing, but because that endpoint is keyed on schema IDs. Use schema_id below to cross over, or spec_id on GET /v1/schemas to cross back.

search filters by name, case-insensitively; % and _ in the query are treated literally, so searching order_ matches only names containing that exact text. Pagination is keyset-based: the opaque cursor encodes the last row's creation time and id, keeping pages stable while Specs are being created, and pagination.total reflects the filtered count before the cursor is applied, so it stays constant across pages.

GET/v1/specs

Query parameters

limitintegerPage size, 1–100. Defaults to 20.
cursorstringOpaque cursor from the previous page's next_cursor.
orderstringdesc (default) or asc, by creation time.
searchstringCase-insensitive name search.

List Specs

curl -H "Authorization: Bearer $TALONIC_API_KEY" \
  "https://api.talonic.com/v1/specs?limit=20"

Response

Response fields

data[].idstringThe Spec ID — the one in the /specs/{id} editor URL.
data[].namestringSpec name.
data[].schema_idstring | nullThe schema this Spec is materialized onto. A different record from the Spec. Null until first published.
data[].versioninteger | nullPublished head version — the number the Spec editor shows. Null if never published.
data[].materialized_versioninteger | nullThe version whose configuration is live on the schema — what a run executes. Normally equal to version.
data[].materialized_atstring | nullWhen that version last converged onto the schema (ISO 8601).
data[].field_countintegerFields declared by the Spec.
data[].node_countintegerStages in the rail. Not the number of executable phases — see Get a Spec.
data[].linksobjectself, versions, dashboard (a deep link into the Spec editor), and — once the Spec has a schema — schema and rail.

Response

{
  "data": [
    {
      "id": "e2144027-39c0-44e8-a196-72be1e360749",
      "name": "Order Intake V25",
      "description": null,
      "schema_id": "2e3ddf8c-b9ab-4934-bb11-a371e9c5d7a8",
      "version": 3,
      "materialized_version": 3,
      "materialized_at": "2026-04-25T14:30:00.000Z",
      "field_count": 60,
      "node_count": 7,
      "created_at": "2026-04-20T09:12:00.000Z",
      "updated_at": "2026-04-25T14:30:00.000Z",
      "links": {
        "self": "/v1/specs/e2144027-39c0-44e8-a196-72be1e360749",
        "versions": "/v1/specs/e2144027-39c0-44e8-a196-72be1e360749/versions",
        "schema": "/v1/schemas/2e3ddf8c-b9ab-4934-bb11-a371e9c5d7a8",
        "rail": "/v1/schemas/2e3ddf8c-b9ab-4934-bb11-a371e9c5d7a8/rail",
        "dashboard": "https://app.talonic.com/specs/e2144027-39c0-44e8-a196-72be1e360749"
      }
    }
  ],
  "pagination": { "total": 6, "limit": 20, "has_more": false, "next_cursor": null }
}

Each row's links object carries the useful next hops: versions for the publish history and — once the Spec has been published — schema and rail on the schema-keyed side of the API, plus dashboard, a deep link into the Spec editor for humans. field_count and node_count are cheap summary counters; node_count counts rail stages as authored, which is not the number of executable phases — the compiled plan lives on Get a Spec.

Specs are read-only over the API. Authoring happens in the Spec editor, which re-converges the live schema on every publish — an API write would be overwritten by the next one.

Frequently asked questions

Why does my Spec ID return 404 on /v1/schemas/{id}?+
Because a Spec and its schema are two different records. The ID in the /specs/... editor URL is the Spec ID; /v1/schemas/{id} is keyed on schema IDs. Call GET /v1/specs/{spec_id} and use the schema_id it returns, or list schemas and match on their spec_id field.
My Spec is published to v3, but the schema reports version 1. Why?+
They are unrelated counters. version on a schema is the legacy schema-version counter, which a Spec-authored schema never advances. The Spec's own published version is version on this endpoint, spec_version on GET /v1/schemas, and the full history is at GET /v1/specs/{id}/versions.
What is the difference between version and materialized_version?+
version is the published head — what the editor shows. materialized_version is the version whose configuration is currently live on the schema, i.e. what a run executes. They are normally identical; materialized_version lags when a publish was refused by the acknowledgement gate or a stale activation no-opped.
Can I create or edit a Spec through this API?+
No — Specs are read-only on the API-key plane. Authoring happens in the Spec editor, which re-converges the live schema on every publish. The one structural write open to API keys is PUT /v1/schemas/{id}/rail, which edits the rail on the schema side and cannot change extraction model settings.

Related

Get a Spec
Published Versions
List Schemas
Update a Rail
Run a Spec