Skip to main content
GET
/
{collection}
/
{id}
/
diff
/
{v1}
/
{v2}
Diff Versions
curl --request GET \
  --url https://api.example.com/{collection}/{id}/diff/{v1}/{v2}
{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "500": {},
  "501": {},
  "from_version": 123,
  "to_version": 123,
  "changes": [
    {
      "field": "<string>",
      "from": "<any>",
      "to": "<any>"
    }
  ]
}
Compares two versions of a document and returns a detailed list of field-level changes between them.

​
Endpoint

GET /{collection}/{id}/diff/{v1}/{v2}

​
Path Parameters

​
collection
string
required
The name of the collection containing the document
​
id
string
required
The unique identifier of the document
​
v1
integer
required
The starting version number (must be less than v2)
​
v2
integer
required
The ending version number (must be greater than v1)

​
Authentication

Requires valid authentication. The user must have read permission on the collection and access to the specific document.

​
Response

Returns the differences between the two versions.
​
from_version
integer
The starting version number (v1)
​
to_version
integer
The ending version number (v2)
​
changes
array
Array of field-level changes
​
field
string
Field path using dot notation (e.g., address.city)
​
from
any
Value in v1 (null if field didn’t exist)
​
to
any
Value in v2 (null if field was removed)

​
Example Request

curl -X GET "https://api.example.com/employees/emp_12345/diff/1/3" \
  -H "Authorization: Bearer <token>"

​
Example Response

{
  "from_version": 1,
  "to_version": 3,
  "changes": [
    {
      "field": "department",
      "from": "Engineering",
      "to": "Marketing"
    },
    {
      "field": "salary",
      "from": 70000,
      "to": 85000
    },
    {
      "field": "manager_id",
      "from": "mgr_001",
      "to": "mgr_002"
    },
    {
      "field": "skills",
      "from": ["JavaScript", "React"],
      "to": ["JavaScript", "React", "Node.js"]
    }
  ]
}

​
Diff Format Examples

​
Field Added

When a field is added in v2: 
{
  "field": "phone",
  "from": null,
  "to": "+1-555-0123"
}

​
Field Removed

When a field is removed in v2: 
{
  "field": "temporary_access",
  "from": true,
  "to": null
}

​
Field Modified

When a field value changes: 
{
  "field": "status",
  "from": "active",
  "to": "inactive"
}

​
Nested Field Changes

Nested fields use dot notation: 
{
  "field": "address.city",
  "from": "San Francisco",
  "to": "New York"
}

​
Array Changes

Arrays are compared as complete values: 
{
  "field": "tags",
  "from": ["developer", "frontend"],
  "to": ["developer", "frontend", "lead"]
}

​
Object Changes

For nested objects, each changed field is reported separately: 
[
  {
    "field": "address.street",
    "from": "123 Main St",
    "to": "456 Oak Ave"
  },
  {
    "field": "address.city",
    "from": "Boston",
    "to": "Seattle"
  }
]

​
Diff Calculation

The diff engine:
  1. Reconstructs both versions to their full document state
  2. Recursively compares all fields using dot notation for nested paths
  3. Identifies three types of changes:
    • Added: Field exists in v2 but not v1 (from: null)
    • Modified: Field value changed between versions
    • Removed: Field exists in v1 but not v2 (to: null)
  4. Returns changes sorted by field name for consistent ordering

​
Field-Level Permissions

Changes to fields that the user doesn’t have permission to read are automatically filtered out. If a field is in the deny list or not in the allow list, it won’t appear in the changes array.

​
Error Responses

​
400
error
Bad Request - Invalid parameters or v1 >= v2
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "v1 must be less than v2",
    "details": {
      "v1": 5,
      "v2": 3
    }
  }
}
​
401
error
Unauthorized - Authentication required
​
403
error
Forbidden - Insufficient permissions
​
404
error
Not Found - One or both versions not found
{
  "error": {
    "code": "VERSION_NOT_FOUND",
    "message": "One or both versions not found",
    "details": {
      "collection": "employees",
      "id": "emp_12345",
      "v1": 1,
      "v2": 99
    }
  }
}
​
500
error
Internal Server Error - Failed to compute diff
​
501
error
Not Implemented - Versioning is not enabled

​
Use Cases

  • Audit Trail: Review what changed between versions
  • Change Tracking: Monitor specific field modifications over time
  • Compliance: Generate reports showing data changes for regulatory purposes
  • Debugging: Identify when and how a field value changed
  • Approval Workflows: Show reviewers what will change before approving

​
Notes

  • Changes are sorted alphabetically by field name
  • Only fields that actually changed are included in the response
  • The comparison is performed on the reconstructed full documents
  • Denied fields are excluded from the changes array
  • Both versions must exist for the document

Build docs developers (and LLMs) love

Get started for freeTalk to us