Gamification API

Retrieve your gamification profile including badges, points, level, leaderboard rank, and login streak

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

Field	Type	Description
badges	array	Badges the user has earned
badges[].id	string	Unique badge identifier
badges[].name	string	Display name of the badge
badges[].description	string	Description of how to earn the badge
badges[].icon	string	Emoji icon for the badge
badges[].category	string	Badge category: onboarding, usage, social, or achievement
badges[].points	number	Points awarded when the badge is earned
badges[].condition	string	Human-readable condition to earn the badge
points	number	User’s total accumulated points
level	number	Current level (1–7)
title	string	Level title: Newcomer, Beginner, Intermediate, Advanced, Expert, Master, or Legend
nextLevel	number	Points threshold required to reach the next level
progress	number	Percentage progress toward the next level (0–100)
streak	number	Current consecutive daily login streak
badgeAwarded	string | null	Badge ID if a streak badge was just awarded on this request, or null
leaderboard	array	Top 5 users by points
leaderboard[].userId	string	User ID
leaderboard[].name	string	User display name, or Anonymous if not set
leaderboard[].points	number	User’s total points
leaderboard[].level	number	User’s current level
leaderboard[].title	string	User’s level title
userRank	number | null	Authenticated user’s rank on the leaderboard (1-indexed), or null if not in the top 10
availableBadges	array	Badges the user has not yet earned. Same shape as badges.

Level thresholds

Level	Title	Points required
1	Newcomer	0
2	Beginner	100
3	Intermediate	500
4	Advanced	1,000
5	Expert	2,500
6	Master	5,000
7	Legend	10,000

Available badges

ID	Name	Category	Points	Condition
onboarding_complete	Getting Started	onboarding	100	Complete all onboarding steps
first_agent	Agent Creator	onboarding	50	Create 1 agent
message_100	Century Club	usage	100	Send 100 messages
message_1000	Message Master	usage	500	Send 1,000 messages
agent_3	Agent Army	usage	150	Create 3 agents
agent_10	Agent Overlord	usage	500	Create 10 agents
first_referral	Referrer	social	100	Refer 1 user
referral_5	Influencer	social	500	Refer 5 users
login_streak_7	Week Warrior	achievement	200	Login 7 days in a row
login_streak_30	Monthly Master	achievement	1,000	Login 30 days in a row
early_adopter	Early Adopter	achievement	500	Joined during beta

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed to fetch profile