From 40e89066ef9b0ca8bd5ba26f221181296262edf4 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 21:52:45 -0400 Subject: [PATCH 01/13] =?UTF-8?q?docs:=20full=20overhaul=20=E2=80=94=20pos?= =?UTF-8?q?itioning,=20developer=20experience,=20and=20navigation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites all core pages to properly communicate what Recoup is (autonomous music infrastructure) and how to use it (API, MCP, CLI). Adds how-it-works concept page, authentication guide, and restructured navigation. Inspired by Composio docs quality bar. Voice follows brand guidelines. Made-with: Cursor --- api-reference/introduction.mdx | 115 +++++++++++------ authentication.mdx | 126 +++++++------------ cli.mdx | 207 ++++++++++++++++-------------- docs.json | 28 ++--- how-it-works.mdx | 102 +++++++++++++++ index.mdx | 145 +++++++++++++-------- mcp.mdx | 221 ++++++++++++++++++++++++++------- quickstart.mdx | 194 ++++++++++++++--------------- 8 files changed, 713 insertions(+), 425 deletions(-) create mode 100644 how-it-works.mdx diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 057216c..7e362f5 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,67 +1,108 @@ --- -title: 'Introduction' -description: 'API documentation for the Recoup platform - AI agents for the music industry' +title: 'API Reference' +description: 'Programmatic access to the Recoup platform — agents, artists, content, analytics, and tasks.' --- -## Welcome +The Recoup API is a REST API that gives you programmatic access to everything on the platform. Manage artists, create content, analyze audiences, run scheduled tasks, and integrate with Spotify, YouTube, Instagram, and more. -Welcome to the Recoup API documentation. Recoup is an AI agent platform for the music industry that provides artist analytics, fan segmentation, and AI-powered chat assistants. Build smarter song rollouts, create unforgettable fan experiences, and drive lasting artist growth. +## Base URL - - View the OpenAPI specification file on GitHub - +``` +https://api.recoupable.com/api +``` -## Base URL +## Authentication -All API requests should be made to: +All endpoints require an API key in the `x-api-key` header. ```bash -https://api.recoupable.com/api +curl -X GET "https://api.recoupable.com/api/artists" \ + -H "x-api-key: YOUR_API_KEY" ``` -## Authentication +Get your key from the [API Keys page](https://chat.recoupable.com/keys). Keys are shown once — store them securely. -All API endpoints are authenticated using an API key passed in the `x-api-key` header. + +Do not commit API keys to version control or share them publicly. + -### Getting Your API Key +## Response Format -1. Navigate to the [API Keys Management Page](https://chat.recoupable.com/keys) -2. Sign in with your account -3. Create a new API key and copy it immediately (it's only shown once) +All endpoints return JSON. Successful responses include a `status` field: -### Using Your API Key +```json +{ + "status": "success", + "data": { ... } +} +``` -Include your API key in the `x-api-key` header for all requests: +Error responses include a message: -```bash -curl -X GET "https://api.recoupable.com/api/artists?accountId=YOUR_ACCOUNT_ID" \ - -H "Content-Type: application/json" \ - -H "x-api-key: YOUR_API_KEY" +```json +{ + "status": "error", + "error": "Description of what went wrong" +} ``` - -Keep your API key secure. Do not share it publicly or commit it to version control. - +## Rate Limits -## Next Steps +API requests are subject to rate limiting. If you hit a limit, the response will include a `429` status code. Back off and retry with exponential backoff. + +## Other Integration Options + +The REST API is one of three ways to integrate with Recoup: + +| Method | Best For | Docs | +|--------|----------|------| +| **REST API** | Custom integrations, dashboards, automation | You're here | +| **MCP** | AI agents (Claude, Cursor, VS Code) | [MCP Guide](/mcp) | +| **CLI** | Terminal workflows, scripting, CI/CD | [CLI Guide](/cli) | + +## Explore - Get started with your first API request + AI conversations with artist context. - Explore all available endpoints + Manage artist profiles and social accounts. + + + Generate and manage AI-powered content. + + + Schedule and monitor background operations. + + + Search and analyze Spotify data. + + + Persistent agent execution environments. diff --git a/authentication.mdx b/authentication.mdx index c3f5019..95a8837 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -1,111 +1,81 @@ --- title: "Authentication" -description: "How authentication works in the Recoup API — API keys, access tokens, and organization access control." +description: "How to authenticate with the Recoup API, MCP server, and CLI." --- -## Overview +All Recoup services use API keys for authentication. One key works across the REST API, MCP server, and CLI. -Every request to the Recoup API must be authenticated using exactly one of two mechanisms: +## Get Your API Key -| Method | Header | Use case | -|--------|--------|----------| -| API Key | `x-api-key` | Server-to-server integrations | -| Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy | - -Providing both headers in the same request will result in a `401` error. - ---- - -## API Keys - -API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are **personal keys** — they are always tied to the account that created them. - -### Creating an API Key - -1. Navigate to [chat.recoupable.com/keys](https://chat.recoupable.com/keys) -2. Enter a descriptive name (e.g. `"Production Server"`) -3. Click **Create API Key** +1. Go to the [API Keys page](https://chat.recoupable.com/keys) +2. Sign in with your Recoup account +3. Click "Create API Key" and give it a name +4. Copy the key immediately — it's only shown once -Copy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation. +Store your API key securely. Do not commit it to version control, share it publicly, or include it in client-side code. -### Using an API Key +## Using Your Key + +### REST API Pass your key in the `x-api-key` header: ```bash -curl -X GET "https://api.recoupable.com/api/tasks" \ +curl -X GET "https://api.recoupable.com/api/artists" \ -H "x-api-key: YOUR_API_KEY" ``` -### Access to Organizations - -If your account belongs to one or more organizations, your API key can access data across those organizations by passing an `account_id` parameter on supported endpoints. This lets you filter to any account within an organization your key has access to. - -- **No org membership** — the key can only access its own account's data -- **Org member** — the key can pass `account_id` to filter to any account within that organization - - -Org membership is determined by the account's [organizations](/api-reference/organizations/list). An account gains access to an org when it is added as a member. - - ---- +### MCP Server + +Pass your key as a Bearer token in the `Authorization` header: + +```json +{ + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` -## Access Tokens (Privy) +### CLI -If you're building a frontend application that authenticates users via [Privy](https://privy.io), you can pass the user's Privy JWT as a Bearer token instead of an API key. +Set the `RECOUP_API_KEY` environment variable: ```bash -curl -X GET "https://api.recoupable.com/api/tasks" \ - -H "Authorization: Bearer YOUR_PRIVY_JWT" +export RECOUP_API_KEY=your-api-key +recoup whoami ``` -The API validates the token against Privy, extracts the user's email, and resolves it to the corresponding Recoup account. Bearer tokens always authenticate as a personal account — they cannot act on behalf of an organization. +## Key Types ---- +### Personal Keys -## How We Verify Access on API Calls +Personal API keys are tied to your account. They can access: -Every authenticated request goes through `validateAuthContext`, which enforces the following access rules: +- Your own data (artists, chats, tasks) +- Data from any organization you belong to (using `account_id` filtering) -### API Key or Bearer Token +### Organization Access -By default, requests access the key owner's own account. When `account_id` is provided: +If your account belongs to an organization, your personal key can access data for other accounts in the same org by passing the `account_id` parameter. +```bash +curl -X GET "https://api.recoupable.com/api/tasks?account_id=OTHER_ACCOUNT_ID" \ + -H "x-api-key: YOUR_API_KEY" ``` -Request includes account_id override? - ├── Same as key owner → Allowed (self-access) - ├── Key owner is a member of an org that contains account_id → Allowed - └── No matching org membership → 403 Forbidden -``` - -Membership is verified by checking the key owner's [organizations](/api-reference/organizations/list) for a record linking the account to the target account's organization. - -The Recoup internal admin organization has universal access to all accounts. - +## Admin Authentication -### Organization Access via `organization_id` - -Some endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either: - -- A **member** of the organization, or -- The **organization account itself** - ---- +Admin endpoints (`/api/admins/*`) require a Bearer token from Privy authentication, not an API key. These are used by the internal admin dashboard. -## Error Responses - -| Status | Cause | -|--------|-------| -| `401` | Missing or invalid credentials, or both `x-api-key` and `Authorization` headers provided | -| `403` | Valid credentials but insufficient access to the requested `account_id` or `organization_id` | - ---- - -## Security Notes - -- API keys are **never stored in plaintext** — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database -- **Never include `account_id` in your API key creation request** — the account is always derived from your authenticated credentials -- Rotate keys immediately if compromised via the [API Keys Management Page](https://chat.recoupable.com/keys) +```bash +curl -X GET "https://api.recoupable.com/api/admins/privy" \ + -H "Authorization: Bearer PRIVY_ACCESS_TOKEN" +``` diff --git a/cli.mdx b/cli.mdx index 29394ea..d0b00c0 100644 --- a/cli.mdx +++ b/cli.mdx @@ -1,9 +1,16 @@ --- title: "CLI" -description: "Install and use the Recoup CLI to interact with the platform from your terminal." +description: "Install and use the Recoup CLI for terminal-based music operations." --- -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. +The Recoup CLI (`@recoupable/cli`) gives you the full platform from your terminal. Manage artists, generate content, check task status, and automate workflows. + +The default flow is: + +1. Authenticate with `recoup whoami` +2. Browse your roster with `recoup artists list` +3. Create content with `recoup content create` +4. Monitor with `recoup tasks status` ## Installation @@ -13,20 +20,18 @@ 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). +Set your API key as an environment variable. Get one from the [API Keys page](https://chat.recoupable.com/keys). ```bash export RECOUP_API_KEY=your-api-key ``` -Verify it works: +Verify your session: ```bash recoup whoami ``` -## Configuration - | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `RECOUP_API_KEY` | Yes | — | Your Recoup API key | @@ -34,149 +39,161 @@ recoup whoami All commands support `--json` for machine-readable output and `--help` for usage info. -## whoami +## Content creation workflow -Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id). +This is the primary workflow for generating social-ready artist videos. + +### Step 1: Check available templates ```bash -recoup whoami -recoup whoami --json +recoup content templates ``` -## orgs +### Step 2: Validate artist readiness -Manage organizations. See [`GET /api/organizations`](/api-reference/organizations/list). +Before creating content, verify the artist has the required assets (songs, face guide, brand docs). ```bash -recoup orgs list -recoup orgs list --account -recoup orgs list --json +recoup content validate --artist ``` -## artists +### Step 3: Estimate cost -Manage artists. See [`GET /api/artists`](/api-reference/artists/list). +Preview cost and duration without starting a run. ```bash -recoup artists list -recoup artists list --org -recoup artists list --account -recoup artists list --json +recoup content estimate --artist +recoup content estimate --artist --template artist-caption-bedroom ``` -## notifications +### Step 4: Create content -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. +Trigger the full pipeline. Returns a run ID for tracking. ```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.

