Skip to main content
POST
/
{collection}
/
{id}
/
restore
/
{v}
Restore Version
curl --request POST \
  --url https://api.example.com/{collection}/{id}/restore/{v}
{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "500": {},
  "501": {},
  "_id": "<string>",
  "_version": 123,
  "updated_at": "<string>",
  "updated_by": "<string>",
  "...": "<any>"
}
Restores a document to the state it had at a specific version. This creates a new version with the restored data.

​
Endpoint

POST /{collection}/{id}/restore/{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 restore to (must be >= 1)

​
Authentication

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

​
Restore Process

When you restore a document:
  1. Pre-restore Snapshot: The current state is saved as a new version with change reason “Pre-restore snapshot”
  2. Data Retrieval: The specified version’s data is reconstructed
  3. Pre-update Hooks: Executed with action “restore”
  4. Document Update: The document is updated with the restored data
  5. Post-update Hooks: Executed with action “restore”
  6. Audit Logging: The restore action is logged with before/after states
  7. New Version: A new version is created with the restored data

​
Response

Returns the restored document with updated metadata.
​
_id
string
Document identifier (preserved from original)
​
_version
integer
New version number after restore
​
updated_at
string
ISO 8601 timestamp when the restore was performed
​
updated_by
string
User ID who performed the restore
​
...
any
All other document fields from the restored version

​
Example Request

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

​
Example Response

{
  "_id": "emp_12345",
  "_version": 5,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "department": "Marketing",
  "salary": 75000,
  "created_at": "2024-01-10T09:15:00Z",
  "updated_at": "2024-03-20T16:45:00Z",
  "updated_by": "user_admin"
}

​
Version Timeline Example

Here’s what happens during a restore operation: 
Before restore:
Version 1: {name: "John", salary: 70000}
Version 2: {name: "John", salary: 75000}
Version 3: {name: "John Doe", salary: 80000}
Version 4: {name: "John Doe", salary: 85000}  <- current

After restoring to version 2:
Version 1: {name: "John", salary: 70000}
Version 2: {name: "John", salary: 75000}
Version 3: {name: "John Doe", salary: 80000}
Version 4: {name: "John Doe", salary: 85000}
Version 5: {name: "John Doe", salary: 85000}  <- pre-restore snapshot
Version 6: {name: "John", salary: 75000}       <- restored (new current)

​
Important Behaviors

​
Document ID Preservation

The document’s _id is always preserved during restore. Only the data fields are restored.

​
Metadata Updates

The following fields are automatically updated:
  • updated_at: Set to the current timestamp
  • updated_by: Set to the user performing the restore

​
Pre-restore Snapshot

If versioning is enabled for the collection, the current document state is saved as a version before restoring. This ensures you can undo the restore if needed.

​
Hooks Integration

Restore operations trigger hooks with:
  • Action: restore
  • Before: Current document state
  • After: Restored document data
  • Metadata: Includes document_id and restore_version
Hooks can:
  • Validate the restore operation
  • Modify the restored data
  • Send notifications
  • Trigger external workflows

​
Audit Trail

The restore action is logged with:
  • Action type: restore
  • Before and after document states
  • Field-level changes computed
  • User who performed the restore
  • Success/failure status

​
Error Responses

​
400
error
Bad Request - Invalid parameters or hook validation failed
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid version number",
    "details": {
      "version": "abc"
    }
  }
}
​
401
error
Unauthorized - Authentication required
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
​
403
error
Forbidden - Missing restore permission
{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to restore this document",
    "details": {
      "action": "restore",
      "collection": "employees"
    }
  }
}
​
404
error
Not Found - 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 restore document
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to restore document",
    "details": {
      "error": "database connection lost"
    }
  }
}
​
501
error
Not Implemented - Versioning is not enabled
{
  "error": {
    "code": "VERSIONING_NOT_ENABLED",
    "message": "Versioning is not enabled"
  }
}

​
Permission Requirements

The restore action requires:
  1. Authentication: Valid user credentials
  2. Collection-level: restore action permission
  3. Document-level: RBAC conditions must pass for the specific document
Example policy configuration: 
policies:
  employees:
    admin:
      actions: [read, create, update, delete, restore]
    manager:
      actions: [read, update, restore]
      when: "user.id == resource.manager_id"
    employee:
      actions: [read]
      when: "user.id == resource._id"

​
Use Cases

  • Undo Changes: Revert accidental modifications
  • Rollback: Return to a known good state after issues
  • Data Recovery: Restore deleted or corrupted data
  • Compliance: Meet regulatory requirements for data retention
  • Testing: Restore to a baseline state for testing
  • Comparison: Restore temporarily to compare with current state

​
Best Practices

  1. Verify Before Restoring: Use the diff endpoint to review changes before restoring
  2. Check Permissions: Ensure users only restore when appropriate
  3. Monitor Restores: Log and alert on restore operations for audit purposes
  4. Document Reasons: Consider adding a change_reason when possible
  5. Test Hooks: Ensure pre/post hooks handle restore actions correctly
  6. Backup Strategy: Rely on the pre-restore snapshot as a safety net

​
Notes

  • The restored document becomes the new current version
  • Previous versions remain intact and accessible
  • Field-level policies apply to the returned document
  • The restore operation is atomic - either fully succeeds or fails
  • Post-restore hooks run asynchronously and are best-effort