Skip to main content
GET
/
{collection}
/
{id}
/
versions
/
{v}
Get Version
curl --request GET \
  --url https://api.example.com/{collection}/{id}/versions/{v}
{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "500": {},
  "501": {},
  "data": {
    "_id": "<string>",
    "_version": 123,
    "...": "<any>"
  },
  "metadata": {
    "updated_by": "<string>",
    "updated_at": "<string>"
  }
}
Retrieves the complete document data for a specific version number. The system reconstructs the document state as it existed at that version.

​
Endpoint

GET /{collection}/{id}/versions/{v}

​
Path Parameters

​
collection
string
required
The name of the collection containing the document
​
id
string
required
The unique identifier of the document
​
v
integer
required
The version number to retrieve (must be >= 1)

​
Authentication

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

​
Response

Returns the document data at the specified version along with metadata.
​
data
object
The document data as it existed at this version
​
_id
string
Document identifier
​
_version
integer
Version number
​
...
any
All other document fields (subject to field-level permissions)
​
metadata
object
Version metadata
​
updated_by
string
User ID who created this version
​
updated_at
string
ISO 8601 timestamp when this version was created

​
Example Request

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

​
Example Response

{
  "data": {
    "_id": "emp_12345",
    "_version": 2,
    "name": "John Doe",
    "email": "[email protected]",
    "department": "Marketing",
    "salary": 75000,
    "created_at": "2024-01-10T09:15:00Z",
    "updated_at": "2024-02-20T14:22:00Z",
    "updated_by": "user_456"
  },
  "metadata": {
    "updated_by": "user_456",
    "updated_at": "2024-02-20T14:22:00Z"
  }
}

​
Version Reconstruction

The system uses two storage modes to efficiently manage versions:

​
Full Mode

Stores a complete snapshot of the document. Version 1 is always stored in full mode to serve as the base version. 
{
  "_id": "...",
  "collection": "employees",
  "doc_id": "emp_12345",
  "version": 1,
  "mode": "full",
  "data": {
    "name": "John Doe",
    "email": "[email protected]",
    "salary": 70000
  }
}

​
Diff Mode

Stores only the changes from the previous version. This reduces storage space for large documents with small changes. 
{
  "_id": "...",
  "collection": "employees",
  "doc_id": "emp_12345",
  "version": 2,
  "mode": "diff",
  "changes": [
    {
      "field": "salary",
      "op": "set",
      "from": 70000,
      "to": 75000
    },
    {
      "field": "department",
      "op": "set",
      "from": "Engineering",
      "to": "Marketing"
    }
  ]
}
When retrieving a diff-mode version, the system:
  1. Starts with the base version (version 1)
  2. Applies all changes sequentially up to the requested version
  3. Returns the reconstructed document state

​
Field Operations

The diff mode supports two operations:
  • set: Field was added or modified
  • unset: Field was removed
Nested fields use dot notation (e.g., address.city).

​
Error Responses

​
400
error
Bad Request - Invalid parameters
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid version number",
    "details": {
      "version": "abc"
    }
  }
}
​
401
error
Unauthorized - Authentication required
​
403
error
Forbidden - Insufficient permissions
​
404
error
Not Found - Collection, document, or version not found
{
  "error": {
    "code": "VERSION_NOT_FOUND",
    "message": "Version not found",
    "details": {
      "collection": "employees",
      "id": "emp_12345",
      "version": 99
    }
  }
}
​
500
error
Internal Server Error - Failed to reconstruct version data
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to reconstruct version data",
    "details": {
      "error": "missing base version"
    }
  }
}
​
501
error
Not Implemented - Versioning is not enabled

​
Notes

  • Field-level policies apply to the returned data
  • Masked fields (e.g., email, phone) are masked according to user permissions
  • Denied fields are automatically removed from the response
  • The _version field is automatically added to the data object
  • The document reflects the state at the time the version was created

Build docs developers (and LLMs) love

Get started for freeTalk to us