Gamification API
Retrieve your gamification profile, earned badges, points, level progression, and leaderboard position.Get gamification profile
Response
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 |