Skip to main content

​
Scope

This guide is the HTTP contract for /api/v1/engage/games/*. It is additive to the public Games catalog. Do not replace GET /api/games/catalog with the engine catalog. Clients that already consume the unversioned route keep working. Deep dives: Game Engine overview · Client · Server · Modularity

​
Coverage

Status: Publish. These operations are in generated OpenAPI under the Game Engine tag (also tagged Games and Engage). They landed in d-sports-api#536. Use the Endpoints group for request/response playgrounds.

​
Endpoints

locker-singularity does not use those session verbs. Its progression is an idle ledger under /api/v1/engage/games/locker-singularity/ledger. The catalog still lists the game (playable: true while the Game row is LIVE). Ledger routes serve a COMING_SOON row normally. A missing Game row returns 404 GAME_UNKNOWN and does not create a ledger. Buzz counters on the wire are decimal strings. These routes write toy currencies only. They do not change DSC balances, Rep, PointsHistory, pack inventory, or marketplace state. Mutations require a UUID v4 idempotencyKey. Replaying the same key returns the stored response. The same key with a different body returns 400 and does not credit twice. Send optional X-Client-Version on ledger reads and on taps, buy, upgrades, and prestige. Below minClientVersion those routes return 403 GAME_UPDATE_REQUIRED. The boost claim route does not apply that gate. Send Authorization: Bearer <Clerk token> on session verbs and on ledger routes. X-Client-Version is optional in OpenAPI. If you build a supported Engage native client, send it on every engine call. If a game has minClientVersion and the header is missing or unparseable, the catalog marks the row UPDATE_REQUIRED and session start returns 403 GAME_UPDATE_REQUIRED. If minClientVersion is unset, an absent header does not block play. Session start returns:
  • 403 GAME_UPDATE_REQUIRED when the binary is below minClientVersion
  • 404 GAME_UNKNOWN for an unknown key
  • 409 GAME_DAILY_NOT_ELIGIBLE when the current UTC day slot is already used

​
Client rules

  • Render awarded Rep after complete, not requested.
  • Treat GAME_UPDATE_REQUIRED as an update wall. Treat GAME_DAILY_NOT_ELIGIBLE as already played.
  • Reject scenario payloads that leak answers (correctIndex, resolutionKey, answer).
  • Do not call /api/v1/engage/rep/earn from a playfield. Awards are server-side.

​
Not in this guide

  • GET /api/games/catalog and legacy play routes — Games API
  • Game Center schedule and realtime — /api/events/*
  • Admin catalog management — redacted
  • Cron settlement — excluded
  • Deprecated POST /api/games/daily-spin/reward — excluded