Gamification

The gamification system keeps testers engaged by rewarding quality and consistency. After each confirmed session, call the evaluate endpoint to process earned points, check badge conditions, and trigger level-up logic.

Scoring Model

Points are calculated from a weighted combination of session signals:

Signal	Max Points
Session completed	50
Business rating (4-5 stars)	30
Think-aloud quality score	20
On-time completion bonus	10
Streak bonus (3+ consecutive sessions)	20

Badges are awarded when cumulative thresholds are crossed. Levels advance at 500-point intervals.

Endpoints

POST /api/gamification/evaluate JWT

Evaluate and award gamification outcomes after a confirmed session

Call this endpoint once per confirmed session. Duplicate calls for the same session return the previously computed result without modifying state.

Request body

{
  "sessionId": "sess_001",
  "testerId": "user_xyz789",
  "signals": {
    "sessionCompleted": true,
    "businessRating": 5,
    "thinkAloudScore": 0.85,
    "completedOnTime": true,
    "previousStreakCount": 4
  }
}

Field	Type	Required	Description
sessionId	string	Yes	ID of the confirmed session
testerId	string	Yes	Tester to evaluate
signals.sessionCompleted	boolean	Yes	Whether the session was marked complete
signals.businessRating	integer (1-5)	Yes	Rating given by the business
signals.thinkAloudScore	number (0-1)	No	AI-assessed narration quality
signals.completedOnTime	boolean	No	Whether the session finished before the study deadline
signals.previousStreakCount	integer	No	Number of consecutive completed sessions before this one

Response

{
  "success": true,
  "data": {
    "testerId": "user_xyz789",
    "sessionId": "sess_001",
    "pointsAwarded": 110,
    "pointsBreakdown": {
      "sessionCompleted": 50,
      "businessRating": 30,
      "thinkAloudScore": 15,
      "completedOnTime": 10,
      "streakBonus": 5
    },
    "newTotalPoints": 1340,
    "previousLevel": 2,
    "currentLevel": 3,
    "leveledUp": true,
    "badgesAwarded": [
      {
        "badgeId": "badge_streak_5",
        "name": "5-Session Streak",
        "description": "Completed 5 sessions in a row without missing a deadline.",
        "iconUrl": "https://openscouter.com/badges/streak-5.png",
        "awardedAt": "2026-03-16T12:05:00Z"
      }
    ],
    "nextLevelThreshold": 1500,
    "pointsToNextLevel": 160
  },
  "error": null,
  "metadata": null
}

badgesAwarded is an empty array if no new badges were earned.

leveledUp triggers a notification to the tester automatically. No additional call is needed.