# Playworks AI Agent Reference

Playworks lets AI agents create browser games, edit generated files, package builds, prepare releases, and read public game and reward data.

API base: `https://api.playworks.gala.com`

## Discovery

- Human setup page: `https://playworks.gala.com/ai`
- Markdown reference: `https://playworks.gala.com/ai.md`
- Agent index: `https://playworks.gala.com/llms.txt`
- Public API base: `https://api.playworks.gala.com`

## Authentication

Create an API key from a wallet-authenticated browser session at `/me/api-keys`, then send it as a Bearer token:

```bash
curl https://api.playworks.gala.com/auth/session \
  -H "Authorization: Bearer pw_your_key_here"
```

Treat `401` as an invalid, expired, or revoked key. Return to the browser wallet session to create a replacement key.

## API Key Policy

API keys may list existing keys for the same wallet. Creating or revoking API keys requires a wallet-authenticated browser session cookie; Bearer API keys cannot create or revoke API keys.

List keys for the same wallet:

```bash
curl https://api.playworks.gala.com/me/api-keys \
  -H "Authorization: Bearer pw_your_key_here"
```

## Public Endpoints

Public endpoints do not require a Bearer token.

- `GET /games?limit=20`
- `GET /games/GAME_SLUG`
- `GET /rewards/stats`

```bash
curl "https://api.playworks.gala.com/games?limit=20"
```

```bash
curl https://api.playworks.gala.com/games/GAME_SLUG
```

```bash
curl https://api.playworks.gala.com/rewards/stats
```

## Creator REST Workflows

Documented owned creator endpoints accept `Authorization: Bearer pw_your_key_here` after you create a key from a wallet-authenticated session. The key can only act on resources owned by the key wallet.

### Projects vs Games

Use `/creator/projects` when Playworks is the authoring workspace: create an AI project, submit prompts, edit generated files, preview, validate, then call `/creator/projects/PROJECT_ID/create-version`. Each AI project has a linked `gameId`; `create-version` packages the project files, uploads the build to that linked game, and attempts publish.

Use `/creator/games` when you already have a game record or ZIP build to manage directly: list/create/update game metadata, upload a ZIP with `/creator/games/GAME_ID/versions`, then publish the returned version. Do not create both a project and a game at the start of the same AI-native flow; start with projects for generated games, or games for direct build uploads.

Create an AI project:

```bash
curl -X POST https://api.playworks.gala.com/creator/projects \
  -H "Authorization: Bearer pw_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Leaderboard Arcade","description":"Fast arcade game with token reward hooks."}'
```

List owned projects:

```bash
curl https://api.playworks.gala.com/creator/projects \
  -H "Authorization: Bearer pw_your_key_here"
```

Upload a ZIP build for a game. Upload runs build validation and does not require a GALA payment:

```bash
curl -X POST https://api.playworks.gala.com/creator/games/GAME_ID/versions \
  -H "Authorization: Bearer pw_your_key_here" \
  -F "file=@game.zip" \
  -F "versionLabel=ai-build-1"
```

Publish a version. Payment only blocks release. If the game is uploaded and ready but payment is required, this endpoint returns HTTP `402` with `code: "RELEASE_PAYMENT_REQUIRED"` and a `payment.paymentUrl` for the creator:

```bash
curl -X POST https://api.playworks.gala.com/creator/versions/VERSION_ID/publish \
  -H "Authorization: Bearer pw_your_key_here"
```

When you receive `RELEASE_PAYMENT_REQUIRED`, do not ask the user for a private key, seed phrase, wallet signature, or browser cookie. Tell the user to open `payment.paymentUrl` in a browser. The page says what GALA amount will be paid and which game will be published. The user connects their wallet, signs the GalaChain transfer, and the page publishes the version. When it confirms, it says they may close the window and return to their AI.

## AI Project REST Workflows

Submit a prompt:

```bash
curl -X POST https://api.playworks.gala.com/creator/projects/PROJECT_ID/prompts \
  -H "Authorization: Bearer pw_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Add a leaderboard, mobile controls, and clearer win feedback."}'
```

List generated files:

```bash
curl https://api.playworks.gala.com/creator/projects/PROJECT_ID/files \
  -H "Authorization: Bearer pw_your_key_here"
```

Update a file:

```bash
curl -X PUT https://api.playworks.gala.com/creator/projects/PROJECT_ID/files/src/main.js \
  -H "Authorization: Bearer pw_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content":"export function startGame() { console.log(\"ready\"); }"}'
```

Create a preview:

```bash
curl -X POST https://api.playworks.gala.com/creator/projects/PROJECT_ID/preview \
  -H "Authorization: Bearer pw_your_key_here"
```

Prepare a version:

```bash
curl -X POST https://api.playworks.gala.com/creator/projects/PROJECT_ID/prepare-version \
  -H "Authorization: Bearer pw_your_key_here"
```

Create a version from an AI project. If payment is required, the project files are prepared/uploaded before publish is blocked and the response will include the same `RELEASE_PAYMENT_REQUIRED` handoff details:

```bash
curl -X POST https://api.playworks.gala.com/creator/projects/PROJECT_ID/create-version \
  -H "Authorization: Bearer pw_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"versionLabel":"ai-generated-v1"}'
```

## MCP Usage

Claude Code and other MCP clients can run the Playworks MCP server locally. Set:

```text
PLAYWORKS_API_URL=https://api.playworks.gala.com
PLAYWORKS_API_KEY=pw_your_key_here
```

Use `playworks_login { mode: "api_key" }` or rely on `PLAYWORKS_API_KEY` auto-auth. MCP calls use the same owned-resource constraints as REST.

MCP agents should upload builds first. If `playworks_publish_version` or `playworks_upload_build` with `autoPublish: true` returns a release-payment-required error, show the included payment URL to the user and wait for them to complete the browser payment page.

## Game Build Requirements

- Put `index.html` at the ZIP root.
- Keep the ZIP under 50 MB.
- Use deterministic gameplay and a seeded PRNG instead of `Math.random()`.
- Log player inputs with tick numbers for score verification.
- Communicate with the Playworks shell through the PostMessage SDK protocol.

## Safety Limits

- Do not place private keys, seed phrases, wallet secrets, session cookies, or user identifiers in game files or prompts.
- Do not attempt to pay or sign GalaChain transactions with an API key. Use the browser payment URL returned by publish.
- Do not document or call admin endpoints with API-key Bearer auth.
- Do not mix preview tokens with publish operations.
- Keep generated games suitable for public web playback and deterministic score review.