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

# Quickstart

> Get an API key, create your first world, and embed it.

Alakazam is the **programmable worlds** API. This guide takes you from zero to
an embedded, playable world — create one, then program it into your product.

## Get an API key

<Steps>
  <Step title="Sign in to the dashboard">
    Open the [developer dashboard](https://play.alakazam.gg/?view=developer) and
    sign in with your Alakazam account.
  </Step>

  <Step title="Create an app">
    An **app** is your project. Every world, session, and usage record is
    attributed to it. Create one and give it a name.
  </Step>

  <Step title="Mint a secret key">
    From your app, generate a **secret** key (`sk_test_…`). It's shown once —
    copy it now and store it securely.
  </Step>
</Steps>

<Warning>
  Save your API key in a secure location and never share it. Secret keys
  (`sk_…`) belong on your server only — never in a browser, a prompt, a log, or
  version control.
</Warning>

## Create your first world

To verify your setup, we recommend creating a world from only a text premise.
Send a `POST` to `/v1/worlds` with your secret key:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.alakazam.gg/v1/worlds' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_SECRET_KEY' \
    -d '{
      "name": "Mystical Forest",
      "premise": "A mystical forest with glowing mushrooms"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.alakazam.gg/v1/worlds", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_SECRET_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Mystical Forest",
      premise: "A mystical forest with glowing mushrooms",
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.alakazam.gg/v1/worlds",
      headers={
          "Authorization": "Bearer YOUR_SECRET_KEY",
          "Content-Type": "application/json",
      },
      json={
          "name": "Mystical Forest",
          "premise": "A mystical forest with glowing mushrooms",
      },
  )

  print(response.text)
  ```
</CodeGroup>

The response contains your new world's id, a shareable slug, and its cover
image:

```json theme={null}
{
  "worldId": "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
  "slug": "mystical-forest",
  "ok": true,
  "cover": "https://cdn.alakazam.gg/covers/mystical-forest.png",
  "schemaVersion": "1.0"
}
```

<Note>
  Creation reserves one generation against your daily quota. You can check
  what's left any time with [`GET /v1/usage`](/api-reference).
</Note>

## Embed it

A world is meant to be played. Embedding is two steps: mint a **session token**
on your server, then boot the world in the browser with the SDK.

<Steps>
  <Step title="Mint a session token (server)">
    Call `/v1/sessions/token` with your secret key. Bind it to the player and to
    the origin you'll embed on.

    <CodeGroup>
      ```javascript JavaScript theme={null}
      const r = await fetch("https://api.alakazam.gg/v1/sessions/token", {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_SECRET_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          worldId: "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
          playerIdentity: user.id,
          origin: "https://yourgame.com",
        }),
      });
      const { token } = await r.json(); // send `token` to the browser
      ```

      ```python Python theme={null}
      import requests

      r = requests.post(
          "https://api.alakazam.gg/v1/sessions/token",
          headers={"Authorization": "Bearer YOUR_SECRET_KEY"},
          json={
              "worldId": "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
              "playerIdentity": user_id,
              "origin": "https://yourgame.com",
          },
      )
      token = r.json()["token"]  # send to the browser
      ```
    </CodeGroup>
  </Step>

  <Step title="Boot the world (browser)">
    Install the SDK and mount the world. Pass the session token — never your
    secret key.

    ```bash theme={null}
    npm install @alakazamworld/embed
    ```

    ```javascript theme={null}
    import { createEmbed } from "@alakazamworld/embed";

    createEmbed({
      container: "#game",
      slug: "mystical-forest",
      token, // the session token from your server
      onEnding: (e) => console.log("ending reached", e),
    });
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="World generation examples" icon="images" href="/world-generation-examples">
    Create from a premise, an image URL, or an uploaded frame.
  </Card>

  <Card title="Embedding" icon="square-code" href="/embedding">
    Theming, events, token refresh, and cross-origin security.
  </Card>
</CardGroup>