> ## 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.

# Agent quickstart

> One prompt to brief your coding agent on Alakazam and wire it into your app.

Alakazam is built to be integrated by AI coding agents. Give your agent the [skill](/install-skill) so it knows the API across sessions, then paste the prompt below — it briefs the agent on every `/v1` endpoint, installs the skill, scans your repo for places an embedded AI world would help, and proposes tailored integrations.

<Info>
  If you are an agent: get a key by signing your user up at
  [play.alakazam.gg/?view=developer](https://play.alakazam.gg/?view=developer), mint
  an `sk_test_…` key (free, mocked [sandbox](/testing)), and export it as
  `ALAKAZAM_SECRET_KEY`.
</Info>

## Get your API key

<Steps>
  <Step title="Open the developer dashboard">
    [play.alakazam.gg/?view=developer](https://play.alakazam.gg/?view=developer) → create an app.
  </Step>

  <Step title="Mint a secret key">
    Start with an `sk_test_…` key — it runs a free, mocked [sandbox](/testing) (no GPU spend). Swap to `sk_live_…` when you ship.
  </Step>

  <Step title="Export it">
    ```bash theme={null}
    export ALAKAZAM_SECRET_KEY="sk_test_..."
    ```

    Keep it server-side. For browser reads/like buttons, also mint a publishable `pk_…` key.
  </Step>
</Steps>

## Install the skill

So the knowledge persists across sessions without re-pasting ([details](/install-skill)):

```bash theme={null}
npx skills add -g https://docs.alakazam.gg/skill.md
```

## Copy the prompt

Run your agent in your app's directory and paste this (or [▶ open it in Cursor](cursor://anysphere.cursor-deeplink/prompt?text=You%20are%20integrating%20the%20Alakazam%20programmable%20worlds%20API%20into%20this%20app.%20First%20read%20https%3A%2F%2Fdocs.alakazam.gg%2Fskill.md%20and%20https%3A%2F%2Fdocs.alakazam.gg%2Fagent-quickstart%20%2C%20then%20follow%20the%20agent-quickstart%20steps%20in%20order.)):

```text theme={null}
# You are onboarding this project to Alakazam (the programmable worlds API)

Alakazam turns a text premise or an image into a playable, AI-rendered game world
you can program and embed in any app or game. Base URL: https://api.alakazam.gg.
Full reference: https://docs.alakazam.gg (raw index: https://docs.alakazam.gg/llms.txt).

## What you can call

| Area | Inputs | Output | Guide |
|---|---|---|---|
| Create a world | premise text · image URL/upload · or a compiled `world` to import | A playable SMWorld (id, slug, cover) | https://docs.alakazam.gg/world-generation-examples |
| Characters | persona/stances, an example file, or `authored:true` + a premise | A talk-to character (reply, stance, voice, image) | https://docs.alakazam.gg/characters |
| Embed / runtime | worldId (server) → session token (browser) | A live, streamed, playable world via @alakazamworld/embed | https://docs.alakazam.gg/embedding |
| Program the graph | states/events CRUD, a batch op vocab, or natural language | An edited, kernel-validated world graph | https://docs.alakazam.gg/graph-editing |
| Frame → world (vision) | an image | seed frame · detected objects · clickable hotspot boxes | https://docs.alakazam.gg/vision |
| Versions | snapshot / branch / diff / checkout | A branching version tree over a world | https://docs.alakazam.gg/versions |
| Usage | your key | Today's usage vs daily caps | https://docs.alakazam.gg/api-reference |

Billing is runtime-only: you pay for session_seconds (live play time); creating and
editing are free (bounded by a daily quota, not a charge). A test key (sk_test_…) is a
free, mocked sandbox — every response carries "mock": true and nothing spends. Full
docs: https://docs.alakazam.gg. Test sandbox: https://docs.alakazam.gg/testing.

Now work the steps below in order. Don't skip ahead. Stop where a step says to.

## Step 1 — Find the credentials

Alakazam uses per-app bearer keys:

| Credential | Env var | Powers | Exposure |
|---|---|---|---|
| Secret key (sk_…) | ALAKAZAM_SECRET_KEY | create/edit worlds + mint session tokens | Backend only |
| Publishable key (pk_…) | ALAKAZAM_PUBLISHABLE_KEY | browser reads + a like button | Frontend-safe |

Both come in test and live modes (sk_test_ / sk_live_). Check the environment and any
local .env. Never print the actual key value back to me — just say whether each was found.

If no secret key, give me these steps and wait for my confirmation:
1. Open https://play.alakazam.gg/?view=developer and create an app.
2. Mint a secret key. Start with sk_test_… (free, mocked sandbox — no GPU spend).
3. Export it: export ALAKAZAM_SECRET_KEY='sk_test_...'
4. Tell me when it's set.

Setup + auth reference: https://docs.alakazam.gg/quickstart and https://docs.alakazam.gg/concepts

If the key is set, say which credentials you found and continue.

## Step 2 — Brief me, then install the skill (+ MCP when available)

Use the 'What you can call' table to give me a rundown. Then install the skill so this
knowledge persists across sessions:

  npx skills add -g https://docs.alakazam.gg/skill.md

Verify it loaded by asking yourself: "Using Alakazam, how do I embed a world in a
browser without exposing my secret key?" — a correct answer describes the two-token
rule (server mints a session token via POST /v1/sessions/token; the browser uses that
token, never the key).

For LIVE tool calls, also install the MCP server (@alakazamworld/mcp) so you can
generate/edit/embed worlds directly: https://docs.alakazam.gg/install-mcp
(e.g. Claude Code: `claude mcp add alakazam --env ALAKAZAM_SECRET_KEY=$ALAKAZAM_SECRET_KEY -- npx -y @alakazamworld/mcp`).

## Step 3 — Scan this repo for integration opportunities

If this directory has application source, read enough to understand it, then map
findings against the table below. Reference exact files + lines. If the repo is empty
or docs-only, say so and skip to Step 5.

| Code pattern | Replace / augment with | Guide |
|---|---|---|
| Static, hand-authored, or scripted game levels/scenes | Generate playable worlds from a prompt or concept image | https://docs.alakazam.gg/world-generation-examples |
| Hardcoded NPCs, dialogue trees, or a plain chatbot | A talk-to AI character with stances, memory, and voice | https://docs.alakazam.gg/characters |
| A "create your own game / level" or UGC surface | Let users generate + fork + share worlds via the API | https://docs.alakazam.gg/world-generation-examples |
| Concept art / mood boards / reference images for level design | Frame → world: turn an image into geometry + clickable hotspots | https://docs.alakazam.gg/vision |
| A "play", "preview", or "demo" surface embedding game content | Embed a live world via a server-minted session token + the SDK | https://docs.alakazam.gg/embedding |
| Hand-built branching / state-machine game logic | Program the world graph (states/events/ops) or edit it in natural language | https://docs.alakazam.gg/graph-editing |
| Save-slots / variants / undo for authored content | World versions: snapshot, branch, diff, checkout | https://docs.alakazam.gg/versions |
| A like/upvote or play-count feature for shared creations | plays/likes on every world read + POST /v1/worlds/{id}/like (pk_-driven) | https://docs.alakazam.gg/world-generation-examples |

## Step 4 — Propose, then get my approval before touching code

Present findings as a numbered list. For each: the file + line range and what it
replaces · the endpoint(s) + whether they're free (creation) or runtime-metered ·
the exact guide link above · one line on why it's an improvement. Then ask which to
implement. Don't modify files until I approve specific items. Build against a
sk_test_… key first (free sandbox), and follow the two-token rule for any embed.

## Step 5 — Suggest uses + side projects tailored to me

Do this if application code doesn't exist here. Personalize using my CLAUDE.md, my
memory index (MEMORY.md) if present, anything I've told you, and the repo's name +
surroundings. Then produce:

1. 3–5 places in my actual work or stack where an Alakazam endpoint would save effort
   or unlock something new. Tie each to a specific endpoint + a guide link above.
2. 2–3 small, finishable side-project ideas (weekend scope) that lean on my interests.
   Show the endpoints each needs. Examples to riff on:
   - "Prompt → playable world in a tweet": premise in, an embeddable link out (create + embed).
   - Talk-to-NPC widget: drop an AI character with voice into any page (characters + sessions).
   - Image → explorable scene: upload a photo, get a clickable world (vision + embed).
   - UGC arcade: users generate + share worlds, others play + like (create + fork + like + embed).

Don't build anything in Step 5 unless I ask; just propose.
```

## Next steps

<CardGroup cols={2}>
  <Card title="Install the skill" icon="wrench" href="/install-skill">
    One command, every agent.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first world + embed it by hand.
  </Card>

  <Card title="Testing sandbox" icon="flask" href="/testing">
    Build the whole integration free with a test key.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference">
    Every endpoint, parameter, and response.
  </Card>
</CardGroup>