Versions

List, diff, and roll back a Spec versions. Schema versioning is append-only: every change creates a new version retained for history and diffing.

Spec versioning is append-only. Every change that regenerates the Spec creates a new version, and old versions are 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 rollback does not delete history. It creates a new version that copies the target version, so the version chain keeps moving forward and the rollback itself is auditable. This means you can always roll forward again to where you were before the rollback.

Response

[
  {
    "version_number": 3,
    "created_at": "2024-09-14T10:35:00.000Z",
    "created_by": "api",
    "fields": [
      { "field_name": "invoice_number", "data_type": "string" },
      { "field_name": "total", "data_type": "number" }
    ]
  },
  {
    "version_number": 2,
    "created_at": "2024-09-12T09:10:00.000Z",
    "created_by": "user",
    "fields": [
      { "field_name": "invoice_number", "data_type": "string" }
    ]
  }
]

The diff endpoint returns the field-level changes between from and to (added, removed, and modified fields). Rollback returns the newly created version that copies the requested target.

Errors