Skip to main content
POST
/
v1
/
worlds
/
{id}
/
edit
Edit the graph from natural language
curl --request POST \
  --url https://api.alakazam.gg/v1/worlds/{id}/edit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "instruction": "<string>",
  "message": "<string>",
  "verifiedObjects": [
    {}
  ],
  "expectedRev": "<string>"
}
'
{
  "world": {
    "id": "<string>",
    "name": "<string>",
    "entrance": {
      "image": {
        "src": "<string>",
        "label": "<string>"
      },
      "state": "<string>"
    },
    "scene": {
      "states": {},
      "events": [
        {}
      ]
    },
    "description": "<string>",
    "cover": "<string>"
  },
  "diagnostics": [
    {
      "lint": "<string>",
      "path": "<string>",
      "message": "<string>",
      "loc": {
        "field": "<string>",
        "template": "<string>",
        "slot": "<string>",
        "fill": "<string>"
      }
    }
  ],
  "reply": "<string>"
}

Authorizations

​
Authorization
string
header
required

An app API key, e.g. Authorization: Bearer sk_live_…. Secret (sk_) for writes/sessions; publishable (pk_) for read/embed.

Headers

​
If-Match
string

The rev you last read. Mismatch returns 409.

​
Idempotency-Key
string

A retried edit with the same key returns the original result without a second LLM spend.

Path Parameters

​
id
string<uuid>
required

Body

application/json

A natural-language edit instruction for the server-side kernel agent. Either instruction or message is required.

​
instruction
string

What to change, in prose — e.g. "add a locked vault behind the cellar and wire a key to open it".

​
message
string

Alias for instruction (accepted for convenience).

​
verifiedObjects
object[]

Optional grounding hints (named objects the agent may reference).

​
expectedRev
string

Optional optimistic-concurrency token; alternative to the If-Match header.

Response

Edit applied (or a clarifying question in reply with no change). The new rev is the ETag.

The RESULT-ONLY response from a kernel-agent edit. It carries the validated world, advisory diagnostics, and the agent's natural-language reply, and NOTHING else — the agent's system prompt, op grammar, lexicon, model id, and raw op trace are never exposed. When the agent needs clarification it returns its question in reply and leaves the world unchanged.

​
world
object
required

A playable world. The full contract is published as JSON Schema at https://alakazam.gg/schema/smworld-1.0.json (see schema/COMPATIBILITY.md). Additional optional properties are allowed (forward-compatible).

​
diagnostics
object[]
required

The full validateWorld set (advisory warning/info findings) for the persisted world.

​
reply
string
required

The agent's natural-language summary of what it did, or a clarifying question when no change was made.