Graph editing

Convert a world into a shoot-for-score arcade

One-call Arcadeify: runs the SAME canned kernel-agent ask the Studio’s one-click Arcadeify button uses, turning the world into a shoot-for-score arcade derived from the world’s own fiction (a progression, hostiles, a win condition). Same server-side kernel agent as /edit, same fail-closed gate: the agent authors the change and the result persists ONLY after passing the kernel grammar + doctrine suite. This is real LLM spend — reserved against your daily edit quota BEFORE the agent runs — a validation reject or agent error refunds it in full, while a committed edit, a no-change run, or a concurrency conflict meters the agent rounds actually burned and refunds only the unused slice. On success a version titled arcadeify (source ai) is snapshotted onto HEAD, so the conversion is one POST …/checkout away from rollback. Guard: a world that already has a progression is refused 409 unless you pass force:true (which rebuilds it). Pass an Idempotency-Key so a retry doesn’t double-charge.

POST

worlds

{id}

arcadeify

Convert a world into a shoot-for-score arcade

curl --request POST \
  --url https://api.alakazam.gg/v1/worlds/{id}/arcadeify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "force": false,
  "expectedRev": "<string>"
}
'

import requests

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

payload = {
    "force": False,
    "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({force: false, expectedRev: '<string>'})
};

fetch('https://api.alakazam.gg/v1/worlds/{id}/arcadeify', 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}/arcadeify",
  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([
    'force' => false,
    '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}/arcadeify"

	payload := strings.NewReader("{\n  \"force\": false,\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}/arcadeify")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force\": false,\n  \"expectedRev\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"force\": false,\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>",
      "path": "<string>",
      "message": "<string>",
      "loc": {
        "field": "<string>",
        "template": "<string>",
        "slot": "<string>",
        "fill": "<string>"
      }
    }
  ],
  "reply": "<string>",
  "mock": true,
  "versionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "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>",
      "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>"
}

{
  "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 arcadeify with the same key returns the original result without a second LLM spend (its own route-scoped namespace).

Path Parameters

string<uuid>

required

Body

application/json

force

boolean

default:false

Rebuild the arcade even when the world already has a progression. Without it, an already-progression world is refused 409.

expectedRev

string

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

Response

Arcade conversion applied (or a no-op — see below). The new revision is the ETag header. versionId is the arcadeify snapshot, and is null when no version was written: a fail-soft post-persist snapshot failure, OR a no-change run (the agent asked a clarifying question / produced no ops — the original world is returned unchanged via reply).

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.

versionId

string<uuid> | null

The arcadeify version snapshot (source ai), parent-chained to HEAD. Null on a no-change run or a fail-soft post-persist snapshot failure.

List the version treeReturns the full version tree (oldest-first); rebuild the tree from each node's `parentVersionId`.

Convert a world into a shoot-for-score arcade

curl --request POST \
  --url https://api.alakazam.gg/v1/worlds/{id}/arcadeify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "force": false,
  "expectedRev": "<string>"
}
'

import requests

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

payload = {
    "force": False,
    "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({force: false, expectedRev: '<string>'})
};

fetch('https://api.alakazam.gg/v1/worlds/{id}/arcadeify', 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}/arcadeify",
  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([
    'force' => false,
    '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}/arcadeify"

	payload := strings.NewReader("{\n  \"force\": false,\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}/arcadeify")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force\": false,\n  \"expectedRev\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"force\": false,\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>",
      "path": "<string>",
      "message": "<string>",
      "loc": {
        "field": "<string>",
        "template": "<string>",
        "slot": "<string>",
        "fill": "<string>"
      }
    }
  ],
  "reply": "<string>",
  "mock": true,
  "versionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "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>",
      "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>"
}

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

Apps & Keys

Worlds

API Reference

Scenario Studio

Sessions

Characters

Vision

Usage

Webhooks

Graph editing

Versions

Simulation & Data

Convert a world into a shoot-for-score arcade

Authorizations

Headers

Path Parameters

Body

Response