> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```http theme={"dark"}
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

```json theme={"dark"}
{
  "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         |