> ## Documentation Index > Fetch the complete documentation index at: https://docs.alakazam.gg/llms.txt > Use this file to discover all available pages before exploring further. # Apply a batch of graph ops > Apply an ordered batch of `GraphOp`s atomically: unapplicable ops are collected in `applyErrors` (the editor's behavior), then the resulting world is validated ONCE through the kernel gate. A 422 means the batch was rejected as a whole — nothing persists. This single endpoint backs nearly all editor mutations. ## OpenAPI ````yaml /alakazam-v1.yaml post /v1/worlds/{id}/ops openapi: 3.1.0 info: title: Alakazam — Programmable Worlds API version: '1.0' description: > **Alakazam is the programmable worlds API.** Generate playable, AI-rendered worlds from a prompt or an image, program their logic, and embed them in your own products and games. A world is *programmable*: a live graph of states and events you generate, then read, edit, fork, drive, and react to through the API. Two surfaces: a **Creation API** (generate, read, manage, fork worlds) and a **Runtime/Embed API** (mint short-lived session tokens your end-users' browsers use to boot an embedded world). **Authentication.** Two schemes. Management endpoints (`/v1/apps*`) use your Supabase user session. Data endpoints use an **API key** issued per app: `pk_…` (publishable, browser-safe, read + embed) and `sk_…` (secret, server-only, create worlds + mint sessions). Never ship a secret key to a browser. **Usage & quota.** Generations and session mints are metered per app and reserved before any GPU spend; exceeding the daily quota returns `402`. servers: - url: https://api.alakazam.gg description: Production (placeholder — set to your conjure-service host) security: [] tags: - name: Apps & Keys description: >- Create apps (tenants) and manage API keys. Authenticated with your user session. - name: Worlds description: >- Create, read, manage, and fork SMWorld games. Authenticated with an API key. - name: Graph editing description: > Read and program a world's graph — states (nodes), events (edges), and the entrance — with deterministic CRUD, a batch op vocabulary, a natural-language kernel-agent edit, and the kernel validate/lint gate. Every write is validated fail-closed before it persists. Authenticated with an API key. - name: Versions description: > Snapshot, branch, check out, and diff a world's graph. Versions form a branching tree of full snapshots; a HEAD pointer tracks the working graph. Authenticated with an API key. - name: Characters description: > Create, manage, and talk to characters — a SMWorld subtype that pairs a stance-graph with a "brain" (persona, lore, voice). CRUD is authenticated with an API key; the live talk turn (/say) and voice (/tts) are called from the browser with a short-lived session token. - name: Sessions description: Mint short-lived runtime tokens for embedding a world. - name: Usage description: Per-app usage and quota. - name: Webhooks description: >- Register HTTPS endpoints to receive signed server-side event notifications. Managed with your user session. paths: /v1/worlds/{id}/ops: post: tags: - Graph editing summary: Apply a batch of graph ops description: > Apply an ordered batch of `GraphOp`s atomically: unapplicable ops are collected in `applyErrors` (the editor's behavior), then the resulting world is validated ONCE through the kernel gate. A 422 means the batch was rejected as a whole — nothing persists. This single endpoint backs nearly all editor mutations. parameters: - name: id in: path required: true schema: type: string format: uuid - name: If-Match in: header required: false schema: type: string requestBody: required: true content: application/json: schema: type: object required: - ops properties: ops: type: array minItems: 1 items: $ref: '#/components/schemas/GraphOp' expectedRev: type: string responses: '200': description: Batch applied content: application/json: schema: allOf: - $ref: '#/components/schemas/GraphWriteResult' - type: object properties: applyErrors: type: array items: type: string description: >- Per-op messages for ops that could not be applied (non-fatal). '400': description: Empty/invalid ops array content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Concurrent modification content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Failed the kernel gate (not persisted) content: application/json: schema: $ref: '#/components/schemas/GraphValidationError' security: - ApiKeyAuth: [] components: schemas: GraphOp: type: object description: > One operation in the CURATED public op vocabulary applied by `POST /v1/worlds/{id}/ops`. This is a stable, versioned surface mapped onto the internal engine — the kernel's internal op grammar is not exposed. Every op funnels through the same fail-closed validation gate as the dedicated CRUD endpoints. required: - op oneOf: - title: add_state type: object description: >- Create a state (node). `id` is optional; one is auto-assigned when omitted. required: - op properties: op: type: string enum: - add_state id: type: string base: type: string camera: $ref: '#/components/schemas/SMLayerPair' movement: $ref: '#/components/schemas/SMLayerPair' ambient: type: array items: type: string ending: type: object additionalProperties: true variants: type: array items: type: object additionalProperties: true - title: update_state type: object description: Patch fields of an existing state. required: - op - id - patch properties: op: type: string enum: - update_state id: type: string patch: $ref: '#/components/schemas/SMState' - title: delete_state type: object description: >- Delete a state. REJECTED if it is the entrance or referenced by any event/cutscene — detach those refs first. required: - op - id properties: op: type: string enum: - delete_state id: type: string - title: add_event type: object description: >- Create an event (edge). A transition needs `to`; an override must NOT carry `to`. required: - op - kind - from properties: op: type: string enum: - add_event kind: type: string enum: - transition - override from: description: Source state id, or an array of source state ids. oneOf: - type: string - type: array items: type: string to: type: string name: type: string base: type: string detail: type: string hotkey: type: string nullable: true - title: update_event type: object description: Patch any field of an event addressed by its unique `name`. required: - op - name - patch properties: op: type: string enum: - update_event name: type: string patch: $ref: '#/components/schemas/SMEvent' - title: delete_event type: object description: Delete an event addressed by `name`. required: - op - name properties: op: type: string enum: - delete_event name: type: string - title: set_entrance type: object description: >- Set the entrance state (+ optional seed image). The state must exist. required: - op - state properties: op: type: string enum: - set_entrance state: type: string image: type: object required: - src properties: label: type: string src: type: string - title: add_variant type: object description: Add an A/B prompt arm to a state (play-only; never compiled). required: - op - state properties: op: type: string enum: - add_variant state: type: string label: type: string base: type: string camera: $ref: '#/components/schemas/SMLayerPair' movement: $ref: '#/components/schemas/SMLayerPair' ambient: type: array items: type: string - title: remove_variant type: object description: Remove an A/B arm from a state by `label`. required: - op - state - label properties: op: type: string enum: - remove_variant state: type: string label: type: string GraphWriteResult: type: object description: > The result of a graph write. `world` is the new, kernel-validated world; `diagnostics` carries advisory (warning/info) findings; `rev` is the new concurrency token (also returned as the `ETag` header). properties: world: $ref: '#/components/schemas/SMWorld' diagnostics: type: array items: $ref: '#/components/schemas/KernelDiagnostic' rev: type: string description: The new revision token. Pass it as `If-Match` on the next write. schemaVersion: type: string example: '1.0' Error: type: object properties: detail: type: string description: Human-readable error message. errors: type: array items: type: string description: Field-level validation errors (e.g. on 422 from POST /v1/worlds). schemaVersion: type: string required: - detail GraphValidationError: type: object description: >- A 422 from a graph write or validate — the world failed the kernel gate. Nothing was persisted. required: - detail - diagnostics properties: detail: type: string diagnostics: type: array items: $ref: '#/components/schemas/KernelDiagnostic' schemaVersion: type: string example: '1.0' SMLayerPair: type: object description: > A static/dynamic prompt pair. The world model is conditioned on the static layer while the scene holds and on the dynamic layer while it moves. Both are pixel-prose, never authorial intent. properties: static: type: string description: Prose for the held (still) layer. dynamic: type: string description: Prose for the moving layer. SMState: type: object description: > A node in the graph. Optional fields beyond those listed are allowed (forward-compatible). Prose fields must describe pixels, not intent — the kernel doctrine lints enforce this on every write. additionalProperties: true properties: base: type: string description: Scene prose for this node (pixels, not intent). camera: $ref: '#/components/schemas/SMLayerPair' movement: $ref: '#/components/schemas/SMLayerPair' ambient: type: array items: type: string description: Ambient detail prose fragments. ending: type: object description: >- Marks this node as a TERMINAL sink. A node with an ending must be a dead end (no outgoing transitions). required: - kind - title properties: kind: type: string enum: - lose - win title: type: string subtitle: type: string variants: type: array description: A/B prompt arms (play-only; never compiled into the graph). items: type: object additionalProperties: true SMEvent: type: object description: > An edge in the graph, addressed by its unique `name`. A `transition` MUST carry a `to`; an `override` MUST NOT. Optional fields beyond those listed are allowed (forward-compatible). additionalProperties: true required: - name - kind - from properties: name: type: string description: Unique edge id within the world. kind: type: string enum: - transition - override - terminal from: type: array items: type: string description: Source state id(s) this edge fires from. to: type: string description: >- Destination state id. Required for transition, forbidden for override. base: type: string detail: type: string hotkey: type: string nullable: true description: Bound key. Reserved keys (WASD / digits) are rejected. hidden: type: boolean oneShot: type: boolean requires: type: array items: type: string grants: type: array items: type: string SMWorld: type: object description: > 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). additionalProperties: true required: - id - name - entrance - scene properties: id: type: string name: type: string description: type: string cover: type: string entrance: type: object required: - image - state properties: image: type: object required: - src properties: label: type: string src: type: string description: Seed image for the boot. state: type: string description: Initial state id. scene: type: object required: - states - events properties: states: type: object additionalProperties: true events: type: array items: type: object additionalProperties: true KernelDiagnostic: type: object description: > A single finding from the kernel grammar + doctrine lint suite. STRUCTURAL lints (e.g. `dangling-ref`, `transition-needs-to`, `kernel-cycle`, `slot-*`) are always fatal `error`s and block the write (422). Doctrine/budget lints (e.g. `negation`, `whiteout`, `lethal-override`, `budget`) are advisory and surface as `warning`/`info`. required: - lint - severity - path - message properties: lint: type: string description: The lint id (e.g. `dangling-ref`, `negation`, `budget`). severity: type: string enum: - error - warning - info path: type: string description: Human-readable location, e.g. `event[Step outside].movement.static`. message: type: string description: What is wrong and, where possible, how to fix it. loc: type: object description: Structured location for editor/narrator UIs. properties: field: type: string template: type: string slot: type: string fill: type: string securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- An app API key, e.g. `Authorization: Bearer sk_live_…`. Secret (`sk_`) for writes/sessions; publishable (`pk_`) for read/embed. ````