docs: add POST /api/notifications endpoint

api-reference/notifications/create.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Send Notification'
+openapi: 'POST /api/notifications'
+---

api-reference/openapi.json

@@ -3785,6 +3785,64 @@
           }
         }
       }
+    },
+    "/api/notifications": {
+      "post": {
+        "description": "Send a notification email to the authenticated account's email address via the Resend API. Emails are sent from `Agent by Recoup <agent@recoupable.com>`. The recipient is automatically resolved from the API key or Bearer token. Supports plain text (rendered as Markdown) or raw HTML bodies, optional CC recipients, custom headers, and an optional room_id to include a chat link in the email footer.",
+        "requestBody": {
+          "description": "Notification email payload",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateNotificationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Notification sent successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/NotificationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "502": {
+            "description": "Email delivery failed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -3805,6 +3863,67 @@
           }
         }
       },
+      "CreateNotificationRequest": {
+        "type": "object",
+        "required": ["subject"],
+        "properties": {
+          "cc": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Optional CC email addresses",
+            "example": ["cc@example.com"]
+          },
+          "subject": {
+            "type": "string",
+            "description": "Email subject line",
+            "example": "Weekly Pulse Report"
+          },
+          "text": {
+            "type": "string",
+            "description": "Plain text or Markdown body. Rendered as HTML via Markdown if no `html` is provided.",
+            "example": "# Pulse Report\n\nHere's your weekly summary."
+          },
+          "html": {
+            "type": "string",
+            "description": "Raw HTML body. Takes precedence over `text` when both are provided.",
+            "example": "<h1>Pulse Report</h1><p>Here's your weekly summary.</p>"
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Optional custom email headers"
+          },
+          "room_id": {
+            "type": "string",
+            "description": "Room ID to include a chat link in the email footer"
+          }
+        }
+      },
+      "NotificationResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Whether the notification was sent successfully",
+            "example": true
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable result message",
+            "example": "Email sent successfully from Agent by Recoup <agent@recoupable.com> to user@example.com."
+          },
+          "id": {
+            "type": "string",
+            "description": "Resend email ID",
+            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+          }
+        }
+      },
       "ConnectorInfo": {
         "type": "object",
         "required": ["slug", "name", "isConnected"],

docs.json

@@ -18,6 +18,7 @@
             "pages": [
               "index",
               "quickstart",
+              "sdk",
               "api-reference/sandboxes/create"
             ]
           }
@@ -193,6 +194,12 @@
               "api-reference/subscriptions/get"
             ]
           },
+          {
+            "group": "Notifications",
+            "pages": [
+              "api-reference/notifications/create"
+            ]
+          },
           {
             "group": "Apify",
             "pages": [

sdk.mdx

@@ -0,0 +1,107 @@
+---
+title: "CLI"
+description: "Install and use the Recoup CLI to interact with the platform from your terminal."
+---
+
+The Recoup CLI (`@recoupable/cli`) is a command-line wrapper around the Recoup API. It's available as a global npm package and is pre-installed in sandbox environments.
+
+## Installation
+
+```bash
+npm install -g @recoupable/cli
+```
+
+## Authentication
+
+Set your API key as an environment variable. You can get a key from the [API Keys page](https://chat.recoupable.com/keys).
+
+```bash
+export RECOUP_API_KEY=your-api-key
+```
+
+Verify it works:
+
+```bash
+recoup whoami
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `RECOUP_API_KEY` | Yes | — | Your Recoup API key |
+| `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override |
+
+All commands support `--json` for machine-readable output and `--help` for usage info.
+
+## whoami
+
+Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id).
+
+```bash
+recoup whoami
+recoup whoami --json
+```
+
+## orgs
+
+Manage organizations. See [`GET /api/organizations`](/api-reference/organizations/list).
+
+```bash
+recoup orgs list
+recoup orgs list --account <accountId>
+recoup orgs list --json
+```
+
+## artists
+
+Manage artists. See [`GET /api/artists`](/api-reference/artists/list).
+
+```bash
+recoup artists list
+recoup artists list --org <orgId>
+recoup artists list --account <accountId>
+recoup artists list --json
+```
+
+## notifications
+
+Send a notification email to the authenticated account's email address. The recipient is automatically resolved from your API key — no need to specify a `to` address.
+
+```bash
+recoup notifications --subject "Pulse Report" --text "Here's your weekly summary."
+recoup notifications --subject "Update" --cc manager@example.com --text "New release scheduled."
+recoup notifications --subject "Weekly Pulse" --html "<h1>Pulse Report</h1><p>BVB release planning is <strong>active</strong>.</p>"
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--subject <text>` | Yes | Email subject line |
+| `--text <body>` | No | Plain text or Markdown body (rendered as HTML) |
+| `--html <body>` | No | Raw HTML body (takes precedence over `--text`) |
+| `--cc <email>` | No | CC recipient (repeatable) |
+| `--room-id <id>` | No | Room ID for a chat link in the email footer |
+
+This command wraps [`POST /api/notifications`](/api-reference/notifications/create).
+
+## chats
+
+Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create).
+
+```bash
+recoup chats list
+recoup chats create --name "My Topic"
+recoup chats create --name "My Topic" --artist <artistId>
+recoup chats list --json
+```
+
+## sandboxes
+
+Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create).
+
+```bash
+recoup sandboxes list
+recoup sandboxes create
+recoup sandboxes create --command "ls -la"
+recoup sandboxes list --json
+```