Skip to main content
GET
/
{collection}
/
{id}
/
versions
List Versions
curl --request GET \
  --url https://api.example.com/{collection}/{id}/versions
{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "501": {},
  "version": 123,
  "updated_by": "<string>",
  "updated_at": "<string>",
  "change_reason": "<string>"
}
Retrieves a list of all versions for a specific document, including metadata about when each version was created and by whom.

​
Endpoint

GET /{collection}/{id}/versions

​
Path Parameters

​
collection
string
required
The name of the collection containing the document
​
id
string
required
The unique identifier of the document

​
Authentication

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

​
Response

Returns an array of version metadata objects, sorted in reverse chronological order (newest first).
​
version
integer
The version number (starting from 1)
​
updated_by
string
User ID of the person who created this version
​
updated_at
string
ISO 8601 timestamp when this version was created
​
change_reason
string
Optional reason for the change (if provided)

​
Example Request

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

​
Example Response

[
  {
    "version": 3,
    "updated_by": "user_789",
    "updated_at": "2024-03-15T10:30:00Z",
    "change_reason": "Updated salary information"
  },
  {
    "version": 2,
    "updated_by": "user_456",
    "updated_at": "2024-02-20T14:22:00Z",
    "change_reason": "Changed department"
  },
  {
    "version": 1,
    "updated_by": "user_123",
    "updated_at": "2024-01-10T09:15:00Z"
  }
]

​
Version Storage Format

Versions are stored in the _pm_versions collection with the following structure:
  • Full Mode: Complete document snapshot is stored in the data field
  • Diff Mode: Only changes are stored in the changes array (version 1 is always full mode)
Each version record includes:
  • Collection and document identifiers
  • Version number
  • Storage mode (full or diff)
  • User who made the change
  • Timestamp of the change
  • Optional change reason

​
Error Responses

​
400
error
Bad Request - Missing or invalid collection name or document ID
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Document ID is required"
  }
}
​
401
error
Unauthorized - Authentication required
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
​
403
error
Forbidden - Insufficient permissions to read the document
{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this document",
    "details": {
      "action": "read",
      "collection": "employees"
    }
  }
}
​
404
error
Not Found - Collection or document not found
{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "Document not found",
    "details": {
      "collection": "employees",
      "id": "emp_12345"
    }
  }
}
​
501
error
Not Implemented - Versioning is not enabled
{
  "error": {
    "code": "VERSIONING_NOT_ENABLED",
    "message": "Versioning is not enabled"
  }
}

​
Notes

  • If no versions exist for the document, an empty array [] is returned
  • Versions are returned in descending order by version number (newest first)
  • Only version metadata is returned, not the full document data
  • Field-level permissions apply - denied fields are not included in the response

Build docs developers (and LLMs) love

Get started for freeTalk to us