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

EndpointDescription
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/meThe caller’s account: handle, kind, stats, achievements
Signing in merges the guest account’s progress into the member account.

​
Feed & games

EndpointDescription
GET /api/feedMixed feed: { items: [{ type: "game" | "clip" | "live", ... }] }
GET /api/gamesAll 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/:idGeneration job status
POST /api/games/:id/sessionMint a game-scoped token for a play session

​
Gameplay telemetry

POST /api/events with one of: 
{ "type": "play_start", "gameId": "..." }
{ "type": "play_end",   "gameId": "...", "durationSeconds": 42 }
{ "type": "score",      "gameId": "...", "score": 100 }
Returns { user, newAchievements }.

​
Clips & live video

EndpointDescription
POST /api/clips/upload { gameId?, title?, trimStart?, trimEnd? }→ { clip, uploadUrl }; PUT the video file to uploadUrl (member)
GET /api/clips/mineThe caller’s clips with processing status
POST /api/liveRTMP ingest credentials for the caller’s stream (member)

​
Profiles & social

EndpointDescription
GET /api/profiles/search?q=Search member profiles by handle/name
GET /api/profiles/:handle{ profile, games, clips, social }
POST /api/profiles/:handle/followFollow (member). Mutual follow = friends
DELETE /api/profiles/:handle/followUnfollow
GET /api/friendsThe caller’s mutual follows

​
Economy

EndpointDescription
GET /api/walletCoin balance + ledger (session token)
GET /api/games/:id/itemsPublic: a game’s items, including loot-box odds
POST /api/games/:id/items, PUT .../items/:itemIdCreator item management
POST /api/sdk/shop/intents { gameId, itemId }Create a purchase intent (game/SDK)
GET /api/sdk/shop/intents/:idPoll an intent’s status
POST /api/shop/intents/:id/approve | /declineSettle an intent — session token only (the app’s native sheet)
GET /api/sdk/wallet, GET /api/sdk/shop/inventory/:gameIdBalance / inventory from inside a game

​
SDK state

EndpointDescription
GET /api/sdk/state/:gameIdThe 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.