Versions and branches

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, checking out, renaming, and pruning need a secret key with worlds:write. Never ship a secret key to a browser.

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.
Pruning a version deletes only that node and re-roots its children onto its parent, so the tree never fragments. You can’t prune the version HEAD currently points at. Check out another version first.

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" }'

const { versionId, version } = await fetch(
  "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_…",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ title: "before the vault rewrite", source: "save" }),
  },
).then((r) => r.json());
console.log("snapshot", versionId, "parent", version.parentVersionId);

import requests

body = requests.post(
    "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions",
    headers={
        "Authorization": "Bearer sk_live_…",
        "Content-Type": "application/json",
    },
    json={"title": "before the vault rewrite", "source": "save"},
).json()
print("snapshot", body["versionId"], "parent", body["version"]["parentVersionId"])

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_…'

const { versions } = await fetch(
  "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions",
  { headers: { Authorization: "Bearer pk_live_…" } },
).then((r) => r.json());
for (const v of versions) console.log(v.id, "←", v.parentVersionId, v.source, v.title);

import requests

versions = requests.get(
    "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions",
    headers={"Authorization": "Bearer pk_live_…"},
).json()["versions"]
for v in versions:
    print(v["id"], "←", v["parentVersionId"], v["source"], v["title"])

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" }'

const res = await fetch(
  "https://api.alakazam.gg/v1/worlds/WORLD_ID/checkout",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_…",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ versionId: "VERSION_ID" }),
  },
);
const { world, rev } = await res.json();
console.log("restored", world.name, "rev", rev);

import requests

res = requests.post(
    "https://api.alakazam.gg/v1/worlds/WORLD_ID/checkout",
    headers={
        "Authorization": "Bearer sk_live_…",
        "Content-Type": "application/json",
    },
    json={"versionId": "VERSION_ID"},
)
body = res.json()
print("restored", body["world"]["name"], "rev", body["rev"])

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_…'

const diff = await fetch(
  "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/BASE_ID/diff/TARGET_ID",
  { headers: { Authorization: "Bearer pk_live_…" } },
).then((r) => r.json());
console.log("states +", diff.states.added, "events ~", diff.events.changed);

import requests

diff = requests.get(
    "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/BASE_ID/diff/TARGET_ID",
    headers={"Authorization": "Bearer pk_live_…"},
).json()
print("states +", diff["states"]["added"], "events ~", diff["events"]["changed"])

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": [] }
}

Rename a version

PATCH /v1/worlds/{id}/versions/{versionId} changes a version’s title and nothing else: it never touches the snapshot, the parent pointer, or HEAD. title is required. Send an empty or missing one and the call comes back 400. The response echoes the versionId and the trimmed title.

curl -X PATCH 'https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/VERSION_ID' \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ "title": "vault rewrite, final" }'

const { ok, versionId, title } = await fetch(
  "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/VERSION_ID",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer sk_live_…",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ title: "vault rewrite, final" }),
  },
).then((r) => r.json());
console.log("renamed", versionId, "→", title);

import requests

body = requests.patch(
    "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/VERSION_ID",
    headers={
        "Authorization": "Bearer sk_live_…",
        "Content-Type": "application/json",
    },
    json={"title": "vault rewrite, final"},
).json()
print("renamed", body["versionId"], "→", body["title"])

Prune a version

DELETE /v1/worlds/{id}/versions/{versionId} removes a single version node. Any children it had are re-rooted onto the pruned node’s parent, so the tree stays connected. You never orphan a branch by deleting a node in the middle of it. The response returns { ok: true, deleted } with the id you removed.

You cannot prune the version HEAD currently points at, because that would leave head_version_id dangling. The API refuses with 409. Check out another version first (see Check out a version), then prune the one you no longer need.

curl -X DELETE 'https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/VERSION_ID' \
  -H 'Authorization: Bearer sk_live_…'

const res = await fetch(
  "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/VERSION_ID",
  {
    method: "DELETE",
    headers: { Authorization: "Bearer sk_live_…" },
  },
);
if (res.status === 409) {
  console.log("that version is HEAD, check out another first");
} else {
  const { deleted } = await res.json();
  console.log("pruned", deleted);
}

import requests

res = requests.delete(
    "https://api.alakazam.gg/v1/worlds/WORLD_ID/versions/VERSION_ID",
    headers={"Authorization": "Bearer sk_live_…"},
)
if res.status_code == 409:
    print("that version is HEAD, check out another first")
else:
    print("pruned", res.json()["deleted"])

Status codes

Status	Meaning
`200`	OK. Snapshot/checkout/diff/list/get/rename/prune succeeded.
`400`	A required field is missing (e.g. `versionId` on checkout, `title` on rename).
`404`	The world or a referenced version doesn’t exist, or isn’t yours.
`409`	Either the rev you asserted on a checkout is stale (reload and retry), or you tried to prune the version HEAD points at (check out another version first).

Get started

Agents & SDKs

Engine SDKs

Guides

Resources

Versions and branches

How the tree works

Snapshot a version

List the tree

Check out a version

Diff two versions

Rename a version

Prune a version

Status codes

​How the tree works

​Snapshot a version

​List the tree

​Check out a version

​Diff two versions

​Rename a version

​Prune a version

​Status codes

How the tree works

Snapshot a version

List the tree

Check out a version

Diff two versions

Rename a version

Prune a version

Status codes