--- type: reference --- # API endpoints Three HTTP endpoints. All follow the [inverted envelope](#inverted-envelope) — Cap's wire format is the top level, Caputchin data rides under `platform`. The platform server is a dumb proxy for Cap parts and never parses or transforms Cap's shapes. See [ADR-0003](adr/0003-inverted-envelope.md) for why. The browser-side endpoints (`/game/start`, `/game/complete`) are reached via Cap's `CAP_CUSTOM_FETCH` hook, which the [widget](widget.md) uses to inject the `platform` field into Cap's outgoing request bodies. The customer-backend endpoint (`/siteverify`) is reCAPTCHA-shape-compatible at the top level. ## Inverted envelope ``` { ...cap_native_shape, "platform": { ...caputchin_extensions } } ``` Why this shape: Cap's protocol can change without affecting platform code; the server forwards bytes and only reads the `platform` field. See [cap-integration](cap-integration.md) for the full proxy posture. ## `POST /game/start` (browser → platform) Fires when the user *starts the game*, not on widget mount. The widget calls Cap's `solve()` lazily so users who never play don't generate challenges. **Request:** ```json { "...cap_challenge_request fields": "...", "platform": { "sitekey": "cpt_pub_...", "gameId": "bubble-pop" } } ``` `sitekey` is the customer's public site key (visible in the widget mount attribute). `gameId` is optional — absent for the invisible-default mode, present otherwise (marketplace ID or customer-supplied label). **Response:** ```json { "...cap_challenge_response fields": "...", "platform": { "sessionId": "...", "gameNonce": "..." } } ``` The `gameNonce` is server-issued, signed with the platform secret, and carries `{ sessionId, gameId, issuedAt, expiresAt }`. See [wrapped token](#wrapped-token). ## `POST /game/complete` (browser → platform) Fires every time the game's `onComplete` callback fires. Games may legitimately fire `onComplete` multiple times (replay, multi-round) — see [game-sdk](game-sdk.md). The server dedups Cap's `redeem` per session: only the first call proxies redeem and constructs the wrapped token; subsequent calls only record score for scoreboard purposes. **The endpoint never blocks on user input.** Score persistence is decoupled from nickname collection — the row is recorded immediately, and the optional scoreboard handle is set later via the separate [`/game/nickname`](#post-gamenickname-browser--platform) endpoint. See [ADR-0014](adr/0014-scoreboard-3letter-async-naming.md). **Request:** ```json { "...cap_redeem_request fields": "...", "platform": { "sessionId": "...", "score": 0.847, "durationMs": 4200 } } ``` `score` and `durationMs` are both nullable. The [invisible default widget mode](widget.md#modes) (no game configured) sends `score: null`; manual mode customers may also omit either field. Either way they are client-claimed metadata, not security signals. **Response (first call):** ```json { "...cap_redeem_response fields": "...", "platform": { "wrappedToken": "..." } } ``` **Response (subsequent calls):** ```json { "platform": { "recorded": true } } ``` The wrapped token is locked at first completion. The widget uses Cap's `CAP_CUSTOM_FETCH` to hold the redeem call until the first `onComplete` fires. ## `POST /game/nickname` (browser → platform) Sets or updates the 3-letter scoreboard handle for the session. **Non-blocking from the verification flow:** the wrapped token is already returned by the time this fires, and the customer's `/siteverify` does not depend on it. A session that never calls this endpoint records its entries with a `NULL` nickname (rendered as `---` on the [dashboard scoreboard view](dashboard.md#scoreboards-post-mvp)). See [ADR-0014](adr/0014-scoreboard-3letter-async-naming.md). **Request:** ```json { "platform": { "wrappedToken": "...", "nickname": "AAA" } } ``` **Response:** ```json { "platform": { "set": true } } ``` | Field | Constraint | |---|---| | `wrappedToken` | Authenticates the call; must be unexpired | | `nickname` | Server-validates `^[A-Z]{3}$` and a small profanity blocklist; reject → `400` | The call is idempotent and last-write-wins; the user may resubmit until the wrapped token expires. The update applies to **all** scoreboard entries for the session — one nickname per session, not per round. Rate-limited per session to bound abuse without identifying. ## `GET /games/:id/resolve` (browser → platform) Returns the script URL and SRI integrity hash for a marketplace game ID so the widget can build its sandboxed iframe at mount. Customer-hosted games skip this endpoint — the customer supplies the URL via the widget's `game-src` attribute. See [widget](widget.md#game-loading), [marketplace](marketplace.md#indexer-rules), and [ADR-0015](adr/0015-sandbox-game-iframe.md). **Request:** none (URL parameter only). **Response:** ```json { "url": "https://cdn.jsdelivr.net/npm/@cooperative-games/bubble-pop@1.2.0/dist/bubble-pop.js", "integrity": "sha384-..." } ``` The hash is computed by the marketplace indexer at index time and pinned per version. The widget passes both into the iframe's `