Skip to main content

List Versions

List every published version of a schema graph class, newest first. Each version snapshots the JSON Schema definition and field registry IDs at publish time.

A class version is an immutable snapshot of a schema graph class at one point in its evolution: the JSON Schema definition of its fields plus the field registry IDs it referenced when published. This endpoint returns the complete version history of a class, ordered by version number descending, so the first item is always the current structure.

Versions are published by the platform as the ontology evolves: when new documents introduce fields or change field types, schema generation produces a new snapshot and version numbers increment monotonically. Each transition between consecutive versions is also recorded as a diff you can review via the diffs endpoints.

GET/v1/schema-graph/classes/{id}/versions

curl

Response

Response fields

dataarrayArray of version objects.
data[].idstringVersion UUID.
data[].schema_class_idstringParent schema class UUID.
data[].version_numberintegerVersion number (monotonically increasing).
data[].json_schemaobjectJSON Schema definition for this version.
data[].field_idsarrayArray of field registry UUIDs included in this version.
data[].created_atstringISO 8601 creation timestamp.

Response

{
  "data": [
    {
      "id": "ver-uuid-3",
      "schema_class_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "version_number": 3,
      "json_schema": {
        "type": "object",
        "properties": {
          "invoice_number": { "type": "string" },
          "vendor": { "type": "string" },
          "total": { "type": "number" }
        }
      },
      "field_ids": ["field-uuid-1", "field-uuid-2", "field-uuid-3"],
      "created_at": "2024-09-01T00:00:00.000Z"
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
404not_foundNo schema class with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Compare two versions by fetching them individually with GET /v1/schema-graph/classes/{id}/versions/{version} and diffing their json_schema and field_ids arrays, or read the precomputed change record from GET /v1/schema-graph/diffs?schema_class_id={id}. This is useful for auditing how a class evolved, or for building a changelog UI that shows added and removed fields per version.

Versions are read-only history. There is no rollback endpoint: the ontology evolves forward, and every structural change between consecutive versions is captured as a reviewable diff.

Related

Get Version
List Diffs
Field Registry