recoupable · sweetmantech · Mar 24, 2026 · Mar 24, 2026 · Mar 26, 2026 · Mar 26, 2026
@@ -1,67 +1,20 @@
 ---
-title: 'Introduction'
-description: 'API documentation for the Recoup platform - AI agents for the music industry'
+title: 'API Reference'
+description: 'Complete reference for all Recoup API endpoints.'
 ---
 
-## Welcome
+## Base URL
+
+```
+https://api.recoupable.com/api
+```
 
-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.
+All endpoints require authentication. See the [Authentication guide](/authentication) for how to pass your API key or Bearer token.
 
 <Card
   title="View OpenAPI Specification"
   icon="code"
   href="https://github.com/sweetmantech/docs/blob/main/api-reference/openapi.json"
 >
-  View the OpenAPI specification file on GitHub
+  View the full OpenAPI spec on GitHub
 </Card>
-
-## Base URL
-
-All API requests should be made to:
-
-```bash
-https://api.recoupable.com/api
-```
-
-## Authentication
-
-All API endpoints are authenticated using an API key passed in the `x-api-key` header.
-
-### Getting Your API Key
-
-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)
-
-### Using Your API Key
-
-Include your API key in the `x-api-key` header for all requests:
-
-```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"
-```
-
-<Warning>
-Keep your API key secure. Do not share it publicly or commit it to version control.
-</Warning>
-
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card
-    title="Quickstart"
-    icon="rocket"
-    href="/quickstart"
-  >
-    Get started with your first API request
-  </Card>
-  <Card
-    title="API Reference"
-    icon="book"
-    href="/api-reference/artists/list"
-  >
-    Explore all available endpoints
-  </Card>
-</CardGroup>
@@ -18,9 +18,10 @@
             "pages": [
               "index",
               "quickstart",
-              "cli",
-              "mcp",
               "authentication",
+              "mcp",
+              "mcp-tools",
+              "cli",
               "api-reference/sandboxes/create"
             ]
           }

@@ -1,102 +1,103 @@
 ---
 title: "Recoup API Documentation"
-description: "Use the Recoup API to build your record label."
+description: "Build AI-powered tools for the music industry — artist analytics, fan segmentation, chat agents, and task automation."
 ---
 
 # Welcome to the Recoup API
 
-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 is an AI agent platform for record labels, artists, and managers. Use the API to build intelligent automations, fan-facing experiences, and data-driven workflows on top of Recoup infrastructure.
 
-## What is Recoup?
+## Choose your integration path
 
-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.
-
-This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.
-
-## Get Started
-
-<CardGroup cols={2}>
+<CardGroup cols={3}>
   <Card
-    title="Quickstart"
-    icon="rocket"
+    title="REST API"
+    icon="code"
     href="/quickstart"
   >
-    Get your API key and make your first request in minutes.
+    Make HTTP requests with your API key. Best for server-side integrations and custom tooling.
   </Card>
   <Card
-    title="API Reference"
-    icon="code"
-    href="/api-reference/introduction"
+    title="MCP Server"
+    icon="robot"
+    href="/mcp"
+  >
+    Connect AI agents (Claude, Cursor, VS Code) directly to Recoup tools via the Model Context Protocol.
+  </Card>
+  <Card
+    title="CLI"
+    icon="terminal"
+    href="/cli"
   >
-    Explore all available endpoints and integrations.
+    Run Recoup commands from your terminal. Useful for scripting and local development.
   </Card>
 </CardGroup>
 
-## Key Capabilities
+## What you can build
 
 <CardGroup cols={2}>
   <Card
-    title="Chat API"
-    icon="comments"
-    href="/api-reference/chat/chats"
+    title="Artist Intelligence"
+    icon="chart-line"
+    href="/api-reference/artist/profile"
   >
-    AI-powered conversations with artist context. Stream responses or generate complete messages.
+    Pull social metrics, follower counts, and engagement data across Spotify, Instagram, X, and YouTube.
   </Card>
   <Card
-    title="Artist Analytics"
-    icon="chart-line"
-    href="/api-reference/artist/profile"
+    title="AI Chat Agents"
+    icon="comments"
+    href="/api-reference/chat/chats"
   >
-    Comprehensive artist profiles with social metrics, follower counts, and engagement data across platforms.
+    Build streaming AI conversations with full artist context and persistent memory.
   </Card>
   <Card
     title="Fan Segmentation"
     icon="users"
     href="/api-reference/segment/fans"
   >
-    Organize and analyze fan bases by demographics, engagement levels, and behavior patterns.
+    Segment audiences by demographics, engagement, and behavior for targeted campaigns.
   </Card>
   <Card
-    title="Task Management"
+    title="Automated Tasks"
     icon="list-check"
     href="/api-reference/tasks/get"
   >
-    Schedule and automate recurring tasks with cron-based scheduling and AI-powered execution.
+    Schedule recurring AI-powered jobs — daily reports, fan outreach, content generation, and more.
   </Card>
 </CardGroup>
 
-## Platform Integrations
+## Platform integrations
 
 <CardGroup cols={3}>
   <Card
     title="Spotify"
     icon="spotify"
     href="/api-reference/spotify/search"
   >
-    Search artists, albums, and tracks.
+    Search artists, albums, tracks. Pull top tracks and revenue data.
   </Card>
   <Card
     title="Instagram"
     icon="instagram"
     href="/api-reference/instagram/profiles"
   >
-    Scrape profiles and comments.
+    Scrape profiles and comments for fan intelligence.
   </Card>
   <Card
     title="X (Twitter)"
     icon="x-twitter"
     href="/api-reference/x/search"
   >
