Skip to content

Add gamification API reference #300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add gamification API reference #300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 172 additions & 0 deletions api-reference/gamification.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
---
title: Gamification API
description: "Retrieve your gamification profile including badges, points, level, leaderboard position, and login streak"
---

# Gamification API

Retrieve your gamification profile. The response includes earned badges, total points, current level, leaderboard ranking, and login streak data. Viewing your profile also updates your daily login streak automatically.

## Get gamification profile

```http
GET /api/gamification/profile
```

Requires session authentication. Returns the authenticated user's gamification data including badges, points, level progression, leaderboard position, and login streak.

### Headers

| Header | Value | Required |
|--------|-------|----------|
| `Cookie` | Session cookie | Yes |

### Response

```json
{
"badges": [
{
"id": "first_agent",
"name": "Agent Creator",
"description": "Create your first AI agent",
"icon": "🤖",
"category": "onboarding",
"points": 50,
"condition": "Create 1 agent"
}
],
"points": 250,
"level": 3,
"title": "Intermediate",
"nextLevel": 1000,
"progress": 25,
"streak": 5,
"badgeAwarded": null,
"leaderboard": [
{
"userId": "user_abc",
"name": "Alice",
"points": 3200,
"level": 5,
"title": "Expert"
}
],
"userRank": 12,
"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 | List of badges the user has earned. |
| `badges[].id` | string | Unique badge identifier. |
| `badges[].name` | string | Display name of the badge. |
| `badges[].description` | string | What the badge represents. |
| `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 description of how to earn the badge. |
| `points` | number | Total accumulated points. |
| `level` | number | Current level (1–7). |
| `title` | string | Level title (for example "Newcomer", "Expert"). |
| `nextLevel` | number | Points 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, otherwise `null`. |
| `leaderboard` | array | Top 5 users by points. |
| `leaderboard[].userId` | string | User identifier. |
| `leaderboard[].name` | string | Display name. |
| `leaderboard[].points` | number | Total points. |
| `leaderboard[].level` | number | Current level. |
| `leaderboard[].title` | string | Level title. |
| `userRank` | number \| null | Your position on the leaderboard, or `null` if not ranked. |
| `availableBadges` | array | Badges the user has not yet earned. Same shape as `badges`. |

### Errors

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

### Example

```bash
curl -X GET https://agentbot.sh/api/gamification/profile \
-H "Cookie: next-auth.session-token=YOUR_SESSION"
```

## Badges

There are 10 badges across four categories.

### Onboarding

| Badge | Points | Condition |
|-------|--------|-----------|
| Getting Started | 100 | Complete the onboarding process |
| Agent Creator | 50 | Create your first agent |

### Usage

| Badge | Points | Condition |
|-------|--------|-----------|
| Century Club | 100 | Send 100 messages through your agents |
| Message Master | 500 | Send 1,000 messages through your agents |
| Agent Army | 150 | Create 3 agents |
| Agent Overlord | 500 | Create 10 agents |

### Social

| Badge | Points | Condition |
|-------|--------|-----------|
| Referrer | 100 | Refer your first user |
| Influencer | 500 | Refer 5 users |

### Achievement

| Badge | Points | Condition |
|-------|--------|-----------|
| Week Warrior | 200 | Login 7 days in a row |
| Monthly Master | 1,000 | Login 30 days in a row |
| Early Adopter | 500 | Joined during beta |

## Levels

Points determine your level. Earning badges and completing actions award points.

| 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 |

## Login streaks

Your login streak increments each consecutive day you view your gamification profile. If you miss a day, the streak resets to 1. Streak milestones automatically award badges:

- **7-day streak** — "Week Warrior" badge (200 points)
- **30-day streak** — "Monthly Master" badge (1,000 points)

When a streak badge is awarded, the `badgeAwarded` field in the response contains the badge ID.

<Note>Badges are awarded automatically based on your activity. You do not need to claim them manually. Points from badges are added to your total immediately.</Note>

<Note>The gamification profile is also related to the [referrals API](/api-reference/referrals). Referring users earns the "Referrer" and "Influencer" badges.</Note>
1 change: 1 addition & 0 deletions api-reference/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,7 @@ curl -X POST https://agentbot.sh/api/ai/chat \
| `/api/dashboard/cost` | GET | Get aggregated cost dashboard data (by agent, model, and day) |
| `/api/dashboard/health` | GET | Get health status of backend services (no auth) |
| `/api/dashboard/stats` | GET | Get dashboard stats (agent counts, skills, tasks) |
| `/api/gamification/profile` | GET | Get gamification profile (badges, points, level, leaderboard, login streak) |
| `/api/referrals` | GET | Get referral data, statistics, and referral link (session auth) |
| `/api/stats` | GET | Get system stats (CPU, memory, uptime, health, deployment info) |
| `/api/billing` | GET | Get billing info |
Expand Down
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,7 @@
"api-reference/export",
"api-reference/wallet-monitor",
"api-reference/market-intel",
"api-reference/gamification",
"api-reference/referrals"
]
},
Expand Down