Document Versions
API reference for managing document version history
5 mins
Document Versions API
Mavibase automatically maintains a version history for every document. Each update creates a new version, allowing you to view history and restore previous states.
Authentication
All version endpoints require an API key with appropriate scopes:
| Scope | Required For |
|---|---|
databases:read | GET requests |
databases:write | POST (restore) requests |
How Versioning Works
- When a document is created, it starts at version 1
- Each update (PUT or PATCH) increments the version number
- Previous versions are preserved and can be accessed
- You can restore any previous version
- Restoring creates a new version (not a rollback)
List Document Versions
Retrieves all versions of a document.
Endpoint
GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId/versions
Path Parameters
| Parameter | Description |
|---|---|
databaseId | Database identifier |
collectionId | Collection identifier |
documentId | Document identifier |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 25 | Maximum versions to return |
offset | integer | 0 | Number of versions to skip |
Example Request
bash
curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456/versions" \
-H "X-API-Key: your_api_key"JavaScript Example
javascript
const response = await fetch(
'<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456/versions',
{
headers: {
'X-API-Key': 'your_api_key',
},
}
);
const { versions, total } = await response.json();Response
json
{
"success": true,
"versions": [
{
"version": 3,
"data": {
"name": "John Doe",
"email": "john.doe@example.com",
"age": 30
},
"createdAt": "2024-01-15T15:00:00.000Z",
"createdBy": "usr_abc123"
},
{
"version": 2,
"data": {
"name": "John Doe",
"email": "john@example.com",
"age": 29
},
"createdAt": "2024-01-15T12:00:00.000Z",
"createdBy": "usr_abc123"
},
{
"version": 1,
"data": {
"name": "John Doe",
"email": "john@example.com",
"age": 28
},
"createdAt": "2024-01-15T10:00:00.000Z",
"createdBy": "usr_abc123"
}
],
"total": 3,
"currentVersion": 3
}Get Specific Version
Retrieves a specific version of a document.
Endpoint
GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId/versions/:version
Path Parameters
| Parameter | Description |
|---|---|
databaseId | Database identifier |
collectionId | Collection identifier |
documentId | Document identifier |
version | Version number to retrieve |
Example Request
bash
curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456/versions/1" \
-H "X-API-Key: your_api_key"Response
json
{
"success": true,
"version": {
"version": 1,
"data": {
"name": "John Doe",
"email": "john@example.com",
"age": 28
},
"createdAt": "2024-01-15T10:00:00.000Z",
"createdBy": "usr_abc123"
}
}Compare Versions
Compares two versions of a document to see the differences.
Endpoint
GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId/versions/compare/:version1/:version2
Path Parameters
| Parameter | Description |
|---|---|
databaseId | Database identifier |
collectionId | Collection identifier |
documentId | Document identifier |
version1 | First version number |
version2 | Second version number |
Example Request
bash
curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456/versions/compare/1/3" \
-H "X-API-Key: your_api_key"JavaScript Example
javascript
const response = await fetch(
'<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456/versions/compare/1/3',
{
headers: {
'X-API-Key': 'your_api_key',
},
}
);
const { diff } = await response.json();Response
json
{
"success": true,
"diff": {
"version1": 1,
"version2": 3,
"changes": [
{
"field": "email",
"oldValue": "john@example.com",
"newValue": "john.doe@example.com",
"type": "modified"
},
{
"field": "age",
"oldValue": 28,
"newValue": 30,
"type": "modified"
}
],
"added": [],
"removed": [],
"modified": ["email", "age"]
}
}Restore Version
Restores a document to a previous version. This creates a new version with the old data.
Endpoint
POST <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId/versions/:version/restore
Path Parameters
| Parameter | Description |
|---|---|
databaseId | Database identifier |
collectionId | Collection identifier |
documentId | Document identifier |
version | Version number to restore |
Example Request
bash
curl -X POST "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456/versions/1/restore" \
-H "X-API-Key: your_api_key"JavaScript Example
javascript
const response = await fetch(
'<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456/versions/1/restore',
{
method: 'POST',
headers: {
'X-API-Key': 'your_api_key',
},
}
);
const { document } = await response.json();
console.log(`Restored to version ${document.version}`);Response
json
{
"success": true,
"document": {
"id": "doc_def456",
"data": {
"name": "John Doe",
"email": "john@example.com",
"age": 28
},
"version": 4,
"restoredFrom": 1,
"createdAt": "2024-01-15T10:00:00.000Z",
"updatedAt": "2024-01-15T16:00:00.000Z"
},
"message": "Document restored from version 1"
}Note: Restoring creates a new version (4 in this example) with the data from version 1. The version history is preserved.
Version History Use Cases
Audit Trail
Track who made changes and when:
javascript
async function getDocumentHistory(databaseId, collectionId, documentId) {
const response = await fetch(
`<API_ENDPOINT>/api/v1/db/databases/${databaseId}/collections/${collectionId}/documents/${documentId}/versions`,
{
headers: { 'X-API-Key': 'your_api_key' },
}
);
const { versions } = await response.json();
return versions.map((v) => ({
version: v.version,
changedAt: v.createdAt,
changedBy: v.createdBy,
}));
}Undo Last Change
Restore to the previous version:
javascript
async function undoLastChange(databaseId, collectionId, documentId) {
// Get current version
const docResponse = await fetch(
`<API_ENDPOINT>/api/v1/db/databases/${databaseId}/collections/${collectionId}/documents/${documentId}`,
{
headers: { 'X-API-Key': 'your_api_key' },
}
);
const { document } = await docResponse.json();
const previousVersion = document.version - 1;
if (previousVersion < 1) {
throw new Error('No previous version available');
}
// Restore previous version
const restoreResponse = await fetch(
`<API_ENDPOINT>/api/v1/db/databases/${databaseId}/collections/${collectionId}/documents/${documentId}/versions/${previousVersion}/restore`,
{
method: 'POST',
headers: { 'X-API-Key': 'your_api_key' },
}
);
return restoreResponse.json();
}Show Change Diff
Display what changed between versions:
javascript
async function showChanges(databaseId, collectionId, documentId, v1, v2) {
const response = await fetch(
`<API_ENDPOINT>/api/v1/db/databases/${databaseId}/collections/${collectionId}/documents/${documentId}/versions/compare/${v1}/${v2}`,
{
headers: { 'X-API-Key': 'your_api_key' },
}
);
const { diff } = await response.json();
console.log('Modified fields:', diff.modified);
console.log('Added fields:', diff.added);
console.log('Removed fields:', diff.removed);
diff.changes.forEach((change) => {
console.log(`${change.field}: ${change.oldValue} → ${change.newValue}`);
});
}