diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 057216c..95a557f 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -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. - View the OpenAPI specification file on GitHub + View the full OpenAPI spec on GitHub - -## 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" -``` - - -Keep your API key secure. Do not share it publicly or commit it to version control. - - -## Next Steps - - - - Get started with your first API request - - - Explore all available endpoints - - diff --git a/docs.json b/docs.json index 9361713..88d3519 100644 --- a/docs.json +++ b/docs.json @@ -18,9 +18,10 @@ "pages": [ "index", "quickstart", - "cli", - "mcp", "authentication", + "mcp", + "mcp-tools", + "cli", "api-reference/sandboxes/create" ] } diff --git a/index.mdx b/index.mdx index 05c0125..4a3edb0 100644 --- a/index.mdx +++ b/index.mdx @@ -1,71 +1,72 @@ --- 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 - - + - 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. + Connect AI agents (Claude, Cursor, VS Code) directly to Recoup tools via the Model Context Protocol. + + - Explore all available endpoints and integrations. + Run Recoup commands from your terminal. Useful for scripting and local development. -## Key Capabilities +## What you can build - 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. - Comprehensive artist profiles with social metrics, follower counts, and engagement data across platforms. + Build streaming AI conversations with full artist context and persistent memory. - Organize and analyze fan bases by demographics, engagement levels, and behavior patterns. + Segment audiences by demographics, engagement, and behavior for targeted campaigns. - 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. -## Platform Integrations +## Platform integrations - Search artists, albums, and tracks. + Search artists, albums, tracks. Pull top tracks and revenue data. - Scrape profiles and comments. + Scrape profiles and comments for fan intelligence. - Search tweets and trending topics. + Search tweets and trending topics in real time. -## Need Help? +## Need help? - Reach out to our team for assistance with the Recoup API. + Reach out to our team at agent@recoupable.com diff --git a/mcp-tools.mdx b/mcp-tools.mdx new file mode 100644 index 0000000..f006c08 --- /dev/null +++ b/mcp-tools.mdx @@ -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. + + + All tools require a valid API key. Get yours from the [API Keys page](https://chat.recoupable.com/keys). + + +--- + +## 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. | diff --git a/mcp.mdx b/mcp.mdx index 05709d8..cc7aad9 100644 --- a/mcp.mdx +++ b/mcp.mdx @@ -1,78 +1,177 @@ --- -title: "MCP" -description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP) server." +title: "MCP Servers" +description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP)." --- -The Recoup API exposes an [MCP](https://modelcontextprotocol.io/) server that AI agents can connect to for tool use. The server is available at: + + [MCP (Model Context Protocol)](https://modelcontextprotocol.io) is an open standard that lets AI assistants connect to external tools and data sources. Recoup exposes two MCP servers you can use today. + -``` -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 - -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. +## Choose your MCP server -Returns raw `stdout` and `stderr` from the command. The sandbox stays alive after each prompt for follow-up interactions. + + + Search and read the Recoup API docs directly from your AI assistant — powered by Mintlify. + + + Call 40+ Recoup tools (artists, Spotify, video, search, sandboxes, and more) from your AI agent. + + -**Input schema:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prompt` | `string` | Yes | The prompt to send to OpenClaw in the sandbox. | - -**Response fields:** +--- -| 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. | +## Docs Search MCP -**Example usage (TypeScript with MCP SDK):** +Every page in these docs includes an **MCP** button in the contextual menu (top-right of each page). Clicking it gives you a ready-to-use config snippet to add the Recoup docs as an MCP source in Claude, Cursor, VS Code, or any MCP-compatible client. -```typescript -import { Client } from "@modelcontextprotocol/sdk/client/index.js"; -import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; +This server is powered by Mintlify and lets AI assistants search and read the Recoup API documentation directly — useful for building integrations or answering questions about the API. -const transport = new StreamableHTTPClientTransport( - new URL("https://recoup-api.vercel.app/mcp"), - { requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } }, -); +--- -const client = new Client({ name: "my-agent", version: "1.0.0" }); -await client.connect(transport); +## Recoup API MCP Server -const result = await client.callTool({ - name: "prompt_sandbox", - arguments: { prompt: "list all files in the orgs directory" }, -}); +The Recoup API exposes an MCP server that AI agents can connect to for tool use: -console.log(result.content); +``` +https://recoup-api.vercel.app/mcp ``` -### run_sandbox_command - -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. - -See [`POST /api/sandboxes`](/api-reference/sandboxes/create) for the equivalent REST endpoint. +### Setup + + + + Go to the [API Keys page](https://chat.recoupable.com/keys), sign in, and create a new key. + + + Copy your key immediately — it is only shown once and cannot be retrieved after creation. + + + + Pick your AI client below and paste the config, replacing `YOUR_API_KEY` with your actual key. + + + + Add to your `claude_desktop_config.json` (found at `~/Library/Application Support/Claude/` on macOS): + + ```json + { + "mcpServers": { + "recoup": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "https://recoup-api.vercel.app/mcp", + "--header", + "Authorization:${AUTH_HEADER}" + ], + "env": { + "AUTH_HEADER": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + + Add to `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` globally: + + ```json + { + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + + Add to `.vscode/mcp.json` in your project, or to your user settings: + + ```json + { + "servers": { + "recoup": { + "type": "http", + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + + Install the MCP SDK and connect programmatically: + + ```typescript + import { Client } from "@modelcontextprotocol/sdk/client/index.js"; + import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; + + const transport = new StreamableHTTPClientTransport( + new URL("https://recoup-api.vercel.app/mcp"), + { requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } }, + ); + + const client = new Client({ name: "my-agent", version: "1.0.0" }); + await client.connect(transport); + ``` + + + + + Once connected, your AI agent can call any Recoup tool. Here are two examples using the TypeScript SDK: + + + + ```typescript Search the web + const result = await client.callTool({ + name: "search_web", + arguments: { query: "top hip hop releases this week", max_results: 5 }, + }); + console.log(result.content); + ``` + + ```typescript Run a sandbox prompt + const result = await client.callTool({ + name: "prompt_sandbox", + arguments: { prompt: "list all files in the orgs directory" }, + }); + console.log(result.content); + ``` + + + + -**Input schema:** +--- -| 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). | +## Available tools + +The Recoup MCP server exposes 40+ tools across these categories. See the [full tool reference](/mcp-tools) for details on every tool. + + + + Create artists, manage socials, run deep research. + + + Search, top tracks, albums, and deep research. + + + Channels, videos, revenue, and thumbnails. + + + Web search, image search, and deep research. + + + Generate and edit images, create Sora 2 videos. + + + Run prompts in persistent per-account sandboxes. + + diff --git a/quickstart.mdx b/quickstart.mdx index cc7e37b..fb0d409 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,159 +1,112 @@ --- title: "Quickstart" -description: "Get your API key and make your first request to the Recoup API." +description: "Get your API key and make your first request to the Recoup API in under 5 minutes." --- ## Base URL -All API requests should be made to: - -```bash +``` https://api.recoupable.com/api ``` -## 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 +## Step 1: Get an 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 [chat.recoupable.com/keys](https://chat.recoupable.com/keys) +2. Sign in to your account +3. Enter a name for your key (e.g. `"Development"`) and click **Create API Key** -Copy and securely store your API key immediately - it will only be shown once! +Copy your key immediately — it is only shown once and cannot be retrieved after creation. -### Step 3: Use Your API Key +## Step 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 Spotify for an artist — this works immediately with no additional setup: ```bash cURL -curl -X GET "https://api.recoupable.com/api/tasks" \ - -H "Content-Type: application/json" \ +curl "https://api.recoupable.com/api/spotify/search?q=Drake&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": "Drake", "type": "artist"}, + headers={"x-api-key": "YOUR_API_KEY"}, ) print(response.json()) ``` ```javascript JavaScript -const response = await fetch("https://api.recoupable.com/api/tasks", { - headers: { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY", - }, -}); +const response = await fetch( + "https://api.recoupable.com/api/spotify/search?q=Drake&type=artist", + { headers: { "x-api-key": "YOUR_API_KEY" } } +); const data = await response.json(); console.log(data); ``` -```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[]; -} - -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); -``` - -**Example Response:** +**Example response:** ```json { "status": "success", - "tasks": [ + "artists": [ { - "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 + "id": "3TVXtAsR1Inumwj472S9r4", + "name": "Drake", + "followers": 88000000, + "popularity": 96, + "genres": ["canadian hip hop", "rap"], + "image": "https://i.scdn.co/image/..." } ] } ``` - -For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). - - -## Next Steps - -With your API key ready, you can now: +## Step 3: Explore what's next - Fetch artist profiles, social accounts, and segments. - - - Access fan data across all connected social platforms. + Fetch an artist's full profile — social accounts, follower counts, and engagement data. - Build AI-powered conversations with artist context. + Build AI conversations with full artist context and streaming responses. - Schedule and automate recurring tasks. + Schedule recurring AI-powered jobs for reports, outreach, and content generation. + + + Connect Claude, Cursor, or VS Code directly to Recoup tools via MCP. -## Support +## Authentication reference + +All requests require your API key in the `x-api-key` header. For frontend apps using Privy, you can pass a Bearer token instead. See the [Authentication guide](/authentication) for full details. + +## Need help? -If you need help or have questions about the API, please contact our support team at [agent@recoupable.com](mailto:agent@recoupable.com). +Contact [agent@recoupable.com](mailto:agent@recoupable.com).