API reference

Versioned under /api/v1. Player-facing endpoints are called by the hosted play page; management endpoints require a signed-in dashboard session. All are per-IP rate limited and return errors as { "error": { "message": "…" } }.

POST/api/v1/opt-in

Registers a player + consent for a live campaign and returns a short-lived, signed play token. Rate limit: 10/min per IP.

{ "campaign": "summer-tap", "tenant": "acme",
  "player": { "name": "Ada", "email": "ada@x.com" },
  "consent": { "brand": true, "gamivate": false },
  "policyVersion": "2026-07-01" }
// 200 → { "playToken": "…", "sessionId": "uuid" }

POST/api/v1/scores

Submits a score. Requires a valid, unexpired play token bound to that session. Server verifies the token, range-checks the score, allows one score per session, and issues a reward if the score qualifies. Rate limit: 30/min per IP.

{ "playToken": "…", "score": 8500, "metadata": { } }
// 200 → { "entryId": "uuid", "rank": 3, "season": 1,
//         "reward": { "name": "…", "code": "GV-7K9Q", "message": "…",
//                     "expiresAt": "…" } | null }

GET/api/v1/leaderboard/[campaign]

Public top-N for a campaign's current season. Query: limit (≤100), season, and tenant (or the x-gv-tenant-slug header). PII-minimized — display names and scores only, never emails.

// 200 → { "data": [ { "rank": 1, "displayName": "Ada", "score": 8500 } ] }

GET/api/v1/exports/audience

Authenticated.Streams a CSV of the signed-in tenant's audience (query consent=all|consented|declined). Generated on demand — never stored in public storage.

GET/api/v1/dsar/[playerId]

Authenticated.GDPR data-subject export — streams the player's full data bundle (profile, consents, sessions, scores, rewards). Scoped to the caller's tenant; the request is audited.

POST/api/v1/redeem

API key (Growth+). Redeem a reward code from a POS or backend. Send Authorization: Bearer <key> (or x-api-key) and a JSON body { "code": "ABC123" }. Scoped to the key's tenant; the same redeem-once guard as the staff tool. Returns 200 redeemed, 409 already_redeemed, 410 expired, or 404 not_found. Create and revoke keys in Settings → Developer.

Manage tenant API keys under Settings → Developer (Growth+). The raw key is shown once at creation and stored only as a peppered hash. Dashboard endpoints authenticate with the session cookie.