Skip to main content

List Diffs

List pending, approved, and rejected diffs between schema graph class versions. Shows proposed changes for the approve/reject workflow.

Diffs represent proposed changes between schema graph class versions. When the platform discovers new fields or detects field type changes, it creates a diff that can be reviewed and either approved (promoting the changes to a new version) or rejected (discarding them). This endpoint returns all diffs, optionally filtered by class or review status.

Diffs are classified as additive (new fields only) or breaking (field removals or type changes). Breaking diffs may affect downstream extraction jobs that depend on the removed fields.
GET/v1/schema-graph/diffs

Response

Response fields

dataarrayArray of diff objects.
data[].idstringDiff UUID.
data[].schema_class_idstringSchema class UUID this diff belongs to.
data[].from_versionintegerSource version number.
data[].to_versionintegerTarget version number.
data[].review_statusstringReview status: pending, approved, or rejected.
data[].classificationstring | nullDiff classification (e.g. additive, breaking).
data[].added_fieldsarrayFields added in this diff.
data[].removed_fieldsarrayFields removed in this diff.
data[].type_changesarrayFields whose type changed in this diff.
data[].created_atstringISO 8601 creation timestamp.
data[].links.selfstringURL to this diff.

Response

{
  "data": [
    {
      "id": "diff-uuid-1",
      "schema_class_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "from_version": 2,
      "to_version": 3,
      "review_status": "pending",
      "classification": "additive",
      "added_fields": ["total"],
      "removed_fields": [],
      "type_changes": [],
      "created_at": "2024-09-14T10:00:00.000Z",
      "links": { "self": "/v1/schema-graph/diffs/diff-uuid-1" }
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Filter by status=pending to build a review queue for ontology changes. Inspect the added_fields, removed_fields, and type_changes arrays to assess impact, then call POST /v1/schema-graph/diffs/{id}/approve or /reject to action each diff. The classification field (additive vs breaking) helps prioritize which diffs need careful review.

Related

Approve Diff
Reject Diff