From 846c513e233bdac7b9b8436aa97610328c4e1818 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 25 Feb 2026 07:49:49 -0500 Subject: [PATCH 1/8] docs: add POST /api/notifications endpoint Add notification email endpoint documentation following the send_email MCP tool definition. Supports to, cc, subject, text (Markdown), html, custom headers, and room_id for chat footer links. Co-Authored-By: Claude Opus 4.6 --- api-reference/notifications/create.mdx | 4 + api-reference/openapi.json | 128 +++++++++++++++++++++++++ docs.json | 6 ++ 3 files changed, 138 insertions(+) create mode 100644 api-reference/notifications/create.mdx diff --git a/api-reference/notifications/create.mdx b/api-reference/notifications/create.mdx new file mode 100644 index 00000000..664176cb --- /dev/null +++ b/api-reference/notifications/create.mdx @@ -0,0 +1,4 @@ +--- +title: 'Send Notification' +openapi: 'POST /api/notifications' +--- diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 9b5e51c9..9342a648 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -3785,6 +3785,64 @@ } } } + }, + "/api/notifications": { + "post": { + "description": "Send a notification email using the Resend API. Emails are sent from `Agent by Recoup `. 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,76 @@ } } }, + "CreateNotificationRequest": { + "type": "object", + "required": ["to", "subject"], + "properties": { + "to": { + "type": "array", + "items": { + "type": "string", + "format": "email" + }, + "description": "Recipient email addresses", + "example": ["user@example.com"] + }, + "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": "

Pulse Report

Here's your weekly summary.

" + }, + "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 to user@example.com." + }, + "id": { + "type": "string", + "description": "Resend email ID", + "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + } + } + }, "ConnectorInfo": { "type": "object", "required": ["slug", "name", "isConnected"], diff --git a/docs.json b/docs.json index 85631a97..acd393c1 100644 --- a/docs.json +++ b/docs.json @@ -193,6 +193,12 @@ "api-reference/subscriptions/get" ] }, + { + "group": "Notifications", + "pages": [ + "api-reference/notifications/create" + ] + }, { "group": "Apify", "pages": [ From 0f47d750164948850f3ab0d6d682ad437cbce6da Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 25 Feb 2026 07:56:32 -0500 Subject: [PATCH 2/8] docs: remove to param, auto-resolve recipient from auth The recipient email is now automatically resolved from the authenticated account's API key or Bearer token. Co-Authored-By: Claude Opus 4.6 --- api-reference/openapi.json | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 9342a648..b6065de2 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -3788,7 +3788,7 @@ }, "/api/notifications": { "post": { - "description": "Send a notification email using the Resend API. Emails are sent from `Agent by Recoup `. 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.", + "description": "Send a notification email to the authenticated account's email address via the Resend API. Emails are sent from `Agent by Recoup `. 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, @@ -3865,17 +3865,8 @@ }, "CreateNotificationRequest": { "type": "object", - "required": ["to", "subject"], + "required": ["subject"], "properties": { - "to": { - "type": "array", - "items": { - "type": "string", - "format": "email" - }, - "description": "Recipient email addresses", - "example": ["user@example.com"] - }, "cc": { "type": "array", "items": { From 7140ef1e664f55396f403ad69d730f55f471ca3b Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 25 Feb 2026 08:09:35 -0500 Subject: [PATCH 3/8] docs: add SDK tab with CLI notifications command reference First SDK/CLI documentation page. Documents the notifications command usage, options, examples, and its API equivalent. Co-Authored-By: Claude Opus 4.6 --- docs.json | 11 +++++++++ sdk.mdx | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 sdk.mdx diff --git a/docs.json b/docs.json index acd393c1..9f387c5d 100644 --- a/docs.json +++ b/docs.json @@ -23,6 +23,17 @@ } ] }, + { + "tab": "SDK", + "groups": [ + { + "group": "CLI", + "pages": [ + "sdk" + ] + } + ] + }, { "tab": "API reference", "groups": [ diff --git a/sdk.mdx b/sdk.mdx new file mode 100644 index 00000000..6509cceb --- /dev/null +++ b/sdk.mdx @@ -0,0 +1,68 @@ +--- +title: "CLI" +description: "Send notifications and interact with the Recoup API from the command line." +--- + +The Recoup CLI is built into the [interactive terminal](https://bash.recoupable.com) and is available to agents running inside sandboxes. It provides commands that wrap the Recoup API, so agents can perform actions like sending emails without needing direct API access. + +## notifications + +Send a notification email to the authenticated account's email address. The recipient is automatically resolved from your credentials — no need to specify a `to` address. + +Emails are sent from `Agent by Recoup `. + +### Usage + +```bash +notifications --subject [options] +``` + +### Options + +| Flag | Required | Description | +|------|----------|-------------| +| `--subject ` | Yes | Email subject line | +| `--text ` | No | Plain text or Markdown body (rendered as HTML) | +| `--html ` | No | Raw HTML body (takes precedence over `--text`) | +| `--cc ` | No | CC recipient (can be repeated for multiple) | +| `--room-id ` | No | Room ID to include a chat link in the email footer | + +### Examples + +**Send a simple notification:** + +```bash +notifications --subject "Pulse Report" --text "Here's your weekly summary." +``` + +**Send with Markdown formatting:** + +```bash +notifications --subject "Weekly Update" --text "# Artist Highlights\n\n- **BVB**: Release planning active\n- **sweetman.eth**: nounish EP targeting Jul 4" +``` + +**Send with CC recipients:** + +```bash +notifications --subject "Team Update" --cc manager@example.com --cc team@example.com --text "New release scheduled." +``` + +**Send with a room link in the footer:** + +```bash +notifications --subject "Conversation Follow-up" --text "Check the latest updates." --room-id "abc-123-def" +``` + +### API equivalent + +The `notifications` command is a wrapper around [`POST /api/notifications`](/api-reference/notifications/create). You can also call the API directly: + +```bash +curl -X POST "https://api.recoupable.com/api/notifications" \ + -H "Content-Type: application/json" \ + -H "x-api-key: YOUR_API_KEY" \ + -d '{ + "subject": "Pulse Report", + "text": "Here'\''s your weekly summary." + }' +``` From e74420ab65f6623edf8f11bcf304bf902f754e02 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 25 Feb 2026 08:13:47 -0500 Subject: [PATCH 4/8] docs: move SDK page into Guides tab after quickstart Co-Authored-By: Claude Opus 4.6 --- docs.json | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs.json b/docs.json index 9f387c5d..d5788387 100644 --- a/docs.json +++ b/docs.json @@ -18,22 +18,12 @@ "pages": [ "index", "quickstart", + "sdk", "api-reference/sandboxes/create" ] } ] }, - { - "tab": "SDK", - "groups": [ - { - "group": "CLI", - "pages": [ - "sdk" - ] - } - ] - }, { "tab": "API reference", "groups": [ From 3ccc320a9697a74d2b789c26658ebe5e8602f17c Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 25 Feb 2026 08:16:01 -0500 Subject: [PATCH 5/8] docs: rewrite CLI page with install instructions and all commands Document the @recoupable/cli package with installation, auth setup, and headings for all commands: whoami, artists, chats, sandboxes, orgs, and notifications. Co-Authored-By: Claude Opus 4.6 --- sdk.mdx | 104 ++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 71 insertions(+), 33 deletions(-) diff --git a/sdk.mdx b/sdk.mdx index 6509cceb..a5910871 100644 --- a/sdk.mdx +++ b/sdk.mdx @@ -1,68 +1,106 @@ --- title: "CLI" -description: "Send notifications and interact with the Recoup API from the command line." +description: "Install and use the Recoup CLI to interact with the platform from your terminal." --- -The Recoup CLI is built into the [interactive terminal](https://bash.recoupable.com) and is available to agents running inside sandboxes. It provides commands that wrap the Recoup API, so agents can perform actions like sending emails without needing direct API access. +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. -## notifications +## Installation -Send a notification email to the authenticated account's email address. The recipient is automatically resolved from your credentials — no need to specify a `to` address. +```bash +npm install -g @recoupable/cli +``` -Emails are sent from `Agent by Recoup `. +## Authentication -### Usage +Set your API key as an environment variable. You can get a key from the [API Keys page](https://chat.recoupable.com/keys). ```bash -notifications --subject [options] +export RECOUP_API_KEY=your-api-key ``` -### Options +Verify it works: -| Flag | Required | Description | -|------|----------|-------------| -| `--subject ` | Yes | Email subject line | -| `--text ` | No | Plain text or Markdown body (rendered as HTML) | -| `--html ` | No | Raw HTML body (takes precedence over `--text`) | -| `--cc ` | No | CC recipient (can be repeated for multiple) | -| `--room-id ` | No | Room ID to include a chat link in the email footer | +```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 | -### Examples +All commands support `--json` for machine-readable output and `--help` for usage info. -**Send a simple notification:** +## whoami + +Show the authenticated account. ```bash -notifications --subject "Pulse Report" --text "Here's your weekly summary." +recoup whoami +recoup whoami --json ``` -**Send with Markdown formatting:** +## artists + +Manage artists. ```bash -notifications --subject "Weekly Update" --text "# Artist Highlights\n\n- **BVB**: Release planning active\n- **sweetman.eth**: nounish EP targeting Jul 4" +recoup artists list +recoup artists list --org +recoup artists list --account +recoup artists list --json ``` -**Send with CC recipients:** +## chats + +Manage chats. ```bash -notifications --subject "Team Update" --cc manager@example.com --cc team@example.com --text "New release scheduled." +recoup chats list +recoup chats create --name "My Topic" +recoup chats create --name "My Topic" --artist +recoup chats list --json ``` -**Send with a room link in the footer:** +## sandboxes + +Manage sandboxes. ```bash -notifications --subject "Conversation Follow-up" --text "Check the latest updates." --room-id "abc-123-def" +recoup sandboxes list +recoup sandboxes create +recoup sandboxes create --command "ls -la" +recoup sandboxes list --json ``` -### API equivalent +## orgs + +Manage organizations. + +```bash +recoup orgs list +recoup orgs list --account +recoup orgs list --json +``` + +## notifications -The `notifications` command is a wrapper around [`POST /api/notifications`](/api-reference/notifications/create). You can also call the API directly: +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 -curl -X POST "https://api.recoupable.com/api/notifications" \ - -H "Content-Type: application/json" \ - -H "x-api-key: YOUR_API_KEY" \ - -d '{ - "subject": "Pulse Report", - "text": "Here'\''s your weekly summary." - }' +recoup notifications --subject "Pulse Report" --text "Here's your weekly summary." +recoup notifications --subject "Update" --cc manager@example.com --text "New release scheduled." ``` + +| Flag | Required | Description | +|------|----------|-------------| +| `--subject ` | Yes | Email subject line | +| `--text ` | No | Plain text or Markdown body (rendered as HTML) | +| `--html ` | No | Raw HTML body (takes precedence over `--text`) | +| `--cc ` | No | CC recipient (repeatable) | +| `--room-id ` | No | Room ID for a chat link in the email footer | + +This command wraps [`POST /api/notifications`](/api-reference/notifications/create). From c1cf4d026dd8e6cf347c66eceab634076e095142 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 25 Feb 2026 08:18:03 -0500 Subject: [PATCH 6/8] docs: add API endpoint links to each CLI command Co-Authored-By: Claude Opus 4.6 --- sdk.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sdk.mdx b/sdk.mdx index a5910871..316cf6ae 100644 --- a/sdk.mdx +++ b/sdk.mdx @@ -36,7 +36,7 @@ All commands support `--json` for machine-readable output and `--help` for usage ## whoami -Show the authenticated account. +Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id). ```bash recoup whoami @@ -45,7 +45,7 @@ recoup whoami --json ## artists -Manage artists. +Manage artists. See [`GET /api/artists`](/api-reference/artists/list). ```bash recoup artists list @@ -56,7 +56,7 @@ recoup artists list --json ## chats -Manage chats. +Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create). ```bash recoup chats list @@ -67,7 +67,7 @@ recoup chats list --json ## sandboxes -Manage sandboxes. +Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create). ```bash recoup sandboxes list @@ -78,7 +78,7 @@ recoup sandboxes list --json ## orgs -Manage organizations. +Manage organizations. See [`GET /api/organizations`](/api-reference/organizations/list). ```bash recoup orgs list From 40d7dd57741e3b4dd2fe1e85f50f7564f7d68d79 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 25 Feb 2026 08:18:54 -0500 Subject: [PATCH 7/8] docs: add html flag example to notifications command Co-Authored-By: Claude Opus 4.6 --- sdk.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/sdk.mdx b/sdk.mdx index 316cf6ae..fb6c2135 100644 --- a/sdk.mdx +++ b/sdk.mdx @@ -93,6 +93,7 @@ Send a notification email to the authenticated account's email address. The reci ```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 "

Pulse Report

BVB release planning is active.

" ``` | Flag | Required | Description | From df41713a91c05754a7c3b857883719ef9fa5176c Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 25 Feb 2026 08:20:04 -0500 Subject: [PATCH 8/8] =?UTF-8?q?docs:=20reorder=20CLI=20commands=20?= =?UTF-8?q?=E2=80=94=20orgs,=20artists,=20notifications=20first?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- sdk.mdx | 60 ++++++++++++++++++++++++++++----------------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/sdk.mdx b/sdk.mdx index fb6c2135..8ee5a0d9 100644 --- a/sdk.mdx +++ b/sdk.mdx @@ -43,6 +43,16 @@ recoup whoami recoup whoami --json ``` +## orgs + +Manage organizations. See [`GET /api/organizations`](/api-reference/organizations/list). + +```bash +recoup orgs list +recoup orgs list --account +recoup orgs list --json +``` + ## artists Manage artists. See [`GET /api/artists`](/api-reference/artists/list). @@ -54,6 +64,26 @@ recoup artists list --account 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 "

Pulse Report

BVB release planning is active.

" +``` + +| Flag | Required | Description | +|------|----------|-------------| +| `--subject ` | Yes | Email subject line | +| `--text ` | No | Plain text or Markdown body (rendered as HTML) | +| `--html ` | No | Raw HTML body (takes precedence over `--text`) | +| `--cc ` | No | CC recipient (repeatable) | +| `--room-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). @@ -75,33 +105,3 @@ recoup sandboxes create recoup sandboxes create --command "ls -la" recoup sandboxes list --json ``` - -## orgs - -Manage organizations. See [`GET /api/organizations`](/api-reference/organizations/list). - -```bash -recoup orgs list -recoup orgs list --account -recoup orgs 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 "

Pulse Report

BVB release planning is active.

" -``` - -| Flag | Required | Description | -|------|----------|-------------| -| `--subject ` | Yes | Email subject line | -| `--text ` | No | Plain text or Markdown body (rendered as HTML) | -| `--html ` | No | Raw HTML body (takes precedence over `--text`) | -| `--cc ` | No | CC recipient (repeatable) | -| `--room-id ` | No | Room ID for a chat link in the email footer | - -This command wraps [`POST /api/notifications`](/api-reference/notifications/create).