Skip to main content
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 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.