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.
+
+<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>
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.
+
+<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>
diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx
index c26b916..b5fb708 100644
--- a/api-reference/overview.mdx
+++ b/api-reference/overview.mdx
@@ -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`) |