Versions

List, diff, and roll back a Spec's published field versions. Versioning is append-only: every publication snapshots the fields for history, diffing, and audit.

Spec versioning is append-only. Each version is an immutable snapshot of the Spec's field definitions at the moment it was published (a draft was promoted), retained for history and diffing. These endpoints let you list versions newest first, diff any two by their version numbers, fetch one by number, and roll back to an earlier version. A Spec that has never published a version returns an empty array.

A rollback never deletes history. POST .../versions/rollback creates a new active draft named Rollback to v<n> whose fields copy the target version, recording the version you rolled away from as its base_version_number. The response is that draft, not a new version: the version chain advances only when the draft is promoted (published), at which point the rollback becomes the newest version. Until then the live Spec is unchanged, so a rollback is always reviewable before it takes effect.

The diff endpoint compares any two versions field by field. Its response carries entries (one per field, with a status of added, removed, modified, or unchanged, the field's shape on each side, and the individual changes), the summary arrays fieldsAdded / fieldsRemoved / fieldsModified, and an isBreaking flag for changes that would break downstream consumers of the produced table, such as a removed field.

curl -s "https://api.talonic.com/v1/schemas/a1b2c3d4-e5f6-7890-abcd-ef1234567890/versions/diff?from=2&to=3" \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

The list endpoint returns a bare array of version snapshots, newest first. Each snapshot is the persisted user_schema_versions row: the monotonic version_number, the fields captured at publication, a field_count, who promoted it (promoted_by, a user UUID, null for system publications), and timestamps. Versions are immutable — nothing on this surface edits one.

{
  "entries": [
    {
      "fieldName": "total",
      "status": "added",
      "liveField": null,
      "draftField": { "field_name": "total", "data_type": "number" },
      "changes": []
    },
    {
      "fieldName": "invoice_number",
      "status": "unchanged",
      "liveField": { "field_name": "invoice_number", "data_type": "string" },
      "draftField": { "field_name": "invoice_number", "data_type": "string" },
      "changes": []
    }
  ],
  "fieldsAdded": ["total"],
  "fieldsRemoved": [],
  "fieldsModified": [],
  "isBreaking": false
}

Rollback returns the draft it created — name Rollback to v<n>, status active, fields copied from the target, and base_version_number recording the version that was current when you rolled back. Promote (publish) that draft to make the rollback the live version; discard it to abandon the rollback with no effect on the Spec.

Errors