Version History

Track changes to documents over time. View previous versions, compare diffs, and restore to any point.

info

Plan Limits

Free tier: 5 versions per document, no diff. Pro tier: 50 versions per document with diff support.

GET/v1/db/{ns}/{collection}/{id}/versions

List all stored versions of a document, newest first.

curl https://api.jsondb.cloud/v1/db/default/users/usr_abc123/versions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "versions": [
    {
      "version": 3,
      "operation": "patch",
      "timestamp": "2026-02-24T14:00:00.000Z",
      "apiKeyHint": "jdb_sk_live_...a1b2"
    },
    {
      "version": 2,
      "operation": "update",
      "timestamp": "2026-02-24T12:00:00.000Z",
      "apiKeyHint": "jdb_sk_live_...a1b2"
    },
    {
      "version": 1,
      "operation": "create",
      "timestamp": "2026-02-24T10:00:00.000Z",
      "apiKeyHint": "jdb_sk_live_...a1b2"
    }
  ]
}

GET/v1/db/{ns}/{collection}/{id}/versions/{version}

Retrieve the full document as it existed at a specific version.

curl https://api.jsondb.cloud/v1/db/default/users/usr_abc123/versions/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/db/{ns}/{collection}/{id}/versions/diff?from=N&to=M

Compare two versions and see what changed. Pro plan only.

warning

Pro Only

Version diffing is available only on the Pro plan.

curl "https://api.jsondb.cloud/v1/db/default/users/usr_abc123/versions/diff?from=1&to=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Diff Response

{
  "from": 1,
  "to": 3,
  "changes": [
    { "path": "name", "type": "changed", "from": "Alice", "to": "Alice Smith" },
    { "path": "role", "type": "added", "value": "admin" },
    { "path": "temp_field", "type": "removed", "value": true }
  ]
}

POST/v1/db/{ns}/{collection}/{id}/versions/{version}/restore

Restore a document to a previous version. Creates a new version with the restored content.

curl -X POST https://api.jsondb.cloud/v1/db/default/users/usr_abc123/versions/1/restore \
  -H "Authorization: Bearer YOUR_API_KEY"

Restoring creates a new version (incrementing the version number) with the content from the specified version. The X-Document-Version response header contains the new version number.

Version Metadata

Field	Description
`version`	Sequential version number (1-based)
`operation`	What created this version: create, update, patch, restore
`timestamp`	ISO 8601 timestamp
`apiKeyHint`	Last 4 chars of the API key used

Automatic Pruning

Versions are automatically pruned to stay within plan limits. When a new version exceeds the limit, the oldest version is removed. Free plan retains 5 versions per document; Pro retains 50.