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

# Frequently asked questions

> Common questions about the programmable worlds API.

<AccordionGroup>
  <Accordion title="What is a 'programmable world'?">
    A world is a playable game expressed as a graph of states and events — a
    little state machine you generate from a prompt. It's *programmable* because
    you don't just get a static asset: you read it, patch it, fork variants, and
    react to its runtime events (`onChoice`, `onEnding`, …) to wire it into your
    own product's logic.
  </Accordion>

  <Accordion title="Publishable vs secret keys?">
    **Secret** keys (`sk_…`) live on your server and can create worlds and mint
    session tokens. **Publishable** keys (`pk_…`) are browser-safe and limited to
    read + embed. Both come in `test` and `live` modes.
  </Accordion>

  <Accordion title="How do I embed a world without exposing my key?">
    Mint a short-lived **session token** on your server with your secret key
    (`POST /v1/sessions/token`), then pass that token — not the key — to
    `@alakazamworld/embed` in the browser. See [Embedding](/embedding).
  </Accordion>

  <Accordion title="How does billing work?">
    The API is free during the developer preview. Generations and sessions are
    metered per app so you can see usage, but nothing is charged. See
    [Pricing](/pricing).
  </Accordion>

  <Accordion title="Will the world shape change under me?">
    No. Worlds conform to a frozen, versioned
    [schema](https://alakazam.gg/schema/smworld-1.0.json) (`schemaVersion`).
    Minor versions only add optional fields; breaking changes require a major
    version, and the previous major stays readable.
  </Accordion>

  <Accordion title="How do I avoid duplicate worlds on a retry?">
    Send an `Idempotency-Key` header on `POST /v1/worlds`. A retry with the same
    key returns the original result instead of generating again.
  </Accordion>
</AccordionGroup>