> ## 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. # Get a campaign (spine + authored chapters) > Read a campaign: its story spine and the chapter worlds authored so far (ordered by `actIndex`, growing while the generation job runs). Each chapter is an ordinary world — fetch it with `GET /v1/worlds/{worldId}` and run it with `POST /v1/sessions/token`. Generation status/progress is read from `GET /v1/jobs/{jobId}` (the `jobId` returned by POST /v1/campaigns), which exposes `actsDone`/`actsTotal`. Tenant-scoped: a campaign that isn't this app's returns `404`. Uses the **read** scope, so a publishable (`pk_`) key can read it. ## OpenAPI ````yaml /alakazam-v1.yaml get /v1/campaigns/{id} 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/campaigns/{id}: get: tags: - Worlds summary: Get a campaign (spine + authored chapters) description: > Read a campaign: its story spine and the chapter worlds authored so far (ordered by `actIndex`, growing while the generation job runs). Each chapter is an ordinary world — fetch it with `GET /v1/worlds/{worldId}` and run it with `POST /v1/sessions/token`. Generation status/progress is read from `GET /v1/jobs/{jobId}` (the `jobId` returned by POST /v1/campaigns), which exposes `actsDone`/`actsTotal`. Tenant-scoped: a campaign that isn't this app's returns `404`. Uses the **read** scope, so a publishable (`pk_`) key can read it. parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: The campaign resource (spine + chapters authored so far) content: application/json: schema: $ref: '#/components/schemas/Campaign' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: API key is missing the required scope for this operation content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found (or not this app's campaign). content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] components: schemas: Campaign: type: object description: > A multi-chapter book→game campaign: one story spine plus the chapter worlds authored from it. Each chapter is an ordinary playable world (run it via POST /v1/sessions/token like any other). `worlds` lists the chapters authored SO FAR, ordered by `actIndex`, so the list grows while the generation job runs. Tenant-scoped: only the app that created it can read it. required: - id - fidelity - actCount - worlds properties: id: type: string format: uuid title: type: string nullable: true description: >- Campaign title (from the book bible; defaults to the request `name`). logline: type: string nullable: true description: One-line premise distilled from the source text. cover: type: string nullable: true description: Cover image URL (the first chapter's seed, once painted). fidelity: type: string enum: - faithful - spirit description: >- How closely the chapters track the source text (echoes the create request). actCount: type: integer description: >- Total chapters the spine defines (0 until the spine stage completes). `worlds.length` reaches this when the job succeeds. graph: type: object additionalProperties: true nullable: true description: >- The story-spine graph (acts + how they connect). `{}` until the spine stage completes. worlds: type: array description: >- Chapters authored so far, ordered by `actIndex`. Each is a standalone world. items: type: object required: - worldId - actIndex properties: worldId: type: string format: uuid description: >- The chapter world's id (GET /v1/worlds/{worldId}; run it via POST /v1/sessions/token). actIndex: type: integer description: 0-based position in the spine. title: type: string nullable: true description: The chapter/act title. slug: type: string nullable: true description: The chapter world's slug (public worlds only). 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 securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- An app API key, e.g. `Authorization: Bearer sk_live_…`. Secret (`sk_`) for writes/sessions; publishable (`pk_`) is read-only (browser-safe). ````