Skip to main content
Every world keeps a version tree: a branching history of full graph snapshots, plus a HEAD pointer that tracks the working graph. Snapshot a version before a risky change, branch to explore an alternative, check out an older snapshot to roll back, and diff any two versions to see exactly what moved.
Reading versions needs a publishable (pk_) or secret (sk_) key with worlds:read. Snapshotting and checking out need a secret key with worlds:write.

​
How the tree works

  • A version is a full snapshot of a world’s graph at a point in time, plus metadata: id, parentVersionId, source, title, and createdAt.
  • HEAD is the version your working graph currently descends from.
  • Snapshotting onto the current HEAD advances HEAD — a linear “save”. Snapshotting off an older parent forks a branch and leaves HEAD alone.
  • source records how a version was made: save, branch, manual, ai (an agent edit), or import.

​
Snapshot a version

Capture the world’s current graph as a new version. Omit parentVersionId to snapshot onto the current HEAD. 
curl -X POST 'https://api.alakazam.gg/v1/worlds/WORLD_ID/versions' \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ "title": "before the vault rewrite", "source": "save" }'

​
List the tree

GET /v1/worlds/{id}/versions returns every node oldest-first; rebuild the tree from each node’s parentVersionId. 
curl 'https://api.alakazam.gg/v1/worlds/WORLD_ID/versions' \
  -H 'Authorization: Bearer pk_live_…'
Fetch one snapshot in full — graph and all — with GET /v1/worlds/{id}/versions/{versionId}; it returns the version metadata plus the complete snapshot world.

​
Check out a version

Checking out sets the working graph to a version’s snapshot and moves HEAD onto it, atomically. A later snapshot then branches off the checked-out version. The response carries the restored world and the new rev (also the ETag). Like every world write, checkout honors If-Match / expectedRev and returns 409 if a concurrent edit advanced the rev, so a checkout never silently clobbers an in-flight edit. 
curl -X POST 'https://api.alakazam.gg/v1/worlds/WORLD_ID/checkout' \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ "versionId": "VERSION_ID" }'

​
Diff two versions

GET /v1/worlds/{id}/versions/{a}/diff/{b} returns a pure structural diff between version a (base) and version b (target). States are keyed by their record key, events by their unique name; changed means present in both but not byte-identical. 
curl 'https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/BASE_ID/diff/TARGET_ID' \
  -H 'Authorization: Bearer pk_live_…'
The diff is shaped like this: 
{
  "a": "BASE_ID",
  "b": "TARGET_ID",
  "states": { "added": ["vault"], "removed": [], "changed": ["cellar"] },
  "events": { "added": ["Turn the brass key"], "removed": [], "changed": [] }
}

​
Status codes

StatusMeaning
200OK. Snapshot/checkout/diff/list/get succeeded.
400A required field is missing (e.g. versionId on checkout).
404The world or a referenced version doesn’t exist, or isn’t yours.
409The rev you asserted is stale — a concurrent edit moved it; reload and retry.