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: 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. Your
quota reservation is refunded. Even a hostile instruction cannot push an
off-doctrine world past the gate.
A basic edit
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.
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