" -recoup notifications --subject "Pulse Report" --account --text "Here's your weekly summary." +recoup content create --artist +recoup content create --artist --template artist-caption-bedroom --lipsync +recoup content create --artist --songs hiccups,adhd --batch 3 ``` | 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 | -| `--account ` | No | Send to a specific account (org keys only) | - -This command wraps [`POST /api/notifications`](/api-reference/notifications/create). - -## chats +| `--artist ` | Yes | Artist account ID | +| `--template ` | No | Template name (default: random) | +| `--lipsync` | No | Enable lipsync mode | +| `--upscale` | No | Enable upscaling | +| `--caption-length ` | No | Max caption length in characters | +| `--songs ` | No | Comma-separated song slugs to limit clip selection | -Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create). +### Step 5: Monitor the run ```bash -recoup chats list -recoup chats create --name "My Topic" -recoup chats create --name "My Topic" --artist -recoup chats list --json +recoup tasks status --run +recoup tasks status --run --json ``` -## sandboxes - -Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create). +### End-to-end example ```bash -recoup sandboxes list -recoup sandboxes create -recoup sandboxes create --command "ls -la" -recoup sandboxes list --json +recoup content templates +recoup content validate --artist abc-123-uuid +recoup content estimate --artist abc-123-uuid --template artist-caption-bedroom +recoup content create --artist abc-123-uuid --template artist-caption-bedroom --lipsync +recoup tasks status --run run_abc123 ``` -## tasks - -Check the status of background task runs. See [`GET /api/tasks/runs`](/api-reference/tasks/runs). +## Artist management ```bash -recoup tasks status --run -recoup tasks status --run --json -``` - -| Flag | Required | Description | -|------|----------|-------------| -| `--run ` | Yes | Trigger.dev run ID | +# List all artists on your account +recoup artists list -## content +# Filter by organization +recoup artists list --org -Content-creation pipeline commands. Generate AI-powered social videos for artists. +# Filter by specific account +recoup artists list --account -### List templates +# JSON output for scripting +recoup artists list --json +``` -List available content templates. See [`GET /api/content/templates`](/api-reference/content/templates). +## Organizations ```bash -recoup content templates -recoup content templates --json +recoup orgs list +recoup orgs list --account +recoup orgs list --json ``` -### Validate artist - -Check that an artist has the required assets (face-guide, songs, context files) before creating content. See [`POST /api/content/validate`](/api-reference/content/validate). +## Chat management ```bash -recoup content validate --artist -recoup content validate --artist --json -``` +# List chats +recoup chats list -| Flag | Required | Description | -|------|----------|-------------| -| `--artist ` | Yes | Artist account ID | +# Create a new chat +recoup chats create --name "Release Strategy Q2" -### Estimate cost +# Create a chat with artist context +recoup chats create --name "EP Launch Plan" --artist +``` + +## Sandboxes -Preview the estimated cost and duration for a content run without starting it. See [`POST /api/content/estimate`](/api-reference/content/estimate). +Sandboxes are persistent environments where agents run. Create one to execute code, manage files, and run workflows. ```bash -recoup content estimate --artist -recoup content estimate --artist --template --json -``` +# List active sandboxes +recoup sandboxes list -| Flag | Required | Description | -|------|----------|-------------| -| `--artist ` | Yes | Artist account ID | -| `--template ` | No | Template name (default: random) | -| `--lipsync` | No | Enable lipsync mode | -| `--upscale` | No | Enable upscaling | +# Create a new sandbox +recoup sandboxes create + +# Run a command in a sandbox +recoup sandboxes create --command "ls -la" +``` -### Create content +## Notifications -Trigger the full content-creation pipeline. Returns a run ID you can check with [`recoup tasks status`](/cli#tasks). See [`POST /api/content`](/api-reference/content/create). +Send emails to the authenticated account. The recipient is resolved from your API key. ```bash -recoup content create --artist -recoup content create --artist --template --lipsync --upscale -recoup content create --artist --json +# Plain text email +recoup notifications --subject "Weekly Pulse" --text "Here's your summary." + +# HTML email +recoup notifications --subject "Weekly Pulse" --html "

Report

Active campaigns: 3

