Skip to content

Add API reference for onboarding, gamification, and notifications #299

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 2 commits into
base: main
Choose a base branch
from
Open

Add API reference for onboarding, gamification, and notifications #299

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f89014d
Add API reference for onboarding, gamification, and notifications
mintlify[bot] Apr 4, 2026
ca3b395
Merge branch 'main' into mintlify/api-engagement-1775279094
Eskyee Apr 25, 2026
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
204 changes: 204 additions & 0 deletions api-reference/notifications.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
---
title: Notifications API
description: "In-app notification system for badges, referrals, achievements, and system events"
---
Comment on lines +1 to +4
Copy link
Copy Markdown

@devin-ai-integration devin-ai-integration Bot Apr 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 New documentation pages not added to docs.json navigation

The new pages api-reference/notifications.mdx and api-reference/onboarding.mdx are created but not registered in the docs.json navigation configuration (docs.json:96-183). Mintlify uses this configuration to build the sidebar navigation. Without entries for "api-reference/onboarding" and "api-reference/notifications" in the pages array of the "API Reference" group, these pages will be orphaned — they exist on the site but users cannot discover them through the sidebar. They would only be reachable via direct URL or internal links from other pages.

Prompt for agents 
The new pages api-reference/notifications.mdx and api-reference/onboarding.mdx need to be added to the navigation in docs.json. In docs.json, find the "API Reference" group (around line 95-183) and add "api-reference/onboarding" and "api-reference/notifications" to the pages array. A logical placement would be near the existing related pages like api-reference/referrals and api-reference/gamification (around line 156-157). For example, add them as: "api-reference/onboarding", "api-reference/notifications" after the gamification entry.
Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.


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

<Info>The notification endpoints are available on the web API. All endpoints require session authentication.</Info>

## 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..." |

<Note>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.</Note>
160 changes: 160 additions & 0 deletions api-reference/onboarding.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<Info>The onboarding endpoints are available on the web API. All endpoints require session authentication.</Info>

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

<Note>Onboarding progress is stored in the `UserSettings` table using keys prefixed with `onboarding_step_` and `onboarding_completed`. Completion status persists across sessions.</Note>
12 changes: 12 additions & 0 deletions api-reference/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,6 +290,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`) |
Expand Down