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

# Overview

> The API for programmable, playable AI worlds.

Alakazam gives your users an AI-rendered world they can actually play. With one
API call you generate a world from a text premise or an image, program its logic,
and embed it in your app, branded as your own.

A world is a graph of states and events. Your players move through it, making
choices that change what they see and where the story goes, and the API renders
each moment as they play.

There are two surfaces:

<CardGroup cols={2}>
  <Card title="Creation API" icon="wand-sparkles">
    Generate, read, manage, and fork worlds. Authenticated with a secret API
    key from your server.
  </Card>

  <Card title="Runtime & Embed API" icon="play">
    Mint short-lived session tokens your end-users' browsers use to boot an
    embedded world with the `@alakazamworld/embed` SDK.
  </Card>
</CardGroup>

<Note>
  **Building with an AI coding agent?** Install the [skill](/install-skill) and the
  [MCP server](/install-mcp) (`npx @alakazamworld/mcp`) so your agent knows the API
  and can call it live, or paste the [agent quickstart](/agent-quickstart) prompt
  to have it self-onboard and wire Alakazam into your app.
</Note>

## The mental model

* A **world** is a *programmable*, playable graph of states and events
  the player navigates, rendered live. You generate it, then read, edit, fork,
  and react to it through the API. The full shape is the versioned `SMWorld`
  schema in the [API reference](/api-reference).
* You create a world from a **premise** (a "what if" pitch) and/or a **seed
  frame** (an image). Creation is a single call that returns the world.
* You embed a world by minting a **session token** on your server and handing it
  to the browser. The token is short-lived and scoped to one world and one
  player.

## The two-token rule

<Warning>
  Your **secret** key (`sk_…`) stays on your server. Never ship it to a browser.
  To embed a world, your server mints a short-lived **session token** and hands
  *that* to the client.
</Warning>

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get a key, create your first world, and embed it, in a few minutes.
  </Card>

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