" + +# With CC +recoup notifications --subject "Update" --cc manager@example.com --text "New release scheduled." ``` | Flag | Required | Description | |------|----------|-------------| -| `--artist ` | Yes | Artist account ID | -| `--template ` | No | Template name (default: random) | -| `--lipsync` | No | Enable lipsync mode | -| `--upscale` | No | Enable upscaling | -| `--caption-length ` | No | Max caption length in characters | +| `--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 | +| `--account ` | No | Send to a specific account (org keys only) | + +## Command summary + +| Command | What It Does | +|---------|-------------| +| `recoup whoami` | Show authenticated account | +| `recoup artists list` | List artists on your account | +| `recoup orgs list` | List organizations | +| `recoup chats list` | List chats | +| `recoup chats create` | Create a new chat | +| `recoup content templates` | List content templates | +| `recoup content validate` | Check artist readiness | +| `recoup content estimate` | Preview cost and duration | +| `recoup content create` | Trigger content creation | +| `recoup tasks status` | Check task run status | +| `recoup sandboxes list` | List sandboxes | +| `recoup sandboxes create` | Create a sandbox | +| `recoup notifications` | Send a notification email | + +Run `recoup --help` for detailed usage and flags. diff --git a/docs.json b/docs.json index 9a686e2..d61bc2f 100644 --- a/docs.json +++ b/docs.json @@ -14,29 +14,29 @@ "tab": "Guides", "groups": [ { - "group": "Getting started", + "group": "Get Started", "pages": [ "index", "quickstart", - "cli", - "mcp", - "authentication", - "api-reference/sandboxes/create" + "how-it-works", + "authentication" ] }, { - "group": "Agents", + "group": "Integrate", "pages": [ + "mcp", + "cli", "content-agent" ] } ] }, { - "tab": "API reference", + "tab": "API Reference", "groups": [ { - "group": "API documentation", + "group": "Overview", "pages": [ "api-reference/introduction" ] @@ -265,19 +265,19 @@ "global": { "anchors": [ { - "anchor": "Recoup App", + "anchor": "Dashboard", "href": "https://chat.recoupable.com", "icon": "rocket" }, + { + "anchor": "API Keys", + "href": "https://chat.recoupable.com/keys", + "icon": "key" + }, { "anchor": "Website", "href": "https://recoupable.com", "icon": "globe" - }, - { - "anchor": "Blog", - "href": "https://research.recoupable.com/", - "icon": "newspaper" } ] } diff --git a/how-it-works.mdx b/how-it-works.mdx new file mode 100644 index 0000000..14b29b2 --- /dev/null +++ b/how-it-works.mdx @@ -0,0 +1,102 @@ +--- +title: "How It Works" +description: "Agents, sandboxes, context, and the architecture behind Recoup." +--- + +Recoup is a system, not a tool. You give it artist context. It deploys agents that run your music operations autonomously. + +## The Three Layers + +``` +┌─────────────────────────────────────────────────┐ +│ Entry Points │ +│ Web App · Slack · CLI · API · MCP │ +├─────────────────────────────────────────────────┤ +│ Agent Layer │ +│ Chat agents · Content agent · Coding agent │ +│ Scheduled tasks · Background workers │ +├─────────────────────────────────────────────────┤ +│ Context Layer │ +│ Artist profiles · Songs · Face guides │ +│ Brand docs · Audience data · Platform metrics │ +└─────────────────────────────────────────────────┘ +``` + +**Entry points** are how you interact with the system. Web app for visual workflows. Slack for team operations. CLI for automation. API and MCP for developers and other AI agents. + +**Agents** do the work. They create content, research audiences, generate reports, manage releases, and post to social platforms. Each agent is purpose-built for a specific job. + +**Context** is what makes the output yours. Every agent reads your artist files — songs, face guide, brand voice, audience data — before it creates anything. The agent doesn't guess. It reads your docs. + +## Agents + +Agents are autonomous workers. You give them a goal, they execute. Each agent type specializes in a domain. + +| Agent | What It Does | Entry Points | +|-------|-------------|--------------| +| **Chat Agent** | Conversational AI with full artist context. Research, planning, strategy. | Web App, API | +| **Content Agent** | Generates social-ready videos from your artist's songs and brand. | Slack, API, CLI | +| **Task Agent** | Runs scheduled operations — daily reports, batch jobs, monitoring. | API, Web App | + +### How agents use context + +When you create content for an artist, the agent reads: + +1. `context/artist.md` — who they are, their genre, brand voice, aesthetic +2. `context/audience.md` — fan demographics, platform behavior, engagement patterns +3. `context/images/face-guide.png` — visual reference for AI-generated imagery +4. `songs/*.mp3` — the actual music for clip selection and audio-driven content + +This is why Recoup content sounds like the artist, not like generic AI output. + +## Sandboxes + +Every account gets a persistent sandbox — an isolated environment where agents run code, manage files, and execute workflows. The sandbox persists across sessions, so agents pick up where they left off. + +```bash +# Via MCP +prompt_sandbox "analyze my top 5 songs by streaming performance" + +# Via API +POST /api/sandboxes +{ "prompt": "generate a release timeline for Q2" } + +# Via CLI +recoup sandboxes create --prompt "set up content pipeline for new EP" +``` + +Sandboxes are how Recoup moves from "suggesting" to "doing." The agent doesn't just recommend a marketing plan — it creates the assets, schedules the posts, and tracks the results. + +## Data Flow + +``` +Your data (songs, brand docs, social accounts) + ↓ +Recoup API (ingestion, normalization, storage) + ↓ +Agents (content creation, analysis, distribution) + ↓ +Platforms (Spotify, Instagram, TikTok, X, YouTube) + ↓ +Results (metrics, reports, optimizations) +``` + +## Integration Options + +| Method | Best For | Docs | +|--------|----------|------| +| **REST API** | Custom integrations, dashboards, programmatic access | [API Reference](/api-reference/introduction) | +| **MCP** | AI agents (Claude, Cursor, VS Code), tool-use workflows | [MCP Guide](/mcp) | +| **CLI** | Terminal workflows, scripting, CI/CD automation | [CLI Guide](/cli) | +| **Slack** | Team-based content operations, batch workflows | [Content Agent](/content-agent) | +| **Web App** | Visual interface, chat, artist management | [chat.recoupable.com](https://chat.recoupable.com) | + +## What Makes Recoup Different + +| Them | Us | +|------|------| +| Chatbot that suggests | System that executes | +| Generic AI tools adapted for music | Built for music — releases, fans, workflows | +| Manual operation required | Agents run autonomously with your context | +| One interface, one capability | Multiple entry points, one system | +| Point solutions (analytics OR content OR scheduling) | Full stack — create, distribute, measure, improve | diff --git a/index.mdx b/index.mdx index 05c0125..18ca3da 100644 --- a/index.mdx +++ b/index.mdx @@ -1,102 +1,139 @@ --- -title: "Recoup API Documentation" -description: "Use the Recoup API to build your record label." +title: "Recoup" +description: "Run your music business with agents. API, MCP, and CLI for autonomous music operations." --- -# Welcome to the Recoup API +# Run Your Music Business with Agents -Use the Recoup API to build your record label. Access artist analytics, fan segmentation, AI-powered chat, and task automation to power your music business. +Recoup deploys AI agents that handle the work of running a music business — release strategy, content creation, audience research, marketing, and operations. One system. Multiple entry points. -## What is Recoup? - -Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools. + + + **MCP** -This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. + Connect Claude, Cursor, or any MCP client to 40+ music-industry tools. -## Get Started + ```bash + https://recoup-api.vercel.app/mcp + ``` - + [MCP setup →](/mcp) + - Get your API key and make your first request in minutes. + **REST API** + + Programmatic access to agents, artists, content, analytics, and tasks. + + ```bash + https://api.recoupable.com/api + ``` + + [API reference →](/api-reference/introduction) - Explore all available endpoints and integrations. + **CLI** + + Same capabilities as the app. From your terminal. + + ```bash + npm install -g @recoupable/cli + ``` + + [CLI docs →](/cli) -## Key Capabilities +## What Recoup Does + +Recoup is the platform that enables autonomous music businesses. The agents don't just suggest — they create content, analyze audiences, manage releases, and post across platforms. - AI-powered conversations with artist context. Stream responses or generate complete messages. + Generate social-ready videos from artist context — songs, face guide, brand docs. 22 videos in one session, zero manual editing. - Comprehensive artist profiles with social metrics, follower counts, and engagement data across platforms. + Cross-platform fan data. Spotify, Instagram, TikTok, YouTube, X. Demographics, engagement, behavior patterns. - Organize and analyze fan bases by demographics, engagement levels, and behavior patterns. + Conversational AI with deep artist context. Tell the agent what you need in plain language. It acts. - Schedule and automate recurring tasks with cron-based scheduling and AI-powered execution. + Scheduled operations — daily reports, batch content runs, social monitoring. Runs in the background. -## Platform Integrations +## Who It's For - Search artists, albums, and tracks. + Run your career without a team. Agents handle marketing, content, and fan engagement so you stay in the studio. - Scrape profiles and comments. + Scale operations without scaling headcount. Standardize execution across your roster with context-aware agents. - Search tweets and trending topics. + Build on music-specific agent infrastructure. REST API, MCP server, CLI, webhooks. -## Need Help? +## Get Started - - Reach out to our team for assistance with the Recoup API. - + + + Get your API key and make your first request in 5 minutes. + + + Understand agents, sandboxes, and the platform architecture. + + + +## Platform Integrations + + + + + + + diff --git a/mcp.mdx b/mcp.mdx index 05709d8..853f4dc 100644 --- a/mcp.mdx +++ b/mcp.mdx @@ -1,45 +1,51 @@ --- title: "MCP" -description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP) server." +description: "Connect AI agents to 40+ music-industry tools via the Model Context Protocol." --- -The Recoup API exposes an [MCP](https://modelcontextprotocol.io/) server that AI agents can connect to for tool use. The server is available at: +The Recoup MCP server gives AI agents direct access to music-industry tools — artist data, content creation, audience analysis, Spotify research, YouTube analytics, and more. Connect from Claude Desktop, Cursor, VS Code, or any MCP-compatible client. ``` https://recoup-api.vercel.app/mcp ``` -## Authentication - -All MCP tools require an API key. Pass it as a Bearer token in the `Authorization` header when connecting to the MCP server. - -You can get a key from the [API Keys page](https://chat.recoupable.com/keys). - -## Tools - -### prompt_sandbox +## Connect -Send a prompt to OpenClaw running in a persistent per-account sandbox. The sandbox is reused across calls — if one is already running it picks up where you left off, otherwise a new one is created from the account's latest snapshot. +### Claude Desktop -Returns raw `stdout` and `stderr` from the command. The sandbox stays alive after each prompt for follow-up interactions. +Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): -**Input schema:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prompt` | `string` | Yes | The prompt to send to OpenClaw in the sandbox. | - -**Response fields:** +```json +{ + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` -| Field | Type | Description | -|-------|------|-------------| -| `sandboxId` | `string` | The Vercel Sandbox ID. | -| `stdout` | `string` | Standard output from the command. | -| `stderr` | `string` | Standard error from the command. | -| `exitCode` | `number` | Process exit code (`0` = success). | -| `created` | `boolean` | `true` if a new sandbox was created, `false` if an existing one was reused. | +### Cursor / VS Code + +Add to your MCP settings (`.cursor/mcp.json` or VS Code MCP config): + +```json +{ + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` -**Example usage (TypeScript with MCP SDK):** +### TypeScript SDK ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; @@ -47,32 +53,161 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/ const transport = new StreamableHTTPClientTransport( new URL("https://recoup-api.vercel.app/mcp"), - { requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } }, + { + requestInit: { + headers: { Authorization: `Bearer ${process.env.RECOUP_API_KEY}` }, + }, + } ); const client = new Client({ name: "my-agent", version: "1.0.0" }); await client.connect(transport); const result = await client.callTool({ - name: "prompt_sandbox", - arguments: { prompt: "list all files in the orgs directory" }, + name: "get_spotify_search", + arguments: { query: "Mac Miller", type: "artist" }, }); +``` + +## Authentication + +All tools require an API key. Pass it as a Bearer token in the `Authorization` header. + +Get a key from the [API Keys page](https://chat.recoupable.com/keys). + +## Tools + +### Artists & Socials + +| Tool | Description | +|------|-------------| +| `create_new_artist` | Create a new artist account | +| `get_artist_socials` | Get all social profiles for an artist (handle, avatar, bio, follower count) | +| `update_artist_socials` | Update artist social profiles from URLs | +| `update_account_info` | Update artist profile, name, instructions, label, knowledge base | +| `create_segments` | Analyze fan data and create audience segments | + +### Chat + +| Tool | Description | +|------|-------------| +| `get_chats` | Get chat conversations for accounts | +| `compact_chats` | Summarize long conversations into concise versions | + +### Content & Files + +| Tool | Description | +|------|-------------| +| `generate_image` | Generate an image from a text prompt | +| `edit_image` | Edit an existing image | +| `generate_sora_2_video` | Generate video from text using OpenAI Sora 2 | +| `retrieve_sora_2_video` | Check video generation status | +| `retrieve_sora_2_video_content` | Download rendered video content | +| `generate_txt_file` | Create a downloadable text file stored on Arweave | +| `create_knowledge_base` | Save reference notes to the artist's permanent storage | + +### Spotify + +| Tool | Description | +|------|-------------| +| `get_spotify_search` | Search Spotify for artists, albums, tracks, playlists | +| `get_spotify_artist_albums` | Get an artist's album catalog | +| `get_spotify_artist_top_tracks` | Get an artist's top tracks by country | +| `get_spotify_album` | Get album details | +| `spotify_deep_research` | Deep research on an artist via Spotify ID | + +### YouTube + +| Tool | Description | +|------|-------------| +| `get_youtube_channels` | Get YouTube channel info for an account | +| `get_youtube_channel_video_list` | List videos for a YouTube channel | +| `get_youtube_revenue` | Get estimated revenue for a date range | +| `set_youtube_thumbnail` | Set a custom video thumbnail | +| `youtube_login` | Check YouTube authentication status | + +### Catalogs & Songs + +| Tool | Description | +|------|-------------| +| `select_catalogs` | Get catalogs for an account | +| `select_catalog_songs` | Find songs from available catalogs | +| `insert_catalog_songs` | Add songs to a catalog by ISRC | + +### Tasks & Scheduling + +| Tool | Description | +|------|-------------| +| `get_tasks` | List tasks | +| `create_task` | Create a new scheduled task | +| `update_task` | Update an existing task | +| `delete_task` | Delete a task | +| `get_task_run_status` | Check the status of a task run | + +### Pulses + +| Tool | Description | +|------|-------------| +| `get_pulses` | Get pulse statuses for accounts | +| `update_pulse` | Update pulse status | + +### Audio & Music Analysis + +| Tool | Description | +|------|-------------| +| `transcribe_audio` | Transcribe audio using OpenAI Whisper (music, podcasts, voice memos) | +| `analyze_music` | Analyze music or answer music questions using Recoup's Audio Language Model | + +### Search & Research + +| Tool | Description | +|------|-------------| +| `search_web` | Web search — use first for any information you're unsure about | +| `search_google_images` | Search for existing images on Google | +| `artist_deep_research` | Comprehensive cross-platform artist research | +| `web_deep_research` | Deep multi-source web research | + +### Communication + +| Tool | Description | +|------|-------------| +| `send_email` | Send email via Resend API | +| `contact_team` | Message the Recoup support team | + +### Sandboxes + +| Tool | Description | +|------|-------------| +| `prompt_sandbox` | Send a prompt to a persistent agent sandbox | + +### Utilities + +| Tool | Description | +|------|-------------| +| `get_local_time` | Get current local time/date with optional timezone | + +## Example: Research an Artist -console.log(result.content); ``` +You: "Research Mac Miller's streaming performance and fan demographics" -### run_sandbox_command +Agent calls: get_spotify_search → get_spotify_artist_albums → + get_spotify_artist_top_tracks → artist_deep_research -Create a sandbox and run a shell command or OpenClaw prompt in it. Unlike `prompt_sandbox`, this creates a **new sandbox each call** and runs the command asynchronously via a background task. Returns a sandbox ID and run ID to track progress. +Agent returns: Comprehensive report with streaming data, discography analysis, + and fan engagement metrics. +``` + +## Example: Create Content + +``` +You: "Generate a promotional image for an upcoming EP release" + +Agent calls: get_artist_socials → generate_image -See [`POST /api/sandboxes`](/api-reference/sandboxes/create) for the equivalent REST endpoint. +Agent returns: Artist-branded promotional image ready for social posting. +``` -**Input schema:** +## Docs Search MCP -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `command` | `string` | No | Shell command to run. Cannot be used with `prompt`. | -| `args` | `string[]` | No | Arguments for the command. | -| `cwd` | `string` | No | Working directory for the command. | -| `prompt` | `string` | No | OpenClaw prompt. Cannot be used with `command`. | -| `account_id` | `string` | No | Target a specific account (org API keys only). | +Mintlify (which hosts these docs) also provides an MCP server for searching documentation. Look for the MCP option in the contextual menu on any docs page to get the connection config for searching Recoup docs directly from your AI assistant. diff --git a/quickstart.mdx b/quickstart.mdx index cc7e37b..0ab6c58 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,159 +1,145 @@ --- title: "Quickstart" -description: "Get your API key and make your first request to the Recoup API." +description: "Get your API key and start using Recoup in 5 minutes." --- -## Base URL - -All API requests should be made to: - -```bash -https://api.recoupable.com/api -``` +## 1. Get Your API Key -## API Keys - -To access the Recoup API programmatically, you'll need to create an API key. - -### Step 1: Access the API Keys Management Page - -1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.com/keys) -2. Sign in with your account if you haven't already - -### Step 2: Create Your API Key - -1. On the API Keys page, you'll see a form to create a new API key -2. Enter a descriptive name for your API key (e.g., "My Development Key", "Production API Key") -3. Click the "Create API Key" button +1. Go to the [API Keys page](https://chat.recoupable.com/keys) and sign in +2. Create a new key and copy it immediately — it's only shown once -Copy and securely store your API key immediately - it will only be shown once! +Store your API key securely. Do not commit it to version control or share it publicly. -### Step 3: Use Your API Key +## 2. Make Your First Request -Once you have your API key, include it in the `x-api-key` header for all authenticated requests. Here's a simple example that retrieves your scheduled tasks: +Search for an artist on Spotify — no existing data needed, works immediately. ```bash cURL -curl -X GET "https://api.recoupable.com/api/tasks" \ - -H "Content-Type: application/json" \ +curl -X GET "https://api.recoupable.com/api/spotify/search?q=Mac%20Miller&type=artist" \ -H "x-api-key: YOUR_API_KEY" ``` ```python Python import requests -headers = { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY" -} - response = requests.get( - "https://api.recoupable.com/api/tasks", - headers=headers + "https://api.recoupable.com/api/spotify/search", + params={"q": "Mac Miller", "type": "artist"}, + headers={"x-api-key": "YOUR_API_KEY"} ) -print(response.json()) + +artist = response.json() +print(artist) ``` ```javascript JavaScript -const response = await fetch("https://api.recoupable.com/api/tasks", { - headers: { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY", - }, -}); -const data = await response.json(); -console.log(data); +const response = await fetch( + "https://api.recoupable.com/api/spotify/search?q=Mac%20Miller&type=artist", + { headers: { "x-api-key": "YOUR_API_KEY" } } +); + +const artist = await response.json(); +console.log(artist); ``` -```typescript TypeScript -interface Task { - id: string; - title: string; - prompt: string; - schedule: string; - account_id: string; - artist_account_id: string; - enabled: boolean; -} + -interface TasksResponse { - status: "success" | "error"; - tasks: Task[]; -} +## 3. Try the CLI -const response = await fetch("https://api.recoupable.com/api/tasks", { - headers: { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY", - }, -}); -const data: TasksResponse = await response.json(); -console.log(data.tasks); +Install the CLI for terminal access to the full platform. + +```bash +npm install -g @recoupable/cli +export RECOUP_API_KEY=your-api-key +recoup whoami ``` - +Now search for artists, manage content, and run tasks from your terminal. -**Example Response:** +```bash +recoup artists list +recoup content templates +``` -```json +## 4. Connect via MCP + +If you use Claude Desktop, Cursor, or VS Code — connect directly to Recoup's MCP server. + + + +```json Claude Desktop { - "status": "success", - "tasks": [ - { - "id": "550e8400-e29b-41d4-a716-446655440000", - "title": "Daily Fan Report", - "prompt": "Generate a summary of new fans from the past 24 hours", - "schedule": "0 9 * * *", - "account_id": "123e4567-e89b-12d3-a456-426614174000", - "artist_account_id": "987fcdeb-51a2-3b4c-d5e6-789012345678", - "enabled": true + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } } - ] + } } ``` - -For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). - +```json Cursor / VS Code +{ + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` -## Next Steps + + +Once connected, your AI assistant has access to 40+ music-industry tools — artist data, content creation, audience analysis, and more. -With your API key ready, you can now: +## Base URL + +All REST API requests go to: + +``` +https://api.recoupable.com/api +``` + +All requests require your API key in the `x-api-key` header. + +## Next Steps - Fetch artist profiles, social accounts, and segments. + Understand agents, sandboxes, and context. - Access fan data across all connected social platforms. + Connect AI agents to 40+ music tools. - Build AI-powered conversations with artist context. + Full platform access from your terminal. - Schedule and automate recurring tasks. + Explore all endpoints. - -## Support - -If you need help or have questions about the API, please contact our support team at [agent@recoupable.com](mailto:agent@recoupable.com). From 241e3a3b12351f8b4f827f0223fb4d9c4ca3d433 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 21:56:02 -0400 Subject: [PATCH 02/13] docs: remove corny proof point from content creation card Made-with: Cursor --- index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.mdx b/index.mdx index 18ca3da..685b81f 100644 --- a/index.mdx +++ b/index.mdx @@ -62,7 +62,7 @@ Recoup is the platform that enables autonomous music businesses. The agents don' icon="video" href="/api-reference/content/create" > - Generate social-ready videos from artist context — songs, face guide, brand docs. 22 videos in one session, zero manual editing. + Generate social-ready videos from artist context — songs, face guide, brand docs. The agent handles clip selection, captions, and rendering. Date: Sun, 29 Mar 2026 22:04:10 -0400 Subject: [PATCH 03/13] docs: upgrade homepage with tabs, accordions, and stronger identity Inspired by Claude Code, Exa, and Trigger.dev docs. Uses Mintlify Tabs for integration methods (MCP/API/CLI/Slack), AccordionGroup for capabilities, and a routing table for different user types. Made-with: Cursor --- index.mdx | 197 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 104 insertions(+), 93 deletions(-) diff --git a/index.mdx b/index.mdx index 685b81f..455a834 100644 --- a/index.mdx +++ b/index.mdx @@ -3,114 +3,134 @@ title: "Recoup" description: "Run your music business with agents. API, MCP, and CLI for autonomous music operations." --- -# Run Your Music Business with Agents +Recoup is an AI agent platform for the music industry. It creates content, analyzes audiences, manages releases, and posts across platforms — autonomously, using your artist's context. Available as an API, MCP server, and CLI. -Recoup deploys AI agents that handle the work of running a music business — release strategy, content creation, audience research, marketing, and operations. One system. Multiple entry points. +## Get started - - - **MCP** +Choose how you want to integrate. The API, MCP, and CLI all connect to the same system — your artists, context, and data are shared across all of them. - Connect Claude, Cursor, or any MCP client to 40+ music-industry tools. + + + Connect Claude Desktop, Cursor, or any MCP client to 40+ music-industry tools. No SDK needed. - ```bash - https://recoup-api.vercel.app/mcp + Add to your MCP config: + + ```json + { + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } ``` - [MCP setup →](/mcp) - - - **REST API** + Once connected, your AI assistant can search Spotify, create content, analyze audiences, manage tasks, and more. - Programmatic access to agents, artists, content, analytics, and tasks. + [Full MCP setup and tool list →](/mcp) + + + Programmatic access to artists, content, analytics, tasks, and integrations. ```bash - https://api.recoupable.com/api + curl -X GET "https://api.recoupable.com/api/spotify/search?q=Mac%20Miller&type=artist" \ + -H "x-api-key: YOUR_API_KEY" ``` - [API reference →](/api-reference/introduction) - - - **CLI** + All endpoints return JSON. Authentication is a single API key in the `x-api-key` header. - Same capabilities as the app. From your terminal. + [API reference →](/api-reference/introduction) + + + Full platform access from your terminal. Manage artists, generate content, monitor tasks. ```bash npm install -g @recoupable/cli + export RECOUP_API_KEY=your-api-key + recoup whoami ``` + Then run content workflows, list artists, and check task status — all from the command line. + [CLI docs →](/cli) - - + + + The Content Agent bot generates social-ready videos from Slack. Mention the bot with an artist ID, and it handles the rest. -## What Recoup Does + ``` + @RecoupContentAgent abc-123-uuid artist-caption-bedroom batch=3 + ``` -Recoup is the platform that enables autonomous music businesses. The agents don't just suggest — they create content, analyze audiences, manage releases, and post across platforms. + Results are posted back to your thread when the pipeline finishes. - - - Generate social-ready videos from artist context — songs, face guide, brand docs. The agent handles clip selection, captions, and rendering. - - - Cross-platform fan data. Spotify, Instagram, TikTok, YouTube, X. Demographics, engagement, behavior patterns. - - - Conversational AI with deep artist context. Tell the agent what you need in plain language. It acts. - - - Scheduled operations — daily reports, batch content runs, social monitoring. Runs in the background. - - + [Content Agent setup →](/content-agent) + + -## Who It's For + +Get your API key from the [API Keys page](https://chat.recoupable.com/keys). One key works across all integration methods. + - - - Run your career without a team. Agents handle marketing, content, and fan engagement so you stay in the studio. - - - Scale operations without scaling headcount. Standardize execution across your roster with context-aware agents. - - - Build on music-specific agent infrastructure. REST API, MCP server, CLI, webhooks. - +## What you can do + + + + Agents read your artist's songs, face guide, brand voice, and audience data — then create social-ready videos, captions, and imagery that sound like the artist, not like generic AI. + + ```bash + recoup content create --artist --template artist-caption-bedroom --lipsync + ``` + + The pipeline handles clip selection, rendering, captioning, and delivery. Run one video or batch 30. + + + Pull fan data from Spotify, Instagram, TikTok, YouTube, and X. Demographics, engagement patterns, follower trends, and streaming performance — all through a single API. + + ```bash + curl "https://api.recoupable.com/api/artist/profile?artistId=YOUR_ARTIST_ID" \ + -H "x-api-key: YOUR_API_KEY" + ``` + + + Every chat agent reads the artist's context files before responding. Ask for a release strategy, competitive analysis, or marketing plan — the agent works from real data, not assumptions. + + + Set up recurring tasks — daily fan reports, weekly content runs, social monitoring. Tasks run in the background on Trigger.dev workers and deliver results via email or webhook. + + ```bash + recoup tasks status --run + ``` + + + Every account gets a persistent sandbox — an isolated environment where agents execute code, manage files, and run multi-step workflows. The sandbox persists across sessions. + + + Agents connect to Spotify, YouTube, Gmail, Google Calendar, Instagram, TikTok, X, Slack, and LinkedIn via Composio connectors. Authenticate once, agents use them automatically. + + + +## Who it's for + +| I am a... | I want to... | Start here | +|-----------|-------------|------------| +| **Artist** | Run my career without a team — content, marketing, fan engagement | [Dashboard](https://chat.recoupable.com) | +| **Label / Manager** | Scale operations across my roster without scaling headcount | [How It Works](/how-it-works) | +| **Developer** | Build on music-specific agent infrastructure | [API Reference](/api-reference/introduction) | +| **AI agent builder** | Connect my agent to music-industry tools | [MCP](/mcp) | + +## Platform integrations + + + + + + -## Get Started +## Next steps - Understand agents, sandboxes, and the platform architecture. + Agents, sandboxes, context, and architecture. - -## Platform Integrations - - - - - - - From a9adf99ce040bd3016f6d90e1a4213abaaf4327a Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:07:15 -0400 Subject: [PATCH 04/13] =?UTF-8?q?docs:=20sharpen=20identity=20=E2=80=94=20?= =?UTF-8?q?deep=20context=20edge,=20"why=20not=20ChatGPT"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Uses real founder language: "AI infrastructure for the music industry", "general purpose agents can't do what we do because they don't know the artist", context as the entire edge. Made-with: Cursor --- how-it-works.mdx | 22 ++++++++++++---------- index.mdx | 2 +- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/how-it-works.mdx b/how-it-works.mdx index 14b29b2..8679f09 100644 --- a/how-it-works.mdx +++ b/how-it-works.mdx @@ -3,7 +3,7 @@ title: "How It Works" description: "Agents, sandboxes, context, and the architecture behind Recoup." --- -Recoup is a system, not a tool. You give it artist context. It deploys agents that run your music operations autonomously. +General purpose AI tools don't know the artist, the catalog, the audience, or the history. Recoup does. You give it artist context — songs, brand voice, audience data, release history — and it deploys agents that run operations using that context. That's the edge: every feature is so context-aware that you'd never go back to ChatGPT or doing it by hand. ## The Three Layers @@ -26,7 +26,7 @@ Recoup is a system, not a tool. You give it artist context. It deploys agents th **Agents** do the work. They create content, research audiences, generate reports, manage releases, and post to social platforms. Each agent is purpose-built for a specific job. -**Context** is what makes the output yours. Every agent reads your artist files — songs, face guide, brand voice, audience data — before it creates anything. The agent doesn't guess. It reads your docs. +**Context** is the entire edge. Every agent reads the artist's files before it does anything — songs, face guide, brand voice, audience data, release history. This is why Recoup output doesn't sound like generic AI. The agent knows the artist the way a dedicated manager would. ## Agents @@ -91,12 +91,14 @@ Results (metrics, reports, optimizations) | **Slack** | Team-based content operations, batch workflows | [Content Agent](/content-agent) | | **Web App** | Visual interface, chat, artist management | [chat.recoupable.com](https://chat.recoupable.com) | -## What Makes Recoup Different +## Why not ChatGPT -| Them | Us | -|------|------| -| Chatbot that suggests | System that executes | -| Generic AI tools adapted for music | Built for music — releases, fans, workflows | -| Manual operation required | Agents run autonomously with your context | -| One interface, one capability | Multiple entry points, one system | -| Point solutions (analytics OR content OR scheduling) | Full stack — create, distribute, measure, improve | +General purpose agents can generate a marketing plan for any artist. Recoup agents generate a marketing plan for *your* artist — using their actual songs, their real audience data, their brand voice, their release history. + +| Generic AI | Recoup | +|------------|--------| +| Knows nothing about the artist | Reads `artist.md`, `audience.md`, songs, face guide before every action | +| Suggests a plan | Creates the assets, schedules the posts, tracks the results | +| One conversation, then gone | Persistent sandbox — picks up where it left off | +| You copy-paste between tools | API, MCP, CLI, Slack — one system, every entry point | +| Same output for every artist | Context-aware output that sounds like the artist, not like AI | diff --git a/index.mdx b/index.mdx index 455a834..8ad8fd1 100644 --- a/index.mdx +++ b/index.mdx @@ -3,7 +3,7 @@ title: "Recoup" description: "Run your music business with agents. API, MCP, and CLI for autonomous music operations." --- -Recoup is an AI agent platform for the music industry. It creates content, analyzes audiences, manages releases, and posts across platforms — autonomously, using your artist's context. Available as an API, MCP server, and CLI. +We build AI infrastructure for the music industry — agents and tools for agents that run music businesses. Content creation, analytics, marketing, catalog management. Available as an API, MCP server, and CLI. ## Get started From e53a0f3109be711f5fe7ec48df831bb91232e9d0 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:11:51 -0400 Subject: [PATCH 05/13] =?UTF-8?q?docs:=20rewrite=20homepage=20=E2=80=94=20?= =?UTF-8?q?exciting,=20actionable,=20install-first?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Leads with what you can do. Tabs for connecting Cursor, Claude Code, OpenClaw, Claude Desktop, API, CLI. Accordions show real prompts and tool names. No preamble — connect in under a minute. Made-with: Cursor --- index.mdx | 197 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 122 insertions(+), 75 deletions(-) diff --git a/index.mdx b/index.mdx index 8ad8fd1..d1c98ec 100644 --- a/index.mdx +++ b/index.mdx @@ -1,19 +1,51 @@ --- title: "Recoup" -description: "Run your music business with agents. API, MCP, and CLI for autonomous music operations." +description: "AI infrastructure for the music industry. Connect your AI tools to 40+ music-industry agents." --- -We build AI infrastructure for the music industry — agents and tools for agents that run music businesses. Content creation, analytics, marketing, catalog management. Available as an API, MCP server, and CLI. +# AI Infrastructure for Music -## Get started +40+ tools that know your artists, your catalog, your audience, and your history. Search Spotify. Generate content. Analyze fans. Run entire release campaigns. From Claude Code, Cursor, OpenClaw, or anything that speaks MCP. -Choose how you want to integrate. The API, MCP, and CLI all connect to the same system — your artists, context, and data are shared across all of them. + +**Just want to connect?** Copy the config below, paste it, and start using Recoup tools in under a minute. + + +## Connect your tools - - Connect Claude Desktop, Cursor, or any MCP client to 40+ music-industry tools. No SDK needed. + + Add to `.cursor/mcp.json` in your project (or global settings): + + ```json + { + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + Restart Cursor. You now have 40+ music tools available in every conversation. + + + Run this in your terminal: + + ```bash + claude mcp add recoup \ + --transport http \ + --url https://recoup-api.vercel.app/mcp \ + --header "Authorization: Bearer YOUR_API_KEY" + ``` - Add to your MCP config: + That's it. Claude Code can now search Spotify, create content, analyze artists, and more. + + + OpenClaw connects via MCP automatically in Recoup sandboxes. If you're running outside a sandbox, add the MCP server: ```json { @@ -27,124 +59,139 @@ Choose how you want to integrate. The API, MCP, and CLI all connect to the same } } ``` + + + Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: - Once connected, your AI assistant can search Spotify, create content, analyze audiences, manage tasks, and more. + ```json + { + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } + ``` - [Full MCP setup and tool list →](/mcp) + Restart Claude Desktop. All Recoup tools appear in your tool list. - Programmatic access to artists, content, analytics, tasks, and integrations. - ```bash - curl -X GET "https://api.recoupable.com/api/spotify/search?q=Mac%20Miller&type=artist" \ + curl "https://api.recoupable.com/api/spotify/search?q=Mac%20Miller&type=artist" \ -H "x-api-key: YOUR_API_KEY" ``` - All endpoints return JSON. Authentication is a single API key in the `x-api-key` header. - - [API reference →](/api-reference/introduction) + [Full API reference →](/api-reference/introduction) - Full platform access from your terminal. Manage artists, generate content, monitor tasks. - ```bash npm install -g @recoupable/cli export RECOUP_API_KEY=your-api-key recoup whoami ``` - Then run content workflows, list artists, and check task status — all from the command line. - [CLI docs →](/cli) - - The Content Agent bot generates social-ready videos from Slack. Mention the bot with an artist ID, and it handles the rest. - - ``` - @RecoupContentAgent abc-123-uuid artist-caption-bedroom batch=3 - ``` - - Results are posted back to your thread when the pipeline finishes. - - [Content Agent setup →](/content-agent) - - -Get your API key from the [API Keys page](https://chat.recoupable.com/keys). One key works across all integration methods. - +Get your API key from the [API Keys page](https://chat.recoupable.com/keys). One key works everywhere. ## What you can do - - Agents read your artist's songs, face guide, brand voice, and audience data — then create social-ready videos, captions, and imagery that sound like the artist, not like generic AI. + + Find artists, pull their albums, get top tracks by country, and run deep research — all from your AI tool. - ```bash - recoup content create --artist --template artist-caption-bedroom --lipsync + ``` + "Search Spotify for Wiz Khalifa and show me his top 5 tracks" ``` - The pipeline handles clip selection, rendering, captioning, and delivery. Run one video or batch 30. + Tools: `get_spotify_search`, `get_spotify_artist_albums`, `get_spotify_artist_top_tracks`, `spotify_deep_research` - - Pull fan data from Spotify, Instagram, TikTok, YouTube, and X. Demographics, engagement patterns, follower trends, and streaming performance — all through a single API. + + The content pipeline reads the artist's songs, face guide, and brand docs — then generates videos with clip selection, captions, and rendering. Run one or batch 30. ```bash - curl "https://api.recoupable.com/api/artist/profile?artistId=YOUR_ARTIST_ID" \ - -H "x-api-key: YOUR_API_KEY" + recoup content create --artist --template artist-caption-bedroom --lipsync --songs hiccups,adhd ``` + + Or trigger it from Slack: `@RecoupContentAgent abc-123-uuid batch=5` - - Every chat agent reads the artist's context files before responding. Ask for a release strategy, competitive analysis, or marketing plan — the agent works from real data, not assumptions. + + Cross-platform artist research that pulls from Spotify, YouTube, Instagram, TikTok, and the web. The agent builds a full picture — streaming data, audience demographics, engagement trends, competitive positioning. + + ``` + "Do a deep research report on this artist's streaming performance and fan demographics" + ``` + + Tools: `artist_deep_research`, `web_deep_research`, `search_web` - - Set up recurring tasks — daily fan reports, weekly content runs, social monitoring. Tasks run in the background on Trigger.dev workers and deliver results via email or webhook. + + Pull channel info, list videos, check revenue data, and set custom thumbnails — all through your AI assistant. - ```bash - recoup tasks status --run ``` + "Show me the last 10 videos on this YouTube channel and their view counts" + ``` + + Tools: `get_youtube_channels`, `get_youtube_channel_video_list`, `get_youtube_revenue`, `set_youtube_thumbnail` - - Every account gets a persistent sandbox — an isolated environment where agents execute code, manage files, and run multi-step workflows. The sandbox persists across sessions. + + Every account gets an isolated sandbox where agents run code, manage files, and execute multi-step workflows. The sandbox persists — agents pick up where they left off. + + ``` + "Set up a content pipeline for the new EP and schedule weekly social posts" + ``` + + Tool: `prompt_sandbox` + + + Daily fan reports, batch content runs, social monitoring — set it up once and it runs in the background. Results delivered via email or webhook. + + Tools: `create_task`, `get_tasks`, `update_task`, `get_task_run_status` + + + Create promotional artwork, edit existing images, or search Google Images for real photos and references. + + Tools: `generate_image`, `edit_image`, `search_google_images` - - Agents connect to Spotify, YouTube, Gmail, Google Calendar, Instagram, TikTok, X, Slack, and LinkedIn via Composio connectors. Authenticate once, agents use them automatically. + + Transcribe audio with Whisper (music, podcasts, voice memos) and analyze tracks with Recoup's Audio Language Model. + + Tools: `transcribe_audio`, `analyze_music` +## Why Recoup and not ChatGPT + +General purpose AI doesn't know the artist, the catalog, the audience, or the history. Recoup does. Every tool reads your artist's context files — songs, brand voice, audience data — before it does anything. The output sounds like the artist, not like AI. + +[How context works →](/how-it-works) + ## Who it's for | I am a... | I want to... | Start here | |-----------|-------------|------------| -| **Artist** | Run my career without a team — content, marketing, fan engagement | [Dashboard](https://chat.recoupable.com) | -| **Label / Manager** | Scale operations across my roster without scaling headcount | [How It Works](/how-it-works) | | **Developer** | Build on music-specific agent infrastructure | [API Reference](/api-reference/introduction) | -| **AI agent builder** | Connect my agent to music-industry tools | [MCP](/mcp) | - -## Platform integrations - - - - - - - +| **AI agent builder** | Connect my agent to music tools via MCP | [MCP tool list](/mcp) | +| **Label / Manager** | Scale operations across a roster | [How It Works](/how-it-works) | +| **Artist** | Run my career with agents | [Dashboard](https://chat.recoupable.com) | ## Next steps - - Get your API key and make your first request in 5 minutes. + + API key setup and first request in 5 minutes. - + Agents, sandboxes, context, and architecture. + + All 40+ tools with descriptions and examples. + + + Content workflows, artist management, task monitoring. + From 7c12a15be70018ed15bb33e166c8b0241f3a82c1 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:14:02 -0400 Subject: [PATCH 06/13] docs: replace ugly ASCII diagrams with Mintlify Steps components Made-with: Cursor --- how-it-works.mdx | 53 ++++++++++++++++++++---------------------------- 1 file changed, 22 insertions(+), 31 deletions(-) diff --git a/how-it-works.mdx b/how-it-works.mdx index 8679f09..7dbcc48 100644 --- a/how-it-works.mdx +++ b/how-it-works.mdx @@ -7,26 +7,17 @@ General purpose AI tools don't know the artist, the catalog, the audience, or th ## The Three Layers -``` -┌─────────────────────────────────────────────────┐ -│ Entry Points │ -│ Web App · Slack · CLI · API · MCP │ -├─────────────────────────────────────────────────┤ -│ Agent Layer │ -│ Chat agents · Content agent · Coding agent │ -│ Scheduled tasks · Background workers │ -├─────────────────────────────────────────────────┤ -│ Context Layer │ -│ Artist profiles · Songs · Face guides │ -│ Brand docs · Audience data · Platform metrics │ -└─────────────────────────────────────────────────┘ -``` - -**Entry points** are how you interact with the system. Web app for visual workflows. Slack for team operations. CLI for automation. API and MCP for developers and other AI agents. - -**Agents** do the work. They create content, research audiences, generate reports, manage releases, and post to social platforms. Each agent is purpose-built for a specific job. - -**Context** is the entire edge. Every agent reads the artist's files before it does anything — songs, face guide, brand voice, audience data, release history. This is why Recoup output doesn't sound like generic AI. The agent knows the artist the way a dedicated manager would. + + + Artist profiles, songs, face guides, brand docs, audience data, platform metrics. This is what makes the output *yours*. Every agent reads these files before it does anything — the agent knows the artist the way a dedicated manager would. + + + Chat agents, Content agent, Coding agent, scheduled tasks, background workers. Agents do the work — they create content, research audiences, generate reports, manage releases, and post to social platforms. + + + Web App, Slack, CLI, API, MCP. These are how you interact with the system. Different surfaces, same agents, same context. Use the web app for visual workflows, Slack for team ops, CLI for automation, API and MCP for developers. + + ## Agents @@ -69,17 +60,17 @@ Sandboxes are how Recoup moves from "suggesting" to "doing." The agent doesn't j ## Data Flow -``` -Your data (songs, brand docs, social accounts) - ↓ -Recoup API (ingestion, normalization, storage) - ↓ -Agents (content creation, analysis, distribution) - ↓ -Platforms (Spotify, Instagram, TikTok, X, YouTube) - ↓ -Results (metrics, reports, optimizations) -``` + + + Songs, brand docs, social accounts, audience files. Upload through the web app, API, or CLI. + + + Content creation, audience analysis, competitive research, distribution. Agents read your context and act. + + + Videos on Instagram. Reports in your inbox. Analytics in your dashboard. Metrics tracked across Spotify, YouTube, TikTok, X. + + ## Integration Options From 52c73179ad5172ec18b4ad04756c27305f41a40b Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:18:51 -0400 Subject: [PATCH 07/13] docs: rewrite for agents as primary audience MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "The MCP server for music" — agents need clarity (what tools exist), confidence (real example with real output), and hype (why pick this over generic tools). Tool names on every card. Connect in 30 seconds. Made-with: Cursor --- index.mdx | 185 +++++++++++++++++++++++++----------------------------- 1 file changed, 85 insertions(+), 100 deletions(-) diff --git a/index.mdx b/index.mdx index d1c98ec..8ea247c 100644 --- a/index.mdx +++ b/index.mdx @@ -1,21 +1,19 @@ --- title: "Recoup" -description: "AI infrastructure for the music industry. Connect your AI tools to 40+ music-industry agents." +description: "Music-industry tools for AI agents. Spotify data, content generation, audience research, catalog management — via MCP." --- -# AI Infrastructure for Music +# The MCP server for music -40+ tools that know your artists, your catalog, your audience, and your history. Search Spotify. Generate content. Analyze fans. Run entire release campaigns. From Claude Code, Cursor, OpenClaw, or anything that speaks MCP. +Recoup gives your agent access to the music industry. Spotify data, artist research, content generation, audience analytics, YouTube revenue, catalog management, and more — 40+ tools, one connection. - -**Just want to connect?** Copy the config below, paste it, and start using Recoup tools in under a minute. - +Every tool is context-aware. Recoup knows the artist, the catalog, the audience, and the release history. Your agent gets music-specific results that generic tools can't match. -## Connect your tools +## Connect in 30 seconds - Add to `.cursor/mcp.json` in your project (or global settings): + Add to `.cursor/mcp.json`: ```json { @@ -29,23 +27,17 @@ description: "AI infrastructure for the music industry. Connect your AI tools to } } ``` - - Restart Cursor. You now have 40+ music tools available in every conversation. - Run this in your terminal: - ```bash claude mcp add recoup \ --transport http \ --url https://recoup-api.vercel.app/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` - - That's it. Claude Code can now search Spotify, create content, analyze artists, and more. - OpenClaw connects via MCP automatically in Recoup sandboxes. If you're running outside a sandbox, add the MCP server: + Pre-connected in Recoup sandboxes. Outside a sandbox: ```json { @@ -75,123 +67,116 @@ description: "AI infrastructure for the music industry. Connect your AI tools to } } ``` - - Restart Claude Desktop. All Recoup tools appear in your tool list. - - ```bash - curl "https://api.recoupable.com/api/spotify/search?q=Mac%20Miller&type=artist" \ - -H "x-api-key: YOUR_API_KEY" + ``` - - [Full API reference →](/api-reference/introduction) - - - ```bash - npm install -g @recoupable/cli - export RECOUP_API_KEY=your-api-key - recoup whoami + Server URL: https://recoup-api.vercel.app/mcp + Auth: Bearer token in Authorization header ``` - - [CLI docs →](/cli) -Get your API key from the [API Keys page](https://chat.recoupable.com/keys). One key works everywhere. +Get your API key → [chat.recoupable.com/keys](https://chat.recoupable.com/keys) -## What you can do +## What your agent can do - - - Find artists, pull their albums, get top tracks by country, and run deep research — all from your AI tool. + + + Search artists, albums, tracks. Pull discographies, top tracks by country, album details. Deep artist research. - ``` - "Search Spotify for Wiz Khalifa and show me his top 5 tracks" - ``` + `get_spotify_search` · `get_spotify_artist_albums` · `get_spotify_artist_top_tracks` · `spotify_deep_research` + + + Channel info, video lists, estimated revenue, custom thumbnails, auth status. - Tools: `get_spotify_search`, `get_spotify_artist_albums`, `get_spotify_artist_top_tracks`, `spotify_deep_research` - - - The content pipeline reads the artist's songs, face guide, and brand docs — then generates videos with clip selection, captions, and rendering. Run one or batch 30. + `get_youtube_channels` · `get_youtube_channel_video_list` · `get_youtube_revenue` · `set_youtube_thumbnail` + + + Generate social-ready videos from artist songs, face guide, and brand context. Single or batch. Lipsync, upscale, custom captions. - ```bash - recoup content create --artist --template artist-caption-bedroom --lipsync --songs hiccups,adhd - ``` + `prompt_sandbox` · via [CLI](/cli) or [Slack](/content-agent) + + + Deep cross-platform artist research. Web search. Google Images. Multi-source analysis reports. - Or trigger it from Slack: `@RecoupContentAgent abc-123-uuid batch=5` - - - Cross-platform artist research that pulls from Spotify, YouTube, Instagram, TikTok, and the web. The agent builds a full picture — streaming data, audience demographics, engagement trends, competitive positioning. + `artist_deep_research` · `web_deep_research` · `search_web` · `search_google_images` + + + Generate images from prompts. Edit existing images. Generate video with Sora 2. - ``` - "Do a deep research report on this artist's streaming performance and fan demographics" - ``` + `generate_image` · `edit_image` · `generate_sora_2_video` + + + Transcribe audio with Whisper. Analyze music with Recoup's Audio Language Model. - Tools: `artist_deep_research`, `web_deep_research`, `search_web` - - - Pull channel info, list videos, check revenue data, and set custom thumbnails — all through your AI assistant. + `transcribe_audio` · `analyze_music` + + + Create scheduled tasks, monitor runs, automate recurring operations. - ``` - "Show me the last 10 videos on this YouTube channel and their view counts" - ``` + `create_task` · `get_tasks` · `update_task` · `get_task_run_status` + + + Query catalogs, find songs by ISRC, add tracks in batch. - Tools: `get_youtube_channels`, `get_youtube_channel_video_list`, `get_youtube_revenue`, `set_youtube_thumbnail` - - - Every account gets an isolated sandbox where agents run code, manage files, and execute multi-step workflows. The sandbox persists — agents pick up where they left off. + `select_catalogs` · `select_catalog_songs` · `insert_catalog_songs` + + - ``` - "Set up a content pipeline for the new EP and schedule weekly social posts" - ``` +[See all 40+ tools with full descriptions →](/mcp) - Tool: `prompt_sandbox` - - - Daily fan reports, batch content runs, social monitoring — set it up once and it runs in the background. Results delivered via email or webhook. +## Example: what an agent call looks like - Tools: `create_task`, `get_tasks`, `update_task`, `get_task_run_status` - - - Create promotional artwork, edit existing images, or search Google Images for real photos and references. +Ask your agent: - Tools: `generate_image`, `edit_image`, `search_google_images` - - - Transcribe audio with Whisper (music, podcasts, voice memos) and analyze tracks with Recoup's Audio Language Model. +``` +"Find Mac Miller on Spotify and show me his top 5 tracks" +``` - Tools: `transcribe_audio`, `analyze_music` - - +The agent calls `get_spotify_search` with `{ "query": "Mac Miller", "type": "artist" }`, then `get_spotify_artist_top_tracks` with the artist ID. You get back track names, popularity scores, album info, and preview URLs — real Spotify data, not a web scrape. -## Why Recoup and not ChatGPT +## Why agents pick Recoup -General purpose AI doesn't know the artist, the catalog, the audience, or the history. Recoup does. Every tool reads your artist's context files — songs, brand voice, audience data — before it does anything. The output sounds like the artist, not like AI. + + + Not a generic API adapted for music. Built for artists, catalogs, releases, and fans from day one. + + + Every tool knows the artist's songs, brand voice, audience data, and history. Output is artist-specific, not generic. + + + Spotify, YouTube, Instagram, content generation, analytics, tasks, sandboxes — all through one MCP server. + + + +## Also available as -[How context works →](/how-it-works) + + + Direct HTTP access. Same tools, same data. -## Who it's for + `https://api.recoupable.com/api` + + + Terminal workflows, scripting, automation. -| I am a... | I want to... | Start here | -|-----------|-------------|------------| -| **Developer** | Build on music-specific agent infrastructure | [API Reference](/api-reference/introduction) | -| **AI agent builder** | Connect my agent to music tools via MCP | [MCP tool list](/mcp) | -| **Label / Manager** | Scale operations across a roster | [How It Works](/how-it-works) | -| **Artist** | Run my career with agents | [Dashboard](https://chat.recoupable.com) | + `npm install -g @recoupable/cli` + + ## Next steps - - API key setup and first request in 5 minutes. + + All 40+ MCP tools with descriptions, inputs, and examples. - - Agents, sandboxes, context, and architecture. + + Why Recoup output is artist-specific, not generic AI. - - All 40+ tools with descriptions and examples. + + API key + first request in 5 minutes. - - Content workflows, artist management, task monitoring. + + Generate videos from Slack with a single @mention. From 35a9b4a5f6a75162cd573e06694fe93d36c7aa53 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:20:33 -0400 Subject: [PATCH 08/13] docs: reposition as "The CLI for Music" CLI-first positioning. npm install is the hero. Cards show CLI commands alongside MCP tool names. MCP tabs are secondary. Made-with: Cursor --- index.mdx | 136 ++++++++++++++++++++++++------------------------------ 1 file changed, 61 insertions(+), 75 deletions(-) diff --git a/index.mdx b/index.mdx index 8ea247c..2409ca4 100644 --- a/index.mdx +++ b/index.mdx @@ -1,18 +1,37 @@ --- title: "Recoup" -description: "Music-industry tools for AI agents. Spotify data, content generation, audience research, catalog management — via MCP." +description: "The CLI for music. Spotify data, content generation, audience research, catalog management — from your terminal or any AI agent." --- -# The MCP server for music +# The CLI for Music -Recoup gives your agent access to the music industry. Spotify data, artist research, content generation, audience analytics, YouTube revenue, catalog management, and more — 40+ tools, one connection. +Search Spotify. Generate content. Analyze audiences. Manage catalogs. Run release campaigns. From your terminal, your AI agent, or any MCP client. -Every tool is context-aware. Recoup knows the artist, the catalog, the audience, and the release history. Your agent gets music-specific results that generic tools can't match. +```bash +npm install -g @recoupable/cli +``` -## Connect in 30 seconds +## Get started - + + ```bash + npm install -g @recoupable/cli + export RECOUP_API_KEY=your-api-key + recoup whoami + ``` + + Then start working: + + ```bash + recoup artists list + recoup content templates + recoup content create --artist --template artist-caption-bedroom + ``` + + [Full CLI docs →](/cli) + + Add to `.cursor/mcp.json`: ```json @@ -28,7 +47,7 @@ Every tool is context-aware. Recoup knows the artist, the catalog, the audience, } ``` - + ```bash claude mcp add recoup \ --transport http \ @@ -36,23 +55,7 @@ Every tool is context-aware. Recoup knows the artist, the catalog, the audience, --header "Authorization: Bearer YOUR_API_KEY" ``` - - Pre-connected in Recoup sandboxes. Outside a sandbox: - - ```json - { - "mcpServers": { - "recoup": { - "url": "https://recoup-api.vercel.app/mcp", - "headers": { - "Authorization": "Bearer YOUR_API_KEY" - } - } - } - } - ``` - - + Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json @@ -68,38 +71,44 @@ Every tool is context-aware. Recoup knows the artist, the catalog, the audience, } ``` - - ``` - Server URL: https://recoup-api.vercel.app/mcp - Auth: Bearer token in Authorization header + + ```bash + curl "https://api.recoupable.com/api/spotify/search?q=Mac%20Miller&type=artist" \ + -H "x-api-key: YOUR_API_KEY" ``` + + [API reference →](/api-reference/introduction) Get your API key → [chat.recoupable.com/keys](https://chat.recoupable.com/keys) -## What your agent can do +## What you get Search artists, albums, tracks. Pull discographies, top tracks by country, album details. Deep artist research. - `get_spotify_search` · `get_spotify_artist_albums` · `get_spotify_artist_top_tracks` · `spotify_deep_research` + ```bash + recoup spotify search "Mac Miller" + ``` - - Channel info, video lists, estimated revenue, custom thumbnails, auth status. + + Generate social-ready videos from artist songs, face guide, and brand context. Single or batch 30. - `get_youtube_channels` · `get_youtube_channel_video_list` · `get_youtube_revenue` · `set_youtube_thumbnail` + ```bash + recoup content create --artist --lipsync + ``` - - Generate social-ready videos from artist songs, face guide, and brand context. Single or batch. Lipsync, upscale, custom captions. + + Channel info, video lists, estimated revenue, custom thumbnails. - `prompt_sandbox` · via [CLI](/cli) or [Slack](/content-agent) + `get_youtube_channels` · `get_youtube_channel_video_list` · `get_youtube_revenue` - Deep cross-platform artist research. Web search. Google Images. Multi-source analysis reports. + Deep cross-platform artist research. Web search. Multi-source analysis. - `artist_deep_research` · `web_deep_research` · `search_web` · `search_google_images` + `artist_deep_research` · `web_deep_research` · `search_web` Generate images from prompts. Edit existing images. Generate video with Sora 2. @@ -114,7 +123,9 @@ Get your API key → [chat.recoupable.com/keys](https://chat.recoupable.com/keys Create scheduled tasks, monitor runs, automate recurring operations. - `create_task` · `get_tasks` · `update_task` · `get_task_run_status` + ```bash + recoup tasks status --run + ``` Query catalogs, find songs by ISRC, add tracks in batch. @@ -123,52 +134,30 @@ Get your API key → [chat.recoupable.com/keys](https://chat.recoupable.com/keys -[See all 40+ tools with full descriptions →](/mcp) - -## Example: what an agent call looks like - -Ask your agent: - -``` -"Find Mac Miller on Spotify and show me his top 5 tracks" -``` +[See all 40+ tools →](/mcp) -The agent calls `get_spotify_search` with `{ "query": "Mac Miller", "type": "artist" }`, then `get_spotify_artist_top_tracks` with the artist ID. You get back track names, popularity scores, album info, and preview URLs — real Spotify data, not a web scrape. - -## Why agents pick Recoup +## Why Recoup - Not a generic API adapted for music. Built for artists, catalogs, releases, and fans from day one. + Not a generic API with a music skin. Built for artists, catalogs, releases, and fans. - Every tool knows the artist's songs, brand voice, audience data, and history. Output is artist-specific, not generic. + Every tool knows the artist's songs, brand voice, audience, and history. Output is artist-specific. - - Spotify, YouTube, Instagram, content generation, analytics, tasks, sandboxes — all through one MCP server. - - - -## Also available as - - - - Direct HTTP access. Same tools, same data. - - `https://api.recoupable.com/api` - - - Terminal workflows, scripting, automation. - - `npm install -g @recoupable/cli` + + Spotify, YouTube, Instagram, content generation, analytics, tasks — all through one CLI or one MCP connection. ## Next steps - - All 40+ MCP tools with descriptions, inputs, and examples. + + Content workflows, artist management, task monitoring. + + + All 40+ tools with descriptions and inputs. Why Recoup output is artist-specific, not generic AI. @@ -176,7 +165,4 @@ The agent calls `get_spotify_search` with `{ "query": "Mac Miller", "type": "art API key + first request in 5 minutes. - - Generate videos from Slack with a single @mention. - From a243402e0a8a0797495ed41bdfec176c106816a7 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:21:21 -0400 Subject: [PATCH 09/13] docs: headline to 'Music Industry Tools for AI Agents' Made-with: Cursor --- index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.mdx b/index.mdx index 2409ca4..975c880 100644 --- a/index.mdx +++ b/index.mdx @@ -1,11 +1,11 @@ --- title: "Recoup" -description: "The CLI for music. Spotify data, content generation, audience research, catalog management — from your terminal or any AI agent." +description: "Music industry tools for AI agents. Spotify data, content generation, audience research, catalog management — via MCP and CLI." --- -# The CLI for Music +# Music Industry Tools for AI Agents -Search Spotify. Generate content. Analyze audiences. Manage catalogs. Run release campaigns. From your terminal, your AI agent, or any MCP client. +Spotify data. Content generation. Audience research. Catalog management. YouTube analytics. 40+ tools, one connection. Install the CLI or connect via MCP. ```bash npm install -g @recoupable/cli From 95f9e4bc8c9148e84b4dd95442a0ca31efa2eb58 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:23:33 -0400 Subject: [PATCH 10/13] docs: merge Get Started and Integrate into one nav group Made-with: Cursor --- docs.json | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs.json b/docs.json index d61bc2f..7bc70af 100644 --- a/docs.json +++ b/docs.json @@ -18,15 +18,10 @@ "pages": [ "index", "quickstart", - "how-it-works", - "authentication" - ] - }, - { - "group": "Integrate", - "pages": [ "mcp", "cli", + "how-it-works", + "authentication", "content-agent" ] } From ca33ffe8bcc0c5cd4dec8c6daf99d465fc400ff8 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:28:38 -0400 Subject: [PATCH 11/13] =?UTF-8?q?docs:=20add=20llms.txt=20=E2=80=94=20comp?= =?UTF-8?q?lete=20tool=20reference=20for=20AI=20agents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 43 MCP tools with descriptions, params, and types. 13 CLI commands with flags. Connection instructions for MCP/API/CLI. Single-file reference that agents can fetch in one request. Made-with: Cursor --- llms.txt | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 llms.txt diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..4ccb48a --- /dev/null +++ b/llms.txt @@ -0,0 +1,123 @@ +# Recoup + +> Music industry tools for AI agents. Spotify data, content generation, audience research, catalog management, YouTube analytics — via MCP server and CLI. + +## Connect + +MCP server: https://recoup-api.vercel.app/mcp +REST API: https://api.recoupable.com/api +CLI: npm install -g @recoupable/cli + +Auth: API key from https://chat.recoupable.com/keys +- MCP: Bearer token in Authorization header +- REST API: x-api-key header +- CLI: RECOUP_API_KEY environment variable + +## Docs + +- [Welcome](https://developers.recoupable.com/): Overview, connect instructions, tool list +- [Quickstart](https://developers.recoupable.com/quickstart): API key setup, first request +- [MCP](https://developers.recoupable.com/mcp): Full MCP tool reference with all 43 tools +- [CLI](https://developers.recoupable.com/cli): CLI command reference and workflows +- [How It Works](https://developers.recoupable.com/how-it-works): Agents, sandboxes, context architecture +- [Authentication](https://developers.recoupable.com/authentication): API keys, MCP auth, CLI auth, org access +- [Content Agent](https://developers.recoupable.com/content-agent): Slack bot for video generation +- [API Reference](https://developers.recoupable.com/api-reference/introduction): REST API endpoint docs + +## MCP Tools (43 total) + +### Spotify +- get_spotify_search: Search for artists, albums, tracks, playlists by name. Params: name (required), type (required, array of: artist/album/track/playlist/show/episode/audiobook), limit (optional, 1-50) +- get_spotify_artist_albums: Get an artist's album catalog. Params: id (required), include_groups (optional), market (optional), limit (optional, 1-50), offset (optional) +- get_spotify_artist_top_tracks: Get an artist's top tracks by country. Params: id (required), market (optional, 2-char country code) +- get_spotify_album: Get album details. Params: id (required), market (optional) +- spotify_deep_research: Deep research on an artist using Spotify ID — popularity scores, follower metrics, engagement, tracklist, collaborators. Params: artist_account_id (required) + +### YouTube +- get_youtube_channels: Get YouTube channel info for an account. Params: artist_account_id (required) +- get_youtube_channel_video_list: List videos for a channel. Params: artist_account_id (required), uploads_playlist_id (required), max_results (optional, 1-50) +- get_youtube_revenue: Get estimated revenue for a date range. Params: artist_account_id (required), startDate (optional, YYYY-MM-DD), endDate (optional, YYYY-MM-DD) +- set_youtube_thumbnail: Set custom video thumbnail. Params: artist_account_id (required), video_id (required), thumbnail_url (required) +- youtube_login: Check YouTube auth status. Params: artist_account_id (required) + +### Research +- artist_deep_research: Comprehensive cross-platform artist research — Spotify, socials, website, YouTube, marketing opportunities. Params: artist_account_id (required) +- web_deep_research: Deep multi-source web research. Params: messages (required, array of {role, content}) +- search_web: Web search for real-time information. Params: query (required), max_results (optional, 1-20), country (optional) +- search_google_images: Search Google Images for existing photos. Params: query (required), limit (optional, 1-100), imageSize (optional), imageType (optional), aspectRatio (optional) + +### Content & Images +- generate_image: Generate image from text prompt. Params: prompt (required, 1-1000 chars), account_id (required) +- edit_image: Edit an existing image. Params: prompt (required), account_id (required), imageUrl (required, URL) +- generate_sora_2_video: Generate video with OpenAI Sora 2. Params: prompt (required), seconds (optional, 4-20), size (optional, 720x1280 or 1280x720) +- retrieve_sora_2_video: Check video generation status. Params: video_id (required) +- retrieve_sora_2_video_content: Download rendered video. Params: video_id (required) + +### Audio & Music +- transcribe_audio: Transcribe audio with Whisper. Params: audio_url (required), account_id (required), artist_account_id (required), title (optional), include_timestamps (optional) +- analyze_music: Analyze music with Recoup's Audio Language Model. Params: preset OR prompt (one required), audio_url (optional), max_new_tokens (optional), temperature (optional). Presets: catalog_metadata, mood_tags, lyric_transcription, mix_feedback, song_description, music_theory, similar_artists, sample_detection, sync_brief_match, audience_profile, content_advisory, playlist_pitch, artist_development_notes, full_report + +### Artists & Socials +- create_new_artist: Create a new artist account. Params: name (required), account_id (optional), active_conversation_id (optional), organization_id (optional) +- get_artist_socials: Get all social profiles for an artist. Params: artist_account_id (required), page (optional), limit (optional, 1-100) +- update_artist_socials: Update social profiles from URLs. Params: artistId (required), urls (required, string array) +- update_account_info: Update artist profile, name, instructions, label, knowledge base. Params: artistId (required), image/name/instruction/label/knowledges (all optional) +- create_segments: Analyze fan data and create audience segments. Params: artist_account_id (required), prompt (required) + +### Catalogs & Songs +- select_catalogs: Get catalogs for an account. Params: account_id (required) +- select_catalog_songs: Find songs from catalog by criteria. Params: catalog_id (required), criteria (required) +- insert_catalog_songs: Add songs to catalog by ISRC. Params: songs (required, array of {catalog_id, isrc}) + +### Chat +- get_chats: Get chat conversations. Params: account_id (optional), artist_account_id (optional) +- compact_chats: Summarize conversations. Params: chat_id (required, string array), prompt (optional) + +### Tasks & Scheduling +- create_task: Create a scheduled task. Params: title (required), prompt (required), schedule (required, cron), account_id (required), artist_account_id (required), model (optional) +- get_tasks: List tasks. Params: account_id (optional), artist_account_id (optional), enabled (optional), id (optional) +- update_task: Update a task. Params: id (required), title/prompt/schedule/account_id/artist_account_id/enabled/model (all optional) +- delete_task: Delete a task. Params: id (required) +- get_task_run_status: Check task run status. Params: runId (required) + +### Pulses +- get_pulses: Get pulse statuses. Params: active (optional, boolean) +- update_pulse: Update pulse status. Params: active (required, boolean) + +### Files & Knowledge +- generate_txt_file: Create downloadable text file stored on Arweave. Params: contents (required) +- create_knowledge_base: Save knowledge base entry to artist's permanent storage. Params: artistId (required), knowledgeBaseText (required) + +### Communication +- send_email: Send email via Resend. Params: to (required, email array), subject (required), room_id (required), text (optional), html (optional), cc (optional), headers (optional) +- contact_team: Message Recoup support. Params: message (required, 1-1000 chars) + +### Sandboxes +- prompt_sandbox: Send prompt to persistent agent sandbox. Params: prompt (required) + +### Utilities +- get_local_time: Get current time/date. Params: timezone (optional, IANA) + +## CLI Commands + +- recoup whoami: Show authenticated account +- recoup artists list: List artists (flags: --org, --account, --json) +- recoup orgs list: List organizations (flags: --account, --json) +- recoup chats list: List chats (flag: --json) +- recoup chats create: Create chat (flags: --name, --artist) +- recoup content templates: List content templates +- recoup content validate: Check artist readiness (flag: --artist) +- recoup content estimate: Preview cost/duration (flags: --artist, --template, --lipsync, --upscale) +- recoup content create: Trigger content creation (flags: --artist, --template, --lipsync, --upscale, --caption-length, --songs) +- recoup tasks status: Check task run status (flag: --run) +- recoup sandboxes list: List sandboxes +- recoup sandboxes create: Create sandbox (flag: --command) +- recoup notifications: Send email (flags: --subject, --text, --html, --cc, --room-id, --account) + +## Why Recoup + +General purpose AI tools don't know the artist, the catalog, the audience, or the release history. Recoup does. Every tool is context-aware — it reads artist files (songs, brand voice, audience data) before acting. The output is artist-specific, not generic. + +- Music-specific: Built for artists, catalogs, releases, and fans — not a generic API with a music skin +- Context-aware: Every tool knows the artist's songs, brand voice, audience, and history +- One connection: Spotify, YouTube, content generation, analytics, tasks, sandboxes — all through one MCP server From 9594033af9d2430fa7e33d614a32cf951c9780a7 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 23:40:50 -0400 Subject: [PATCH 12/13] fix: hyphenate General-purpose per CodeRabbit review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixed compound adjective in how-it-works.mdx and index.mdx. Other CodeRabbit comments addressed: - introduction.mdx narrative: this is a landing page, not an endpoint page — frontmatter-only rule doesn't apply here - Duplicated API key blocks: minor overlap across quickstart, auth, and MCP pages — each is contextual, not worth a snippet for 2-3 lines Made-with: Cursor --- how-it-works.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/how-it-works.mdx b/how-it-works.mdx index 7dbcc48..e82338e 100644 --- a/how-it-works.mdx +++ b/how-it-works.mdx @@ -3,7 +3,7 @@ title: "How It Works" description: "Agents, sandboxes, context, and the architecture behind Recoup." --- -General purpose AI tools don't know the artist, the catalog, the audience, or the history. Recoup does. You give it artist context — songs, brand voice, audience data, release history — and it deploys agents that run operations using that context. That's the edge: every feature is so context-aware that you'd never go back to ChatGPT or doing it by hand. +General-purpose AI tools don't know the artist, the catalog, the audience, or the history. Recoup does. You give it artist context — songs, brand voice, audience data, release history — and it deploys agents that run operations using that context. That's the edge: every feature is so context-aware that you'd never go back to ChatGPT or doing it by hand. ## The Three Layers @@ -84,7 +84,7 @@ Sandboxes are how Recoup moves from "suggesting" to "doing." The agent doesn't j ## Why not ChatGPT -General purpose agents can generate a marketing plan for any artist. Recoup agents generate a marketing plan for *your* artist — using their actual songs, their real audience data, their brand voice, their release history. +General-purpose agents can generate a marketing plan for any artist. Recoup agents generate a marketing plan for *your* artist — using their actual songs, their real audience data, their brand voice, their release history. | Generic AI | Recoup | |------------|--------| From 03775468518b28c551bd435849da853ead309897 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 23:41:31 -0400 Subject: [PATCH 13/13] remove llms.txt Made-with: Cursor --- llms.txt | 123 ------------------------------------------------------- 1 file changed, 123 deletions(-) delete mode 100644 llms.txt diff --git a/llms.txt b/llms.txt deleted file mode 100644 index 4ccb48a..0000000 --- a/llms.txt +++ /dev/null @@ -1,123 +0,0 @@ -# Recoup - -> Music industry tools for AI agents. Spotify data, content generation, audience research, catalog management, YouTube analytics — via MCP server and CLI. - -## Connect - -MCP server: https://recoup-api.vercel.app/mcp -REST API: https://api.recoupable.com/api -CLI: npm install -g @recoupable/cli - -Auth: API key from https://chat.recoupable.com/keys -- MCP: Bearer token in Authorization header -- REST API: x-api-key header -- CLI: RECOUP_API_KEY environment variable - -## Docs - -- [Welcome](https://developers.recoupable.com/): Overview, connect instructions, tool list -- [Quickstart](https://developers.recoupable.com/quickstart): API key setup, first request -- [MCP](https://developers.recoupable.com/mcp): Full MCP tool reference with all 43 tools -- [CLI](https://developers.recoupable.com/cli): CLI command reference and workflows -- [How It Works](https://developers.recoupable.com/how-it-works): Agents, sandboxes, context architecture -- [Authentication](https://developers.recoupable.com/authentication): API keys, MCP auth, CLI auth, org access -- [Content Agent](https://developers.recoupable.com/content-agent): Slack bot for video generation -- [API Reference](https://developers.recoupable.com/api-reference/introduction): REST API endpoint docs - -## MCP Tools (43 total) - -### Spotify -- get_spotify_search: Search for artists, albums, tracks, playlists by name. Params: name (required), type (required, array of: artist/album/track/playlist/show/episode/audiobook), limit (optional, 1-50) -- get_spotify_artist_albums: Get an artist's album catalog. Params: id (required), include_groups (optional), market (optional), limit (optional, 1-50), offset (optional) -- get_spotify_artist_top_tracks: Get an artist's top tracks by country. Params: id (required), market (optional, 2-char country code) -- get_spotify_album: Get album details. Params: id (required), market (optional) -- spotify_deep_research: Deep research on an artist using Spotify ID — popularity scores, follower metrics, engagement, tracklist, collaborators. Params: artist_account_id (required) - -### YouTube -- get_youtube_channels: Get YouTube channel info for an account. Params: artist_account_id (required) -- get_youtube_channel_video_list: List videos for a channel. Params: artist_account_id (required), uploads_playlist_id (required), max_results (optional, 1-50) -- get_youtube_revenue: Get estimated revenue for a date range. Params: artist_account_id (required), startDate (optional, YYYY-MM-DD), endDate (optional, YYYY-MM-DD) -- set_youtube_thumbnail: Set custom video thumbnail. Params: artist_account_id (required), video_id (required), thumbnail_url (required) -- youtube_login: Check YouTube auth status. Params: artist_account_id (required) - -### Research -- artist_deep_research: Comprehensive cross-platform artist research — Spotify, socials, website, YouTube, marketing opportunities. Params: artist_account_id (required) -- web_deep_research: Deep multi-source web research. Params: messages (required, array of {role, content}) -- search_web: Web search for real-time information. Params: query (required), max_results (optional, 1-20), country (optional) -- search_google_images: Search Google Images for existing photos. Params: query (required), limit (optional, 1-100), imageSize (optional), imageType (optional), aspectRatio (optional) - -### Content & Images -- generate_image: Generate image from text prompt. Params: prompt (required, 1-1000 chars), account_id (required) -- edit_image: Edit an existing image. Params: prompt (required), account_id (required), imageUrl (required, URL) -- generate_sora_2_video: Generate video with OpenAI Sora 2. Params: prompt (required), seconds (optional, 4-20), size (optional, 720x1280 or 1280x720) -- retrieve_sora_2_video: Check video generation status. Params: video_id (required) -- retrieve_sora_2_video_content: Download rendered video. Params: video_id (required) - -### Audio & Music -- transcribe_audio: Transcribe audio with Whisper. Params: audio_url (required), account_id (required), artist_account_id (required), title (optional), include_timestamps (optional) -- analyze_music: Analyze music with Recoup's Audio Language Model. Params: preset OR prompt (one required), audio_url (optional), max_new_tokens (optional), temperature (optional). Presets: catalog_metadata, mood_tags, lyric_transcription, mix_feedback, song_description, music_theory, similar_artists, sample_detection, sync_brief_match, audience_profile, content_advisory, playlist_pitch, artist_development_notes, full_report - -### Artists & Socials -- create_new_artist: Create a new artist account. Params: name (required), account_id (optional), active_conversation_id (optional), organization_id (optional) -- get_artist_socials: Get all social profiles for an artist. Params: artist_account_id (required), page (optional), limit (optional, 1-100) -- update_artist_socials: Update social profiles from URLs. Params: artistId (required), urls (required, string array) -- update_account_info: Update artist profile, name, instructions, label, knowledge base. Params: artistId (required), image/name/instruction/label/knowledges (all optional) -- create_segments: Analyze fan data and create audience segments. Params: artist_account_id (required), prompt (required) - -### Catalogs & Songs -- select_catalogs: Get catalogs for an account. Params: account_id (required) -- select_catalog_songs: Find songs from catalog by criteria. Params: catalog_id (required), criteria (required) -- insert_catalog_songs: Add songs to catalog by ISRC. Params: songs (required, array of {catalog_id, isrc}) - -### Chat -- get_chats: Get chat conversations. Params: account_id (optional), artist_account_id (optional) -- compact_chats: Summarize conversations. Params: chat_id (required, string array), prompt (optional) - -### Tasks & Scheduling -- create_task: Create a scheduled task. Params: title (required), prompt (required), schedule (required, cron), account_id (required), artist_account_id (required), model (optional) -- get_tasks: List tasks. Params: account_id (optional), artist_account_id (optional), enabled (optional), id (optional) -- update_task: Update a task. Params: id (required), title/prompt/schedule/account_id/artist_account_id/enabled/model (all optional) -- delete_task: Delete a task. Params: id (required) -- get_task_run_status: Check task run status. Params: runId (required) - -### Pulses -- get_pulses: Get pulse statuses. Params: active (optional, boolean) -- update_pulse: Update pulse status. Params: active (required, boolean) - -### Files & Knowledge -- generate_txt_file: Create downloadable text file stored on Arweave. Params: contents (required) -- create_knowledge_base: Save knowledge base entry to artist's permanent storage. Params: artistId (required), knowledgeBaseText (required) - -### Communication -- send_email: Send email via Resend. Params: to (required, email array), subject (required), room_id (required), text (optional), html (optional), cc (optional), headers (optional) -- contact_team: Message Recoup support. Params: message (required, 1-1000 chars) - -### Sandboxes -- prompt_sandbox: Send prompt to persistent agent sandbox. Params: prompt (required) - -### Utilities -- get_local_time: Get current time/date. Params: timezone (optional, IANA) - -## CLI Commands - -- recoup whoami: Show authenticated account -- recoup artists list: List artists (flags: --org, --account, --json) -- recoup orgs list: List organizations (flags: --account, --json) -- recoup chats list: List chats (flag: --json) -- recoup chats create: Create chat (flags: --name, --artist) -- recoup content templates: List content templates -- recoup content validate: Check artist readiness (flag: --artist) -- recoup content estimate: Preview cost/duration (flags: --artist, --template, --lipsync, --upscale) -- recoup content create: Trigger content creation (flags: --artist, --template, --lipsync, --upscale, --caption-length, --songs) -- recoup tasks status: Check task run status (flag: --run) -- recoup sandboxes list: List sandboxes -- recoup sandboxes create: Create sandbox (flag: --command) -- recoup notifications: Send email (flags: --subject, --text, --html, --cc, --room-id, --account) - -## Why Recoup - -General purpose AI tools don't know the artist, the catalog, the audience, or the release history. Recoup does. Every tool is context-aware — it reads artist files (songs, brand voice, audience data) before acting. The output is artist-specific, not generic. - -- Music-specific: Built for artists, catalogs, releases, and fans — not a generic API with a music skin -- Context-aware: Every tool knows the artist's songs, brand voice, audience, and history -- One connection: Spotify, YouTube, content generation, analytics, tasks, sandboxes — all through one MCP server