Published Versions

List every published version of a Spec via GET /v1/specs/{id}/versions: immutable version numbers, sha256 content hashes, and which version is live now.

Every publish appends an immutable version to the Spec's history — version rows are never edited or deleted, and numbers only ascend. This endpoint lists them newest first; it is where a Spec's "v3" actually lives. The response is deliberately identity-only: version number, content hash, timestamp, and the materialization flag. The Spec document's content — rules, prompts, samples, gate configuration — is not exposed anywhere on the public API.

content_hash is the sha256 of the canonical JSON serialization of the Spec document, so it is a stable fingerprint of the configuration itself: identical hashes mean identical Specs wherever they appear. Publishing a document identical to the current head is a no-op that appends nothing, which is why consecutive versions always differ — and why the hash works as a cheap drift check: record the hash your integration was validated against and compare it on a schedule.

is_materialized flags the version whose configuration is actually live on the schema — the one a new pipeline run executes. It normally sits on the newest version, but publishing and materializing are separate steps, so the flag can rest on an older version while the head waits to converge. The Spec summary reports the same state as version versus materialized_version on [List Specs](list-specs).

Do not confuse this with GET /v1/schemas/{id}/versions, which reads the unrelated legacy schema-version counter. A Spec-authored schema never advances that counter, so that endpoint is normally empty for these schemas.

GET/v1/specs/{id}/versions

Path parameters

id*stringSpec UUID.

List versions

curl -H "Authorization: Bearer $TALONIC_API_KEY" \
  "https://api.talonic.com/v1/specs/e2144027-39c0-44e8-a196-72be1e360749/versions"

Response

Response fields

data[].versionintegerVersion number. Publishes only ever append.

data[].content_hashstringsha256 of the canonical Spec document. Identical hashes are identical Specs.

data[].created_atstringWhen the version was published (ISO 8601).

data[].is_materializedbooleanWhether this is the version currently live on the schema.

Response

{
  "data": [
    { "version": 3, "content_hash": "9f2c…", "created_at": "2026-04-25T14:30:00.000Z", "is_materialized": true },
    { "version": 2, "content_hash": "41ab…", "created_at": "2026-04-22T10:05:00.000Z", "is_materialized": false },
    { "version": 1, "content_hash": "c7d0…", "created_at": "2026-04-20T09:12:00.000Z", "is_materialized": false }
  ]
}

Exactly one version is normally flagged is_materialized. If none is, the Spec has been published but never converged onto a schema.

The list has no pagination — the full history returns in one response, newest first. Publishes are explicit authoring events, so histories stay short. If you need the publish time of the live configuration, take the row where is_materialized is true, not the newest row.

To see what a version change actually did to execution, pair this history with the structure reads: GET /v1/specs/{id} compiles the current rail into phases, and GET /v1/pipelines/{id}?include=phases returns the plan a specific run froze at creation. A run that predates the newest publish shows the older plan — the version timestamps here tell you which runs straddle a configuration change.

Frequently asked questions

Why is /v1/schemas/{id}/versions empty for my Spec-authored schema?+

That endpoint reads the legacy schema-version counter, which a Spec-authored schema never advances. Spec versions live here, at `GET /v1/specs/{id}/versions`.

Can two versions have the same content hash?+

No — a publish that would produce a document identical to the head is a no-op and appends nothing. Identical hashes across different Specs do mean identical documents.

Why is is_materialized not on the newest version?+

Publishing and materializing are separate steps: a publish appends the version row, and activation converges it onto the schema. When activation has not happened — or a stale activation no-opped — the flag stays on the last version that actually converged. Runs execute the materialized version, not the head.

Can I read the content of an old version?+

Not over the public API — this surface is identity-only and never returns the Spec document itself (no rules, prompts, samples, or gate configuration). Use `content_hash` to tell whether two versions are identical, and the Spec editor's history to inspect what changed.

Do versions ever get renumbered or deleted?+

No. The history is append-only: version numbers ascend monotonically and existing rows are never edited. That makes the pair of version number and content_hash a reliable audit anchor to cite in change-management records.

Published Versions

Response

Frequently asked questions

Related