Version API

AeorDB provides Git-like version control through snapshots (named points in time) and forks (divergent branches of the data).

Endpoint Summary

Snapshots

POST /version/snapshot

Create a named snapshot of the current HEAD.

Request Body:

{
  "name": "v1.0",
  "metadata": {
    "description": "First stable release",
    "author": "alice"
  }
}

Response: 201 Created

{
  "name": "v1.0",
  "root_hash": "a1b2c3d4e5f6...",
  "created_at": 1775968398000,
  "metadata": {
    "description": "First stable release",
    "author": "alice"
  }
}

Example:

curl -X POST http://localhost:3000/version/snapshot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "v1.0", "metadata": {"description": "First stable release"}}'

Error Responses:

GET /version/snapshots

List all snapshots.

Response: 200 OK

[
  {
    "name": "v1.0",
    "root_hash": "a1b2c3d4e5f6...",
    "created_at": 1775968398000,
    "metadata": {"description": "First stable release"}
  },
  {
    "name": "v2.0",
    "root_hash": "f6e5d4c3b2a1...",
    "created_at": 1775969000000,
    "metadata": {}
  }
]

Example:

curl http://localhost:3000/version/snapshots \
  -H "Authorization: Bearer $TOKEN"

POST /version/restore

Restore a named snapshot, making it the current HEAD. Requires root.

Request Body:

{
  "name": "v1.0"
}

Response: 200 OK

{
  "restored": true,
  "name": "v1.0"
}

Example:

curl -X POST http://localhost:3000/version/restore \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "v1.0"}'

Error Responses:

DELETE /version/snapshot/

Delete a named snapshot. Requires root.

Response: 200 OK

{
  "deleted": true,
  "name": "v1.0"
}

Example:

curl -X DELETE http://localhost:3000/version/snapshot/v1.0 \
  -H "Authorization: Bearer $TOKEN"

Error Responses:

Forks

Forks create a divergent branch of the data, optionally based on a named snapshot.

POST /version/fork

Create a new fork.

Request Body:

{
  "name": "experiment",
  "base": "v1.0"
}

Response: 201 Created

{
  "name": "experiment",
  "root_hash": "a1b2c3d4e5f6...",
  "created_at": 1775968398000
}

Example:

curl -X POST http://localhost:3000/version/fork \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "experiment", "base": "v1.0"}'

Error Responses:

GET /version/forks

List all active forks.

Response: 200 OK

[
  {
    "name": "experiment",
    "root_hash": "a1b2c3d4e5f6...",
    "created_at": 1775968398000
  }
]

Example:

curl http://localhost:3000/version/forks \
  -H "Authorization: Bearer $TOKEN"

POST /version/fork/{name}/promote

Promote a fork’s state to HEAD, making it the active version. Requires root.

Response: 200 OK

{
  "promoted": true,
  "name": "experiment"
}

Example:

curl -X POST http://localhost:3000/version/fork/experiment/promote \
  -H "Authorization: Bearer $TOKEN"

Error Responses:

DELETE /version/fork/

Abandon a fork (soft delete). Requires root.

Response: 200 OK

{
  "abandoned": true,
  "name": "experiment"
}

Example:

curl -X DELETE http://localhost:3000/version/fork/experiment \
  -H "Authorization: Bearer $TOKEN"

Error Responses:

File-Level Version Access

Read, restore, and view history for individual files at specific historical versions.

Reading Files at a Version

Use query parameters on the standard file read endpoint:

# Read a file as it was at a named snapshot
curl "http://localhost:3000/engine/assets/logo.psd?snapshot=v1.0" \
  -H "Authorization: Bearer $TOKEN"

# Read a file at a specific version hash
curl "http://localhost:3000/engine/assets/logo.psd?version=a1b2c3d4..." \
  -H "Authorization: Bearer $TOKEN"

Returns the file content exactly as it was at that version, with the same headers as a normal file read. If both snapshot and version are provided, snapshot takes precedence.

Error Responses:

GET /version/file-history/

View the change history of a single file across all snapshots. Returns entries ordered newest-first, each with a change_type indicating what happened to the file at that snapshot.

Response: 200 OK

{
  "path": "assets/logo.psd",
  "history": [
    {
      "snapshot": "v2.0",
      "timestamp": 1775969000000,
      "change_type": "modified",
      "size": 512000,
      "content_type": "image/vnd.adobe.photoshop",
      "content_hash": "f6e5d4c3..."
    },
    {
      "snapshot": "v1.0",
      "timestamp": 1775968398000,
      "change_type": "added",
      "size": 256000,
      "content_type": "image/vnd.adobe.photoshop",
      "content_hash": "a1b2c3d4..."
    }
  ]
}

Change types:

If the file has never existed in any snapshot, returns 200 with an empty history array.

Example:

curl http://localhost:3000/version/file-history/assets/logo.psd \
  -H "Authorization: Bearer $TOKEN"

POST /version/file-restore/

Restore a single file from a historical version to the current HEAD. Requires root.

Before restoring, an automatic safety snapshot is created (named pre-restore-{timestamp}) to preserve the current state. If the safety snapshot cannot be created, the restore is rejected.

Request Body:

{
  "snapshot": "v1.0"
}

Or using a version hash:

{
  "version": "a1b2c3d4..."
}

If both are provided, snapshot takes precedence.

Response: 200 OK

{
  "restored": true,
  "path": "assets/logo.psd",
  "from_snapshot": "v1.0",
  "auto_snapshot": "pre-restore-2026-04-14T05-01-01Z",
  "size": 256000
}

The auto_snapshot field contains the name of the safety snapshot created before the restore. You can use this snapshot to recover the pre-restore state if needed.

Example:

curl -X POST http://localhost:3000/version/file-restore/assets/logo.psd \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"snapshot": "v1.0"}'

Error Responses: