Graph editing

Edit the graph from natural language

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 runs, and refunded on a validation reject, agent error, or concurrency conflict. RESULT-ONLY: the response is exactly world, diagnostics, and reply. The agent’s system prompt, op grammar, lexicon, model id, and raw op trace are never exposed. If the agent needs clarification it returns the question in reply and leaves the world unchanged. Pass an Idempotency-Key so a retry doesn’t double-charge.

POST

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

import requests

url = "https://api.alakazam.gg/v1/worlds/{id}/edit"

payload = {
    "instruction": "<string>",
    "message": "<string>",
    "verifiedObjects": [{}],
    "expectedRev": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    instruction: '<string>',
    message: '<string>',
    verifiedObjects: [{}],
    expectedRev: '<string>'
  })
};

fetch('https://api.alakazam.gg/v1/worlds/{id}/edit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alakazam.gg/v1/worlds/{id}/edit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'instruction' => '<string>',
    'message' => '<string>',
    'verifiedObjects' => [
        [
                
        ]
    ],
    'expectedRev' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.alakazam.gg/v1/worlds/{id}/edit"

	payload := strings.NewReader("{\n  \"instruction\": \"<string>\",\n  \"message\": \"<string>\",\n  \"verifiedObjects\": [\n    {}\n  ],\n  \"expectedRev\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alakazam.gg/v1/worlds/{id}/edit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"instruction\": \"<string>\",\n  \"message\": \"<string>\",\n  \"verifiedObjects\": [\n    {}\n  ],\n  \"expectedRev\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.alakazam.gg/v1/worlds/{id}/edit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"instruction\": \"<string>\",\n  \"message\": \"<string>\",\n  \"verifiedObjects\": [\n    {}\n  ],\n  \"expectedRev\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "world": {
    "id": "<string>",
    "name": "<string>",
    "entrance": {
      "image": {
        "src": "<string>",
        "label": "<string>"
      },
      "state": "<string>"
    },
    "scene": {
      "states": {},
      "events": [
        {}
      ]
    },
    "description": "<string>",
    "cover": "<string>",
    "subject": "<string>",
    "subjectRef": {
      "imageUrl": "<string>",
      "descriptor": "<string>"
    }
  },
  "diagnostics": [
    {
      "lint": "<string>",
      "severity": "error",
      "path": "<string>",
      "message": "<string>",
      "loc": {
        "field": "<string>",
        "template": "<string>",
        "slot": "<string>",
        "fill": "<string>"
      }
    }
  ],
  "reply": "<string>",
  "mock": true
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "diagnostics": [
    {
      "lint": "<string>",
      "severity": "error",
      "path": "<string>",
      "message": "<string>",
      "loc": {
        "field": "<string>",
        "template": "<string>",
        "slot": "<string>",
        "fill": "<string>"
      }
    }
  ],
  "schemaVersion": "1.0"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

Authorizations

Authorization

string

header

required

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

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

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. For example, "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 none of the agent's internals: the 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. (A TEST-mode response additionally carries a mock: true marker.)

world

object

required

A playable world's compiled graph, id, name, entrance, and the scene (states + events). This is the shape returned inside the world field of a World resource (see World) and by the graph-editing routes. Additional optional properties are allowed (forward-compatible); the schemaVersion on responses pins the contract version.

Show child attributes

diagnostics

object[]

required

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

Show child attributes

string

required

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

mock

boolean

Present and true only for TEST-mode keys. See Testing.

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

import requests

url = "https://api.alakazam.gg/v1/worlds/{id}/edit"

payload = {
    "instruction": "<string>",
    "message": "<string>",
    "verifiedObjects": [{}],
    "expectedRev": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    instruction: '<string>',
    message: '<string>',
    verifiedObjects: [{}],
    expectedRev: '<string>'
  })
};

fetch('https://api.alakazam.gg/v1/worlds/{id}/edit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alakazam.gg/v1/worlds/{id}/edit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'instruction' => '<string>',
    'message' => '<string>',
    'verifiedObjects' => [
        [
                
        ]
    ],
    'expectedRev' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.alakazam.gg/v1/worlds/{id}/edit"

	payload := strings.NewReader("{\n  \"instruction\": \"<string>\",\n  \"message\": \"<string>\",\n  \"verifiedObjects\": [\n    {}\n  ],\n  \"expectedRev\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alakazam.gg/v1/worlds/{id}/edit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"instruction\": \"<string>\",\n  \"message\": \"<string>\",\n  \"verifiedObjects\": [\n    {}\n  ],\n  \"expectedRev\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.alakazam.gg/v1/worlds/{id}/edit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"instruction\": \"<string>\",\n  \"message\": \"<string>\",\n  \"verifiedObjects\": [\n    {}\n  ],\n  \"expectedRev\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "world": {
    "id": "<string>",
    "name": "<string>",
    "entrance": {
      "image": {
        "src": "<string>",
        "label": "<string>"
      },
      "state": "<string>"
    },
    "scene": {
      "states": {},
      "events": [
        {}
      ]
    },
    "description": "<string>",
    "cover": "<string>",
    "subject": "<string>",
    "subjectRef": {
      "imageUrl": "<string>",
      "descriptor": "<string>"
    }
  },
  "diagnostics": [
    {
      "lint": "<string>",
      "severity": "error",
      "path": "<string>",
      "message": "<string>",
      "loc": {
        "field": "<string>",
        "template": "<string>",
        "slot": "<string>",
        "fill": "<string>"
      }
    }
  ],
  "reply": "<string>",
  "mock": true
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "diagnostics": [
    {
      "lint": "<string>",
      "severity": "error",
      "path": "<string>",
      "message": "<string>",
      "loc": {
        "field": "<string>",
        "template": "<string>",
        "slot": "<string>",
        "fill": "<string>"
      }
    }
  ],
  "schemaVersion": "1.0"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

Play API

Forge API

Train API

Edit the graph from natural language

Authorizations

Headers

Path Parameters

Body

Response