From 5802a284e0e1abf33a6ee026b893a94d4285527e Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Sat, 4 Apr 2026 05:13:12 +0000
Subject: [PATCH] Add gamification API reference page
Generated-By: mintlify-agent
---
api-reference/gamification.mdx | 172 +++++++++++++++++++++++++++++++++
api-reference/overview.mdx | 1 +
docs.json | 1 +
3 files changed, 174 insertions(+)
create mode 100644 api-reference/gamification.mdx
diff --git a/api-reference/gamification.mdx b/api-reference/gamification.mdx
new file mode 100644
index 0000000..3086fdb
--- /dev/null
+++ b/api-reference/gamification.mdx
@@ -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.
+
+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.
+
+The gamification profile is also related to the [referrals API](/api-reference/referrals). Referring users earns the "Referrer" and "Influencer" badges.
diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx
index 9b6af5a..fa5133e 100644
--- a/api-reference/overview.mdx
+++ b/api-reference/overview.mdx
@@ -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 |
diff --git a/docs.json b/docs.json
index cd48165..2d5d48d 100644
--- a/docs.json
+++ b/docs.json
@@ -145,6 +145,7 @@
"api-reference/export",
"api-reference/wallet-monitor",
"api-reference/market-intel",
+ "api-reference/gamification",
"api-reference/referrals"
]
},