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.

GET/v1/specs

Query parameters

limitintegerPage size, 1–100. Defaults to 20.

cursorstringOpaque cursor from the previous page's `next_cursor`.

orderstring`desc` (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, 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"
      }
    }
  ],
  "pagination": { "total": 6, "limit": 20, "has_more": false, "next_cursor": null }
}

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.

Get a Spec

Published Versions

List Schemas

List Specs

Response

Related