> ## 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 control command, get the next observation > One call per control tick — the response IS the post-action observation. Discrete `action`, or differential `wheels` (right wheel faster → veers left; echoed back as `applied_action`). ## OpenAPI ````yaml /alakazam-v1.yaml post /v1/sim/sessions/{id}/step openapi: 3.0.3 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-only) and `sk_…` (secret, server-only — create/edit worlds and mint session tokens). Embedding a world in a browser uses a short-lived **session token** minted server-side with a secret key (not a publishable key directly). Never ship a secret key to a browser. **Test vs live.** Keys come in `test` and `live` modes — the prefix tells you which (`sk_test_…`/`pk_test_…` vs `sk_live_…`/`pk_live_…`). A **test** key runs against a sandbox: every generative endpoint returns a deterministic mock marked `"mock": true`, with no GPU or vendor spend; test worlds/characters are isolated from live data (forced `private`, never slugged or discoverable); and test usage is **never** billed. See the Testing guide. **Usage, quota & billing.** Every operation is counted against a per-app daily quota, reserved before any GPU spend. Exceeding it returns `402`. The quota is a free abuse guard, not a charge. Billing, when enabled, is **runtime-only**: you pay for `session_seconds` (live play time). Creating worlds and every other operation are free. Test-mode usage is never billed, even after billing is enabled. The API is in developer preview. See Pricing. **Building with an AI coding agent?** Install the skill (`npx skills add -g https://docs.alakazam.gg/skill.md`) and the MCP server (`npx @alakazamworld/mcp`) so your agent knows this API and can call it live. See the Agent quickstart. 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 of states (nodes), events (edges), and the entrance, using 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: Scenario Studio description: > Author variation/counterfactual plans over an episode or scenario, submit them as durable batches (N verified clips), poll them, and accept/reject each result. Nothing bills at submit — a clip is charged only when accepted; rejected and failed clips never touch the ledger. Authenticated with an API key. - 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. - name: Simulation & Data description: > **Beta — self-hosted runner.** Drive a world headlessly as a training environment (gym) and stream the SNN-controller observation contract: two virtual proximity sensors, collision spikes, object labels, and an optional square RGB camera. The same schema is emitted offline by the dataset exporter (JSONL episodes + train-ready NPZ), so controllers trained on recorded data plug straight into the live loop. paths: /v1/sim/sessions/{id}/step: post: tags: - Simulation & Data summary: Apply a control command, get the next observation description: > One call per control tick — the response IS the post-action observation. Discrete `action`, or differential `wheels` (right wheel faster → veers left; echoed back as `applied_action`). operationId: stepSimSession parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: action: type: string enum: - left - right - forward - none wheels: type: object properties: left: type: number right: type: number holdMs: type: integer minimum: 60 maximum: 2000 default: 300 responses: '200': description: Observation after the action window. content: application/json: schema: $ref: '#/components/schemas/SimObservation' '400': description: Bad command '404': description: Unknown session components: schemas: SimObservation: type: object description: > The SNN-controller observation contract. `proximity` = two virtual range sensors (0 = clear, 1.0 = contact range); `collision` is a SPIKE — true exactly once per collision event, guaranteed to read 1.0 on the colliding side. properties: proximity: type: object properties: left: type: number minimum: 0 maximum: 1 right: type: number minimum: 0 maximum: 1 collision: type: boolean collision_count: type: integer done: type: boolean description: Only latches when terminal_collision=true. t_ms: type: integer sensor_age_ms: type: integer nullable: true description: Sensor staleness vs the camera frame. applied_action: type: string labels: type: array items: type: object properties: id: type: string type: type: string confidence: type: number camera: type: object properties: image: type: string description: Square RGB frame as a data-URL JPEG. ````