-    Search tweets and trending topics.
+    Search tweets and trending topics in real time.
   </Card>
 </CardGroup>
 
-## Need Help?
+## Need help?
 
 <Card
   title="Contact Support"
   icon="envelope"
   href="mailto:agent@recoupable.com"
 >
-  Reach out to our team for assistance with the Recoup API.
+  Reach out to our team at agent@recoupable.com
 </Card>
@@ -0,0 +1,136 @@
+---
+title: "MCP Tool Reference"
+description: "Complete list of tools available through the Recoup MCP server."
+---
+
+Every tool listed here is callable through the [Recoup MCP server](/mcp). Connect your AI agent, then call any tool by name.
+
+<Info>
+  All tools require a valid API key. Get yours from the [API Keys page](https://chat.recoupable.com/keys).
+</Info>
+
+---
+
+## Artists
+
+| Tool | Description |
+|------|-------------|
+| `create_new_artist` | Create a new artist account. |
+| `get_artist_socials` | Get all social profiles linked to an artist. |
+| `update_artist_socials` | Set social profile URLs for an artist (platform auto-detected). |
+| `artist_deep_research` | Run comprehensive research on an artist across platforms. |
+| `update_account_info` | Update an artist's profile info (name, image, instructions, knowledge base). |
+
+## Chats
+
+| Tool | Description |
+|------|-------------|
+| `get_chats` | List chat conversations, optionally filtered by account or artist. |
+| `compact_chats` | Summarize one or more chat conversations into concise notes. |
+
+## Tasks
+
+| Tool | Description |
+|------|-------------|
+| `get_tasks` | List scheduled tasks, optionally filtered by account, artist, or enabled status. |
+| `create_task` | Create a new scheduled task. |
+| `update_task` | Update an existing task. |
+| `delete_task` | Delete a task by ID. |
+| `get_task_run_status` | Get the status of a Trigger.dev background task run. |
+
+## Pulses
+
+| Tool | Description |
+|------|-------------|
+| `get_pulses` | Get pulse statuses for accounts. |
+| `update_pulse` | Enable or disable the pulse for the authenticated account. |
+
+## Catalogs & Songs
+
+| Tool | Description |
+|------|-------------|
+| `select_catalogs` | List catalogs for an account. Call this first before recommending songs. |
+| `select_catalog_songs` | Find songs from a catalog matching given criteria. |
+| `insert_catalog_songs` | Add songs to a catalog by ISRC in batch. |
+
+## Spotify
+
+| Tool | Description |
+|------|-------------|
+| `get_spotify_search` | Search Spotify for artists, albums, tracks, playlists, shows, or episodes. |
+| `get_spotify_artist_albums` | Get an artist's albums from Spotify. |
+| `get_spotify_artist_top_tracks` | Get an artist's top tracks by market. |
+| `get_spotify_album` | Get details for a single Spotify album. |
+| `spotify_deep_research` | Deep-research an artist using their Spotify ID. |
+
+## YouTube
+
+| Tool | Description |
+|------|-------------|
+| `youtube_login` | Check YouTube authentication status for an artist. |
+| `get_youtube_channels` | Get YouTube channel info for an artist. |
+| `get_youtube_channel_video_list` | List videos from a YouTube channel's uploads playlist. |
+| `get_youtube_revenue` | Get estimated YouTube revenue data for a date range. |
+| `set_youtube_thumbnail` | Set a custom thumbnail for a YouTube video. |
+
+## Search & Research
+
+| Tool | Description |
+|------|-------------|
+| `search_web` | Search the web for real-time information via Perplexity. |
+| `search_google_images` | Search Google Images for photos or visual content. |
+| `web_deep_research` | Deep web research using Perplexity's `sonar-deep-research` model. |
+
+## Images
+
+| Tool | Description |
+|------|-------------|
+| `generate_image` | Generate an image from a text prompt. |
+| `edit_image` | Edit an existing image using a text prompt. |
+
+## Video
+
+| Tool | Description |
+|------|-------------|
+| `generate_sora_2_video` | Generate a video from a text prompt using OpenAI Sora 2. |
+| `retrieve_sora_2_video` | Get the status and details of a video generation job. |
+| `retrieve_sora_2_video_content` | Download the rendered video content. |
+
+## Audio
+
+| Tool | Description |
+|------|-------------|
+| `transcribe_audio` | Transcribe an audio file using OpenAI Whisper (MP3, WAV, M4A, WebM). |
+| `analyze_music` | Analyze a track using the Music Flamingo model (mood tags, metadata, sync briefs, etc.). |
+
+## Files & Knowledge
+
+| Tool | Description |
+|------|-------------|
+| `create_knowledge_base` | Save a plain-text knowledge base entry to an artist's permanent storage. |
+| `generate_txt_file` | Create a downloadable TXT file stored on Arweave. |
+
+## Communication
+
+| Tool | Description |
+|------|-------------|
+| `send_email` | Send an email via the Resend API. |
+| `contact_team` | Send a support message to the Recoup team. |
+
+## Segments
+
+| Tool | Description |
+|------|-------------|
+| `create_segments` | Analyze fan data and generate audience segments for an artist. |
+
+## Sandboxes
+
+| Tool | Description |
+|------|-------------|
+| `prompt_sandbox` | Run an OpenClaw prompt inside a persistent per-account sandbox. Returns `stdout`, `stderr`, `exitCode`, and the sandbox ID. |
+
+## Utilities
+
+| Tool | Description |
+|------|-------------|
+| `get_local_time` | Get the current date and time for a given IANA timezone. |