# Alakazam

> The programmable worlds API — create playable AI worlds and program them into your products.

## Docs

- [Editing with natural language](https://docs.alakazam.gg/agent-editing.md): Describe a change in prose and the kernel agent authors it — validated fail-closed, results only, never the authoring brain.
- [Create an app](https://docs.alakazam.gg/api-reference/apps-&-keys/create-an-app.md)
- [List key metadata](https://docs.alakazam.gg/api-reference/apps-&-keys/list-key-metadata.md)
- [List your apps](https://docs.alakazam.gg/api-reference/apps-&-keys/list-your-apps.md)
- [Mint an API key](https://docs.alakazam.gg/api-reference/apps-&-keys/mint-an-api-key.md): Returns the plaintext key ONCE. Store it immediately.
- [Revoke a key](https://docs.alakazam.gg/api-reference/apps-&-keys/revoke-a-key.md)
- [Add a state (node)](https://docs.alakazam.gg/api-reference/graph-editing/add-a-state-node.md): Create a node. Omit `id` to have one auto-assigned. Validated fail-closed before persist.
- [Add an event (edge)](https://docs.alakazam.gg/api-reference/graph-editing/add-an-event-edge.md): Create an edge. A `transition` needs `to`; an `override` must NOT carry `to`. Validated fail-closed.
- [Apply a batch of graph ops](https://docs.alakazam.gg/api-reference/graph-editing/apply-a-batch-of-graph-ops.md): Apply an ordered batch of `GraphOp`s atomically: unapplicable ops are collected in `applyErrors` (the editor's behavior), then the resulting world is validated ONCE through the kernel gate. A 422 means the batch was rejected as a whole — nothing persists. This single endpoint backs nearly all editor…
- [Delete a state](https://docs.alakazam.gg/api-reference/graph-editing/delete-a-state.md): Delete a node. Rejected (400) if it is the entrance or referenced by any event/cutscene — detach those refs first.
- [Delete an event](https://docs.alakazam.gg/api-reference/graph-editing/delete-an-event.md)
- [Edit the graph from natural language](https://docs.alakazam.gg/api-reference/graph-editing/edit-the-graph-from-natural-language.md): Run the kernel agent server-side: describe the change in prose and the agent authors it, then the SAME fail-closed kernel gate every deterministic write passes must bless the result before it persists. This is real LLM spend — one unit is reserved against your daily `edit` quota BEFORE the agent run…
- [Get one event](https://docs.alakazam.gg/api-reference/graph-editing/get-one-event.md): Edges are addressed by their unique `name`, never by index.
- [Get one state](https://docs.alakazam.gg/api-reference/graph-editing/get-one-state.md)
- [Lint (advisory)](https://docs.alakazam.gg/api-reference/graph-editing/lint-advisory.md): Run the doctrine lints advisorily — this NEVER returns 4xx on doctrine hits. Lints an inline `world`/`data` override if provided, else the stored world. `ok` is true when there are zero error-severity findings.
- [List events (edges)](https://docs.alakazam.gg/api-reference/graph-editing/list-events-edges.md)
- [List states (nodes)](https://docs.alakazam.gg/api-reference/graph-editing/list-states-nodes.md)
- [Read the whole graph](https://docs.alakazam.gg/api-reference/graph-editing/read-the-whole-graph.md): Returns the world's states (nodes) and events (edges). The current `rev` is returned both in the body and as the `ETag` header — pass it as `If-Match` on your next write.
- [Set the entrance](https://docs.alakazam.gg/api-reference/graph-editing/set-the-entrance.md): Point the world's entry at a state (+ optional seed image). The state must exist; validated fail-closed.
- [Update a state](https://docs.alakazam.gg/api-reference/graph-editing/update-a-state.md): Patch node fields (base/camera/movement/ambient/variants/ending). The body is the partial state, or `{ patch: {...} }`. Validated fail-closed.
- [Update an event](https://docs.alakazam.gg/api-reference/graph-editing/update-an-event.md): Patch any field of an edge addressed by `name` (kind/from/to/hotkey/requires/grants/timing/…). The body is the partial event, or `{ patch: {...} }`. Validated fail-closed.
- [Validate against the kernel gate](https://docs.alakazam.gg/api-reference/graph-editing/validate-against-the-kernel-gate.md): Run the strict kernel grammar + doctrine suite with no persist. Validates an inline `world` (or `data`) override if provided, else the stored world. Returns 200 with the resolved world when clean, or 422 with diagnostics.
- [Bind the runtime sessionId to the session (attribution)](https://docs.alakazam.gg/api-reference/sessions/bind-the-runtime-sessionid-to-the-session-attribution.md): The embed posts the runtime sessionId (known only after connect) so the platform can attribute the live session to your app for usage + reactive kill. app_id is taken from the verified session token, never the client.
- [Exchange a session token for a runtime connect token](https://docs.alakazam.gg/api-reference/sessions/exchange-a-session-token-for-a-runtime-connect-token.md): Called from the EMBED'S BROWSER with the session token (the token IS the auth — no API key). Admits the session under your per-tenant + the global concurrency caps and your daily session-minutes budget, then returns a short-lived runtime connect token plus the world to play. All cost controls are en…
- [Mint a runtime session token](https://docs.alakazam.gg/api-reference/sessions/mint-a-runtime-session-token.md): Call from YOUR backend with a secret key. Returns a short-lived token your end-user's browser passes to @alakazamworld/embed. Reserves one session against your daily quota.
- [Settle a live session on close](https://docs.alakazam.gg/api-reference/sessions/settle-a-live-session-on-close.md): The embed posts this when the player unmounts. Frees a concurrency slot, refunds the unused session-minutes reservation, and records the actual GPU-seconds to usage + billing.
- [Get today's usage](https://docs.alakazam.gg/api-reference/usage/get-todays-usage.md)
- [Check out a version](https://docs.alakazam.gg/api-reference/versions/check-out-a-version.md): Set the working graph (`world`) to a version's snapshot AND move HEAD onto it, atomically. A later save then branches off the checked-out version. Returns the restored world and the new `rev` (also the `ETag`).
- [Diff two versions](https://docs.alakazam.gg/api-reference/versions/diff-two-versions.md): A pure structural diff between version `a` (base) and version `b` (target): states and events added, removed, and changed.
- [Get one version snapshot](https://docs.alakazam.gg/api-reference/versions/get-one-version-snapshot.md)
- [List the version tree](https://docs.alakazam.gg/api-reference/versions/list-the-version-tree.md): Returns the full version tree (oldest-first); rebuild the tree from each node's `parentVersionId`.
- [Snapshot a version](https://docs.alakazam.gg/api-reference/versions/snapshot-a-version.md): Snapshot the world's CURRENT graph as a new version. The parent is `parentVersionId` (or the current HEAD if omitted); a save onto the current HEAD advances HEAD, while a snapshot off an older parent forks a branch without moving HEAD.
- [Delete a webhook endpoint](https://docs.alakazam.gg/api-reference/webhooks/delete-a-webhook-endpoint.md)
- [Delete a webhook endpoint (POST alias)](https://docs.alakazam.gg/api-reference/webhooks/delete-a-webhook-endpoint-post-alias.md): Same as DELETE, for environments that cannot send a DELETE verb.
- [List webhook endpoints](https://docs.alakazam.gg/api-reference/webhooks/list-webhook-endpoints.md): Returns endpoint metadata only — the signing secret is never returned after creation.
- [Register a webhook endpoint](https://docs.alakazam.gg/api-reference/webhooks/register-a-webhook-endpoint.md): Registers an HTTPS endpoint and returns its `whsec_` signing secret ONCE. Omit `events` to subscribe to all currently-delivered events (world.generation.succeeded and world.generation.failed).
- [Create a world](https://docs.alakazam.gg/api-reference/worlds/create-a-world.md): Generate a playable SMWorld from a premise and/or seed frame. Reserves one generation against your daily quota before spending GPU.
- [Delete a world](https://docs.alakazam.gg/api-reference/worlds/delete-a-world.md)
- [Fork a world](https://docs.alakazam.gg/api-reference/worlds/fork-a-world.md): Clone a source world (your own, or a public one) into a new private world owned by your app.
- [Get a world](https://docs.alakazam.gg/api-reference/worlds/get-a-world.md)
- [Get generation job status](https://docs.alakazam.gg/api-reference/worlds/get-generation-job-status.md): Poll a durable async generation job created with async:true.
- [List your worlds](https://docs.alakazam.gg/api-reference/worlds/list-your-worlds.md)
- [Update world metadata](https://docs.alakazam.gg/api-reference/worlds/update-world-metadata.md)
- [Concepts](https://docs.alakazam.gg/concepts.md): Programmable worlds, sessions, apps, and how they fit together.
- [Embedding](https://docs.alakazam.gg/embedding.md): Drop a world into your site with the @alakazamworld/embed SDK.
- [Errors and troubleshooting](https://docs.alakazam.gg/errors.md): Read error responses from the programmable worlds API and fix common causes.
- [Frequently asked questions](https://docs.alakazam.gg/faq.md): Common questions about the programmable worlds API.
- [Editing the graph](https://docs.alakazam.gg/graph-editing.md): Program a world's states, events, and entrance over HTTP — every write validated fail-closed against the kernel.
- [Introduction](https://docs.alakazam.gg/index.md): The programmable worlds API — create playable AI worlds and program them into your products.
- [Pricing](https://docs.alakazam.gg/pricing.md): How usage and quota work for the programmable worlds API.
- [Quickstart](https://docs.alakazam.gg/quickstart.md): Get an API key, create your first world, and embed it.
- [Rate limits](https://docs.alakazam.gg/rate-limits.md): Throughput limits on the programmable worlds API.
- [Versions and branches](https://docs.alakazam.gg/versions.md): Snapshot, branch, check out, and diff a world's graph — a git-style version tree of full snapshots.
- [Webhooks](https://docs.alakazam.gg/webhooks.md): Get server-side notifications when your programmable worlds generate and play.
- [World generation examples](https://docs.alakazam.gg/world-generation-examples.md): Create a world from a premise, an image URL, or an uploaded frame.

## OpenAPI Specs

- [alakazam-v1](https://docs.alakazam.gg/alakazam-v1.yaml)