Gamification API

Scope

Gamification APIs include quest progression, daily quiz sessions, leaderboard reads/streams, rewards, and related user quest history.

Legacy quests: /api/quests, /api/quests/start, /api/quests/complete-step, /api/quests/daily-visit, /api/quests/check-progress
Engage daily quests: /api/v1/engage/quests/{questId}/session, /api/v1/engage/quests/session/{sessionId}/submit, /api/v1/engage/quests/session/{sessionId}/forfeit, /api/v1/engage/quests/daily-summary, /api/v1/engage/quests/arena-check-in
Leaderboard: /api/leaderboard, /api/leaderboard/stream, /api/leaderboard/search, /api/leaderboard/seasons, /api/leaderboard/winners, /api/leaderboard/stats
Rewards: /api/rewards, /api/rewards/claim, /api/rewards/redeem
User quest history: /api/user/completed-quests

Fan Rep lives on a separate ledger. See Fan Rep.

POST /api/v1/engage/quests/{questId}/session starts a timed daily-quest quiz session.
POST /api/v1/engage/quests/session/{sessionId}/submit records an answer. Send { answerIndex: number }. The generated spec describes that body in prose and does not yet declare a requestBody schema.
POST /api/v1/engage/quests/session/{sessionId}/forfeit burns the UTC-day attempt.
GET /api/v1/engage/quests/daily-summary returns the per-followed-team checklist.
POST /api/v1/engage/quests/arena-check-in is once per team per UTC day.
Amount and Rep type for arena check-in and daily-quest completion are server-authoritative. Do not send those through POST /api/v1/engage/rep/earn.

Quest behavior includes team-aware eligibility and pass-aware progression semantics in addition to base step completion flows.

Team-scoped eligibility is resolved server-side and reflected in quest availability/completion outcomes.
Pass-aware behavior supports global pass and event pass gates where configured.
Completion routes can trigger side effects across points history and leaderboard aggregation.

Global pass and event pass effects are backend-authoritative.
Clients should render eligibility state from API responses rather than local assumptions.
Progress transitions should be treated as eventual-consistency aware across cross-feature surfaces.

Reward flows include differentiated free and unpaid reward handling semantics.
Claim/redeem operations remain server-validated and should be treated as mutation operations with explicit failure handling.

Leaderboard stream clients should reconnect with backoff and refresh snapshots.
Quest step completion can trigger side effects such as points history writes.
Quest/pass state should be re-fetched after completion/claim mutations to avoid stale client assumptions.