Skip to main content

Gamification API

Retrieve your gamification profile, earned badges, points, level progression, and leaderboard position.

Get gamification profile

GET /api/gamification/profile
Requires session authentication. Returns the authenticated user’s badges, points, level, leaderboard rank, login streak, and available badges to earn. Each request automatically updates the user’s daily login streak.

Response

{
  "badges": [
    {
      "id": "first_agent",
      "name": "Agent Creator",
      "description": "Create your first AI agent",
      "icon": "🤖",
      "category": "onboarding",
      "points": 50,
      "condition": "Create 1 agent"
    }
  ],
  "points": 150,
  "level": 2,
  "title": "Beginner",
  "nextLevel": 500,
  "progress": 30,
  "streak": 3,
  "badgeAwarded": null,
  "leaderboard": [
    {
      "userId": "user_abc",
      "name": "Alice",
      "points": 2500,
      "level": 5,
      "title": "Expert"
    }
  ],
  "userRank": 4,
  "availableBadges": [
    {
      "id": "message_100",
      "name": "Century Club",
      "description": "Send 100 messages through your agents",
      "icon": "💬",
      "category": "usage",
      "points": 100,
      "condition": "100 messages"
    }
  ]
}

Response fields

FieldTypeDescription
badgesarrayBadges the user has earned
badges[].idstringUnique badge identifier
badges[].namestringDisplay name of the badge
badges[].descriptionstringDescription of how to earn the badge
badges[].iconstringEmoji icon for the badge
badges[].categorystringBadge category: onboarding, usage, social, or achievement
badges[].pointsnumberPoints awarded when the badge is earned
badges[].conditionstringHuman-readable condition to earn the badge
pointsnumberUser’s total accumulated points
levelnumberCurrent level (1–7)
titlestringLevel title: Newcomer, Beginner, Intermediate, Advanced, Expert, Master, or Legend
nextLevelnumberPoints threshold required to reach the next level
progressnumberPercentage progress toward the next level (0–100)
streaknumberCurrent consecutive daily login streak
badgeAwardedstring | nullBadge ID if a streak badge was just awarded on this request, or null
leaderboardarrayTop 5 users by points
leaderboard[].userIdstringUser ID
leaderboard[].namestringUser display name, or Anonymous if not set
leaderboard[].pointsnumberUser’s total points
leaderboard[].levelnumberUser’s current level
leaderboard[].titlestringUser’s level title
userRanknumber | nullAuthenticated user’s rank on the leaderboard (1-indexed), or null if not in the top 10
availableBadgesarrayBadges the user has not yet earned. Same shape as badges.

Level thresholds

LevelTitlePoints required
1Newcomer0
2Beginner100
3Intermediate500
4Advanced1,000
5Expert2,500
6Master5,000
7Legend10,000

Available badges

IDNameCategoryPointsCondition
onboarding_completeGetting Startedonboarding100Complete all onboarding steps
first_agentAgent Creatoronboarding50Create 1 agent
message_100Century Clubusage100Send 100 messages
message_1000Message Masterusage500Send 1,000 messages
agent_3Agent Armyusage150Create 3 agents
agent_10Agent Overlordusage500Create 10 agents
first_referralReferrersocial100Refer 1 user
referral_5Influencersocial500Refer 5 users
login_streak_7Week Warriorachievement200Login 7 days in a row
login_streak_30Monthly Masterachievement1,000Login 30 days in a row
early_adopterEarly Adopterachievement500Joined during beta

Errors

CodeDescription
401Unauthorized — no valid session
500Failed to fetch profile