Skip to main content
A world is a programmable graph, and you don’t always want to hand-script every node and edge. POST /v1/worlds/{id}/edit lets you describe a change in plain language — “add a locked vault behind the cellar and wire a key that opens it” — and the server-side kernel agent authors it for you, then hands the result through the exact same validation gate every deterministic write passes. This is the natural-language tier of the Graph-Editing API. Both tiers — the deterministic CRUD/ops surface and this one — funnel through one fail-closed kernel gate, so a world edited either way behaves identically in the editor and at runtime.
/edit needs a secret (sk_) key with worlds:write. It is real LLM spend: each call reserves one unit against your daily edit quota. Never ship a secret key to a browser.

​
The authoring brain stays server-side

This is the load-bearing guarantee of the endpoint. The kernel agent — its system prompt, its op grammar, its lexicon, the model that drives it, and the raw op trace it produces — never leaves the server. The response is results only: exactly world, diagnostics, and reply, and nothing else. 
{
  "world": { "id": "…", "name": "…", "entrance": { … }, "scene": { … } },
  "diagnostics": [],
  "reply": "Added a 'vault' state behind the cellar and a 'Turn the brass key' transition gated on the key item."
}
  • world — the new, kernel-validated world. Identical in shape to what GET /v1/worlds/{id} returns.
  • diagnostics — advisory (warning/info) findings on the persisted world, the same set the validate/lint endpoints return.
  • reply — the agent’s natural-language summary of what it did.
The new revision comes back as the ETag header — hold onto it for your next write (see optimistic concurrency).

​
The validation gate applies, unconditionally

The agent can propose anything; it cannot persist anything invalid. Whatever graph it authors is run through the kernel grammar and the full doctrine lint suite fail-closed before it is saved. If the result would be invalid, the call returns 422 with the blocking diagnostics and nothing is persisted — and your quota reservation is refunded. Even a hostile instruction cannot push an off-doctrine world past the gate.

​
A basic edit

curl -X POST 'https://api.alakazam.gg/v1/worlds/WORLD_ID/edit' \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: edit-vault-001' \
  -d '{
    "instruction": "Add a locked vault behind the cellar and wire a brass key that opens the door."
  }'
Either instruction or message is accepted for the prose. Send a missing or empty instruction and you get a 400 before any spend.

​
Clarifying questions

The agent has an ask-gate: when an instruction is ambiguous, it returns its question in reply and leaves the world unchanged (the response is still 200, and world is the world you already had). Treat a reply that ends in a question as a prompt for more detail rather than a confirmation, then call again with a sharper instruction. 
{
  "world": { … },
  "diagnostics": [],
  "reply": "Which existing room should the vault connect to — the cellar or the hallway?"
}

​
Idempotency and concurrency

Because /edit is metered LLM spend, retries matter.
  • Idempotency-Key — a retried /edit with the same key returns the original result without a second LLM call (and without a second charge). Always send one for safe retries.
  • If-Match (or an expectedRev body field) — guards against clobbering a concurrent edit. If the rev you assert is stale, the call returns 409, the reservation is refunded, and you should reload and retry.

​
Metering

/edit reserves one unit of the edit kind against your daily quota before the agent runs (fail-closed). The reservation is refunded on a validation reject (422), an agent failure (502), or a concurrency conflict (409), and recorded only on a successful persist. Usage shows up under the edit key in GET /v1/usage.

​
Status codes

StatusMeaning
200Edit applied (or a clarifying question in reply with no change). The new rev is the ETag.
400Missing instruction. No spend.
402Daily edit quota exceeded.
404The world doesn’t exist, or isn’t yours.
409The rev you asserted is stale — reload and retry. Reservation refunded.
422The agent’s world failed the kernel gate. The body carries the blocking diagnostics; nothing persisted; reservation refunded.
502The authoring agent failed. Reservation refunded.
503The authoring or quota backend is unavailable (fail-closed).