Skip to main content

​
Quest API surface (non-admin)

  • GET /api/quests: fetch active quests.
  • POST /api/quests/start: start a quest for a user.
  • POST /api/quests/complete-step: mark a step complete and award step points.
  • POST /api/quests/check-progress: trigger action-based progression checks.
  • POST /api/quests/daily-visit: complete the daily dashboard visit quest.
  • GET /api/user/completed-quests: read quest-related completion history from points records.
  • POST /api/v1/engage/quests/{questId}/session: start a timed daily-quest quiz session.
  • POST /api/v1/engage/quests/session/{sessionId}/submit: submit an answer.
  • POST /api/v1/engage/quests/session/{sessionId}/forfeit: burn the UTC-day attempt.
  • GET /api/v1/engage/quests/daily-summary: per-followed-team checklist.
  • POST /api/v1/engage/quests/arena-check-in: once per team per UTC day.

​
Lifecycle

  1. Quest definitions come from Quest + ordered QuestStep.
  2. User progress is stored in UserQuestStatus + UserStepStatus.
  3. Completing a step writes points immediately (if step has points).
  4. Quest is marked complete only after all required steps are completed.

​
Per-team quest model

  • Quest progression can be scoped by team context in addition to global quest tracks.
  • Team-aware quest visibility and completion are evaluated server-side.
  • Team/favorites and assignment context can affect eligibility routing.

​
Eligibility resolution (favorites, team scope, pass state)

  • Eligibility combines quest requirements, user/team context, and pass state.
  • Pass-aware routing includes global pass and event pass checks where configured.
  • Clients should refresh quest payloads after key mutations instead of assuming local eligibility.

​
Global pass and event pass behavior

  • Global pass can unlock broader quest/reward eligibility surfaces.
  • Event pass can gate event-specific quest paths and progression outcomes.
  • Both pass types are evaluated by backend logic and reflected in response payloads.

​
Completion and anti-abuse behavior

  • Completion checks remain backend-authoritative.
  • Progress routes can include anti-abuse validation paths for action-based completion.
  • Invalid completion attempts should return explicit, user-actionable responses.

​
Native integration expectations

  • Native quest UI should present team/pass eligibility as returned by API payloads.
  • Quest completion actions should trigger refresh of quest/reward state.
  • Client copy should distinguish availability, locked-by-pass, and completed states.

​
Action-based progression checks

checkAndCompleteQuestProgress() evaluates user actions and conditionally completes steps. Current checks include:
  • Follow user
  • Upload profile picture
  • Choose favorite team
  • Complete profile
  • Get followers
  • Join leaderboard
  • Earn points threshold
  • Reach leaderboard rank threshold

​
Known caveats

  • Some step resolution currently relies on matching step titles. This is fragile if copy changes.
  • A future stable step code pattern is preferred for long-term reliability.