diff --git a/api-reference/gamification.mdx b/api-reference/gamification.mdx new file mode 100644 index 0000000..d6bafc4 --- /dev/null +++ b/api-reference/gamification.mdx @@ -0,0 +1,259 @@ +--- +title: Gamification API +description: "Points, badges, levels, login streaks, and leaderboard for user engagement" +--- + +# Gamification API + +The gamification system rewards users with points, badges, and levels based on platform activity. Badges are awarded automatically when conditions are met, and login streaks are tracked daily. + +The gamification endpoints are available on the web API. All endpoints require session authentication. + +## Get user badges + +```http +GET /api/gamification/badges +``` + +Returns all badges earned by the authenticated user. + +### Response + +```json +{ + "badges": [ + { + "id": "onboarding_complete", + "name": "Getting Started", + "description": "Complete the onboarding process", + "icon": "🚀", + "category": "onboarding", + "points": 100, + "condition": "Complete all onboarding steps" + }, + { + "id": "first_agent", + "name": "Agent Creator", + "description": "Create your first AI agent", + "icon": "🤖", + "category": "onboarding", + "points": 50, + "condition": "Create 1 agent" + } + ] +} +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `badges` | array | List of badges earned by the user | +| `badges[].id` | string | Unique badge identifier | +| `badges[].name` | string | Display name | +| `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 condition for earning the badge | + +### 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 through your agents | +| `message_1000` | Message Master | usage | 500 | Send 1,000 messages through your agents | +| `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 badges | + +--- + +## Get user points and level + +```http +GET /api/gamification/points +``` + +Returns the authenticated user's total points, current level, and progress toward the next level. + +### Response + +```json +{ + "points": 750, + "level": 3, + "title": "Intermediate", + "nextLevel": 1000 +} +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `points` | number | Total accumulated points | +| `level` | number | Current level (1–7) | +| `title` | string | Level title | +| `nextLevel` | number | Points required to reach the next level | + +### Level thresholds + +| Level | Title | Minimum points | +|-------|-------|---------------| +| 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 | + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — no valid session | +| 500 | Failed to fetch points | + +--- + +## Update login streak + +```http +POST /api/gamification/streak +``` + +Records a login event and updates the user's streak counter. Call this endpoint on each authenticated session start. If the user logged in on the previous calendar day, the streak increments. If more than one day has passed, the streak resets to 1. Same-day logins maintain the current streak without incrementing. + +When a streak reaches 7 or 30 days, the corresponding badge is awarded automatically. + +### Response + +```json +{ + "streak": 8, + "badgeAwarded": "login_streak_7" +} +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `streak` | number | Current login streak in consecutive days | +| `badgeAwarded` | string \| null | Badge ID if a streak milestone badge was awarded, otherwise `null` | + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — no valid session | +| 500 | Failed to update streak | + +--- + +## Check and award badges + +```http +POST /api/gamification/check +``` + +Evaluates the authenticated user's current activity and awards any badges whose conditions are now met. Returns a list of newly awarded badge IDs. This endpoint is idempotent — badges that were already awarded are not duplicated. + +Conditions checked: + +- Agent count (1, 3, or 10 agents) +- Referral count (1 or 5 referrals) + +### Response + +```json +{ + "awarded": ["agent_3", "first_referral"] +} +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `awarded` | string[] | List of badge IDs that were newly awarded. Empty array if no new badges were earned. | + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — no valid session | +| 500 | Failed to check badges | + +--- + +## Get leaderboard + +```http +GET /api/gamification/leaderboard +``` + +Returns the top users ranked by total points. No authentication required. + +### Query parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `limit` | integer | `10` | Number of users to return (maximum 50) | + +### Response + +```json +{ + "leaderboard": [ + { + "userId": "user_abc123", + "name": "Alice", + "points": 2500, + "level": 5, + "title": "Expert" + }, + { + "userId": "user_def456", + "name": "Bob", + "points": 1200, + "level": 4, + "title": "Advanced" + } + ] +} +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `leaderboard` | array | Users sorted by points descending | +| `leaderboard[].userId` | string | User identifier | +| `leaderboard[].name` | string | Display name (defaults to "Anonymous" if not set) | +| `leaderboard[].points` | number | Total accumulated points | +| `leaderboard[].level` | number | Current level | +| `leaderboard[].title` | string | Level title | + +### Errors + +| Code | Description | +|------|-------------| +| 500 | Failed to fetch leaderboard | + +Gamification data is stored in the `UserSettings` table using keys prefixed with `badge_`, `gamification_points`, `login_streak`, and `last_login`. Points accumulate from badge awards and cannot be spent or transferred. diff --git a/api-reference/notifications.mdx b/api-reference/notifications.mdx new file mode 100644 index 0000000..1508eca --- /dev/null +++ b/api-reference/notifications.mdx @@ -0,0 +1,204 @@ +--- +title: Notifications API +description: "In-app notification system for badges, referrals, achievements, and system events" +--- + +# Notifications API + +The notification system delivers in-app alerts for user engagement events including badge awards, referral conversions, level-ups, agent deployments, and login streak milestones. + +The notification endpoints are available on the web API. All endpoints require session authentication. + +## Get notifications + +```http +GET /api/notifications +``` + +Returns the authenticated user's notifications, ordered by creation date descending. + +### Query parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `unreadOnly` | boolean | `false` | When `true`, returns only unread notifications | +| `limit` | integer | `20` | Maximum number of notifications to return | + +### Response + +```json +{ + "notifications": [ + { + "id": "notif_abc123", + "userId": "user_xyz", + "type": "badge", + "title": "New Badge Earned!", + "message": "You earned the 🚀 Getting Started badge!", + "read": false, + "data": { + "badgeName": "Getting Started", + "badgeIcon": "🚀" + }, + "createdAt": "2026-04-04T06:00:00.000Z" + }, + { + "id": "notif_def456", + "userId": "user_xyz", + "type": "achievement", + "title": "Level Up!", + "message": "Congratulations! You reached Level 3 - Intermediate", + "read": true, + "data": { + "level": 3, + "title": "Intermediate" + }, + "createdAt": "2026-04-03T12:00:00.000Z" + } + ] +} +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `notifications` | array | List of notifications | +| `notifications[].id` | string | Unique notification identifier | +| `notifications[].userId` | string | User the notification belongs to | +| `notifications[].type` | string | Notification type (see types below) | +| `notifications[].title` | string | Notification headline | +| `notifications[].message` | string | Full notification message | +| `notifications[].read` | boolean | Whether the notification has been read | +| `notifications[].data` | object \| null | Type-specific metadata | +| `notifications[].createdAt` | string | ISO 8601 timestamp | + +### Notification types + +| Type | Description | Example trigger | +|------|-------------|----------------| +| `achievement` | Level-ups and streak milestones | Reaching a new level or login streak | +| `badge` | Badge awards | Earning a gamification badge | +| `referral` | Referral conversions | A referred user signing up | +| `system` | Platform announcements | Welcome-back messages after inactivity | +| `agent` | Agent lifecycle events | Agent deployed successfully | +| `message` | Message-related alerts | Message volume milestones | +| `billing` | Billing and subscription events | Subscription changes | + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — no valid session | +| 500 | Failed to fetch notifications | + +--- + +## Get unread count + +```http +GET /api/notifications/unread-count +``` + +Returns the count of unread notifications for the authenticated user. Use this endpoint to display a notification badge in the UI without fetching all notification data. + +### Response + +```json +{ + "count": 3 +} +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `count` | number | Number of unread notifications | + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — no valid session | +| 500 | Failed to fetch unread count | + +--- + +## Mark notification as read + +```http +POST /api/notifications/read +``` + +Marks a single notification as read. + +### Request body + +```json +{ + "notificationId": "notif_abc123" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `notificationId` | string | Yes | The notification ID to mark as read | + +### Response + +```json +{ + "success": true +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 400 | Missing `notificationId` | +| 401 | Unauthorized — no valid session | +| 500 | Failed to mark notification as read | + +--- + +## Mark all as read + +```http +POST /api/notifications/read-all +``` + +Marks all unread notifications as read for the authenticated user. + +### Response + +```json +{ + "success": true +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — no valid session | +| 500 | Failed to mark notifications as read | + +--- + +## Automatic notifications + +The following notifications are created automatically by the system when corresponding events occur. You do not need to call an endpoint to trigger them. + +| Event | Type | Title | Example message | +|-------|------|-------|-----------------| +| Badge awarded | `badge` | New Badge Earned! | "You earned the 🚀 Getting Started badge!" | +| Referral converted | `referral` | Referral Converted! | "Alice signed up using your referral link. You earned £10 credit!" | +| Level up | `achievement` | Level Up! | "Congratulations! You reached Level 3 - Intermediate" | +| Agent deployed | `agent` | Agent Deployed | "Your agent 'Atlas' is now live and ready to use!" | +| Login streak milestone | `achievement` | Login Streak! | "🔥 7 day login streak! Keep it up!" | +| Return after inactivity | `system` | Welcome Back! | "It's been 14 days! Here's what you missed..." | + +Return notifications are only sent when the user has been inactive for more than 7 days. Notifications older than 30 days that have been read are automatically cleaned up. diff --git a/api-reference/onboarding.mdx b/api-reference/onboarding.mdx new file mode 100644 index 0000000..cbf477f --- /dev/null +++ b/api-reference/onboarding.mdx @@ -0,0 +1,160 @@ +--- +title: Onboarding API +description: "Guided onboarding system for new users with step-by-step progress tracking" +--- + +# Onboarding API + +The onboarding system provides a guided first-time experience with seven steps that help new users set up their account and agents. + +The onboarding endpoints are available on the web API. All endpoints require session authentication. + +## Get onboarding progress + +```http +GET /api/onboarding +``` + +Returns the authenticated user's onboarding progress, including all steps and their completion status. Some steps are auto-completed based on user data (for example, the "Create Your First Agent" step completes automatically when you create an agent). + +### Response + +```json +{ + "userId": "user_abc123", + "completed": false, + "currentStep": 3, + "steps": [ + { + "id": "welcome", + "title": "Welcome to Agentbot", + "description": "Complete your profile and get familiar with the platform", + "action": "Get Started", + "link": "/settings", + "completed": true, + "order": 1 + }, + { + "id": "create_agent", + "title": "Create Your First Agent", + "description": "Build an AI agent that represents you or your brand", + "action": "Create Agent", + "link": "/dashboard/agents/new", + "completed": true, + "order": 2 + }, + { + "id": "deploy_agent", + "title": "Deploy Your Agent", + "description": "Launch your agent to the cloud and make it accessible", + "action": "Deploy", + "link": "/dashboard/deploy", + "completed": false, + "order": 3 + } + ], + "progress": 28 +} +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `userId` | string | The authenticated user's ID | +| `completed` | boolean | Whether all onboarding steps are finished or the user skipped onboarding | +| `currentStep` | number | The `order` value of the next incomplete step | +| `steps` | array | All onboarding steps with completion status | +| `steps[].id` | string | Unique step identifier | +| `steps[].title` | string | Display title for the step | +| `steps[].description` | string | Short description of what the step involves | +| `steps[].action` | string | Call-to-action label for the step button | +| `steps[].link` | string | URL path the user should visit to complete the step | +| `steps[].completed` | boolean | Whether the step is complete (manual or auto-detected) | +| `steps[].order` | number | Step position (1–7) | +| `progress` | number | Completion percentage from 0 to 100 | + +### Onboarding steps + +| Order | Step ID | Title | Auto-completes when | +|-------|---------|-------|---------------------| +| 1 | `welcome` | Welcome to Agentbot | User has set a display name | +| 2 | `create_agent` | Create Your First Agent | User has at least one agent | +| 3 | `deploy_agent` | Deploy Your Agent | User has at least one agent | +| 4 | `connect_platform` | Connect a Platform | Manually marked complete | +| 5 | `customize_personality` | Customize Personality | Manually marked complete | +| 6 | `invite_team` | Invite Your Team | Manually marked complete | +| 7 | `earn_rewards` | Start Earning Rewards | Manually marked complete | + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — no valid session | +| 404 | User not found | +| 500 | Failed to fetch onboarding progress | + +--- + +## Complete a step + +```http +POST /api/onboarding/complete +``` + +Marks an onboarding step as completed. When all seven steps are finished, the system automatically awards the "Getting Started" badge (see [gamification](/api-reference/gamification)). + +### Request body + +```json +{ + "stepId": "connect_platform" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `stepId` | string | Yes | The `id` of the step to mark as complete | + +### Response + +```json +{ + "success": true +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 400 | Invalid or missing `stepId` | +| 401 | Unauthorized — no valid session | +| 500 | Failed to complete step | + +--- + +## Skip onboarding + +```http +POST /api/onboarding/skip +``` + +Skips the onboarding flow entirely. The onboarding status is recorded as `skipped` rather than `completed`. Users can still complete individual steps later from their dashboard. + +### Response + +```json +{ + "success": true +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — no valid session | +| 500 | Failed to skip onboarding | + +Onboarding progress is stored in the `UserSettings` table using keys prefixed with `onboarding_step_` and `onboarding_completed`. Completion status persists across sessions. diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx index 9b6af5a..ce4d83b 100644 --- a/api-reference/overview.mdx +++ b/api-reference/overview.mdx @@ -260,6 +260,18 @@ curl -X POST https://agentbot.sh/api/ai/chat \ | `/api/dashboard/health` | GET | Get health status of backend services (no auth) | | `/api/dashboard/stats` | GET | Get dashboard stats (agent counts, skills, tasks) | | `/api/referrals` | GET | Get referral data, statistics, and referral link (session auth) | +| `/api/onboarding` | GET | Get onboarding progress and step completion status (session auth) | +| `/api/onboarding/complete` | POST | Mark an onboarding step as completed (session auth) | +| `/api/onboarding/skip` | POST | Skip the onboarding flow (session auth) | +| `/api/gamification/badges` | GET | Get badges earned by the authenticated user (session auth) | +| `/api/gamification/points` | GET | Get points, level, and progress toward next level (session auth) | +| `/api/gamification/streak` | POST | Record a login and update the streak counter (session auth) | +| `/api/gamification/check` | POST | Evaluate and award badges based on current activity (session auth) | +| `/api/gamification/leaderboard` | GET | Get top users ranked by points (no auth) | +| `/api/notifications` | GET | Get user notifications with optional unread filter (session auth) | +| `/api/notifications/unread-count` | GET | Get count of unread notifications (session auth) | +| `/api/notifications/read` | POST | Mark a notification as read (session auth) | +| `/api/notifications/read-all` | POST | Mark all notifications as read (session auth) | | `/api/stats` | GET | Get system stats (CPU, memory, uptime, health, deployment info) | | `/api/billing` | GET | Get billing info | | `/api/billing` | POST | Billing actions (`create-checkout`, `enable-byok`, `disable-byok`, `get-usage`, `buy-credits`) | diff --git a/docs.json b/docs.json index cd48165..47d56b8 100644 --- a/docs.json +++ b/docs.json @@ -145,7 +145,10 @@ "api-reference/export", "api-reference/wallet-monitor", "api-reference/market-intel", - "api-reference/referrals" + "api-reference/referrals", + "api-reference/onboarding", + "api-reference/gamification", + "api-reference/notifications" ] }, {