> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turntable.games/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API reference

> The Turntable platform API.

Base URL: `https://api.turntable.games`

Auth: `Authorization: Bearer <token>`. Two token kinds:

* **Session tokens** — issued by the auth flows; full account access.
* **Game-scoped tokens** — what game documents receive; valid only for
  `/api/sdk/*` endpoints of their own game.

All request/response bodies are JSON. Errors return
`{ "error": string }` with a 4xx/5xx status.

## Identity & accounts

| Endpoint                                          | Description                                             |
| ------------------------------------------------- | ------------------------------------------------------- |
| `POST /api/auth/guest` `{ deviceId }`             | Idempotent per-device guest account → `{ token, user }` |
| `POST /api/auth/apple` `{ identityToken, name? }` | Native Sign in with Apple → `{ token, user }`           |
| `POST /api/auth/email/start` `{ email }`          | Send a 6-digit sign-in code                             |
| `POST /api/auth/email/verify` `{ email, code }`   | → `{ token, user }`                                     |
| `GET /api/me`                                     | The caller's account: handle, kind, stats, achievements |

Signing in merges the guest account's progress into the member account.

## Feed & games

| Endpoint                                | Description                                                          |
| --------------------------------------- | -------------------------------------------------------------------- |
| `GET /api/feed`                         | Mixed feed: `{ items: [{ type: "game" \| "clip" \| "live", ... }] }` |
| `GET /api/games`                        | All games (metadata + `htmlUrl`)                                     |
| `GET /games/:id/index.html?token=`      | The playable game document, SDK injected                             |
| `POST /api/games/generate` `{ prompt }` | AI generation as a background job (member)                           |
| `GET /api/jobs`, `GET /api/jobs/:id`    | Generation job status                                                |
| `POST /api/games/:id/session`           | Mint a game-scoped token for a play session                          |

## Gameplay telemetry

`POST /api/events` with one of:

```json theme={null}
{ "type": "play_start", "gameId": "..." }
{ "type": "play_end",   "gameId": "...", "durationSeconds": 42 }
{ "type": "score",      "gameId": "...", "score": 100 }
```

Returns `{ user, newAchievements }`.

## Clips & live video

| Endpoint                                                             | Description                                                         |
| -------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `POST /api/clips/upload` `{ gameId?, title?, trimStart?, trimEnd? }` | → `{ clip, uploadUrl }`; PUT the video file to `uploadUrl` (member) |
| `GET /api/clips/mine`                                                | The caller's clips with processing status                           |
| `POST /api/live`                                                     | RTMP ingest credentials for the caller's stream (member)            |

## Profiles & social

| Endpoint                              | Description                              |
| ------------------------------------- | ---------------------------------------- |
| `GET /api/profiles/search?q=`         | Search member profiles by handle/name    |
| `GET /api/profiles/:handle`           | `{ profile, games, clips, social }`      |
| `POST /api/profiles/:handle/follow`   | Follow (member). Mutual follow = friends |
| `DELETE /api/profiles/:handle/follow` | Unfollow                                 |
| `GET /api/friends`                    | The caller's mutual follows              |

## Economy

| Endpoint                                                     | Description                                                        |
| ------------------------------------------------------------ | ------------------------------------------------------------------ |
| `GET /api/wallet`                                            | Coin balance + ledger (session token)                              |
| `GET /api/games/:id/items`                                   | Public: a game's items, including loot-box odds                    |
| `POST /api/games/:id/items`, `PUT .../items/:itemId`         | Creator item management                                            |
| `POST /api/sdk/shop/intents` `{ gameId, itemId }`            | Create a purchase intent (game/SDK)                                |
| `GET /api/sdk/shop/intents/:id`                              | Poll an intent's status                                            |
| `POST /api/shop/intents/:id/approve` \| `/decline`           | Settle an intent — **session token only** (the app's native sheet) |
| `GET /api/sdk/wallet`, `GET /api/sdk/shop/inventory/:gameId` | Balance / inventory from inside a game                             |

## SDK state

| Endpoint                                 | Description                         |
| ---------------------------------------- | ----------------------------------- |
| `GET /api/sdk/state/:gameId`             | The player's saved state for a game |
| `PUT /api/sdk/state/:gameId` `{ state }` | Save (32KB cap)                     |

## Rate limits

Per user unless noted: generation **8/hour** · clips **12/day** · events
**1000/hour** · state writes **600/hour/game** · follows **200/hour** ·
guest creation **30/hour/device**.