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

# Concepts

> Programmable worlds, sessions, apps, and how they fit together.

Alakazam is the **programmable worlds** API. Everything below is in service of
one idea: a world is software you generate — a live, playable graph you can
read, edit, fork, drive, and react to programmatically.

## Worlds

A **world** is a programmable playable game: a graph of **states** (what the
scene is) and **events** (what the player can do to move between them), rendered
live as the player navigates it. You don't author that graph by hand — you
describe a premise and the API generates a complete, valid world. From there
it's yours to program: read it, patch it, fork variants, and react to its
events at runtime.

Every world returned by the API conforms to a frozen, versioned contract, the
**SMWorld schema** (`schemaVersion: "1.0"`). New optional fields may be added in
minor versions; breaking changes only ever come with a major version, and the
previous major stays readable. See the
[schema](https://alakazam.gg/schema/smworld-1.0.json) and its compatibility
policy.

## Apps and keys

An **app** is your project — the tenant every world, session, and usage record
belongs to. Each app issues API keys:

* **Publishable** (`pk_…`) — safe to expose in a browser; read and embed only.
* **Secret** (`sk_…`) — server-only; creates worlds and mints session tokens.

Keys come in `test` and `live` modes. Test keys only ever touch test resources.

## Sessions and the two-token rule

To play an embedded world, the browser needs a credential — but never your
secret key. Instead:

1. Your server calls `/v1/sessions/token` with the secret key.
2. You get back a **short-lived session token**, scoped to one world, one
   player, and (optionally) one embedding origin.
3. The browser passes that token to `@alakazamworld/embed`.

Short token lifetimes are a feature: the SDK can refresh through your server, so
each renewal is a re-authorization checkpoint.

## Idempotency

`POST /v1/worlds` accepts an `Idempotency-Key` header. A retried request with
the same key returns the original result instead of generating — and charging —
a second time. Use it whenever a network retry is possible.

## Quota

Generations and session mints are metered per app and **reserved before any GPU
spend**. If you're over your daily quota the call returns `402` and nothing is
charged. Check your balance with `GET /v1/usage`.