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..7bc70af 100644 --- a/docs.json +++ b/docs.json @@ -14,29 +14,24 @@ "tab": "Guides", "groups": [ { - "group": "Getting started", + "group": "Get Started", "pages": [ "index", "quickstart", - "cli", "mcp", + "cli", + "how-it-works", "authentication", - "api-reference/sandboxes/create" - ] - }, - { - "group": "Agents", - "pages": [ "content-agent" ] } ] }, { - "tab": "API reference", + "tab": "API Reference", "groups": [ { - "group": "API documentation", + "group": "Overview", "pages": [ "api-reference/introduction" ] @@ -265,19 +260,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..e82338e --- /dev/null +++ b/how-it-works.mdx @@ -0,0 +1,95 @@ +--- +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. + +## The Three Layers + + + + 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 + +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 + + + + 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 + +| 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) | + +## 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. + +| 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 05c0125..975c880 100644 --- a/index.mdx +++ b/index.mdx @@ -1,102 +1,168 @@ --- -title: "Recoup API Documentation" -description: "Use the Recoup API to build your record label." +title: "Recoup" +description: "Music industry tools for AI agents. Spotify data, content generation, audience research, catalog management — via MCP and CLI." --- -# Welcome to the Recoup API +# Music Industry Tools for AI 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. +Spotify data. Content generation. Audience research. Catalog management. YouTube analytics. 40+ tools, one connection. Install the CLI or connect via MCP. -## What is Recoup? +```bash +npm install -g @recoupable/cli +``` -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. +## Get started -This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. + + + ```bash + npm install -g @recoupable/cli + export RECOUP_API_KEY=your-api-key + recoup whoami + ``` -## Get Started + 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 + { + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + + ```bash + claude mcp add recoup \ + --transport http \ + --url https://recoup-api.vercel.app/mcp \ + --header "Authorization: Bearer YOUR_API_KEY" + ``` + + + Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: + + ```json + { + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + + ```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 you get - - Get your API key and make your first request in minutes. + + Search artists, albums, tracks. Pull discographies, top tracks by country, album details. Deep artist research. + + ```bash + recoup spotify search "Mac Miller" + ``` - - Explore all available endpoints and integrations. + + Generate social-ready videos from artist songs, face guide, and brand context. Single or batch 30. + + ```bash + recoup content create --artist --lipsync + ``` - + + Channel info, video lists, estimated revenue, custom thumbnails. -## Key Capabilities + `get_youtube_channels` · `get_youtube_channel_video_list` · `get_youtube_revenue` + + + Deep cross-platform artist research. Web search. Multi-source analysis. - - - AI-powered conversations with artist context. Stream responses or generate complete messages. + `artist_deep_research` · `web_deep_research` · `search_web` - - Comprehensive artist profiles with social metrics, follower counts, and engagement data across platforms. + + Generate images from prompts. Edit existing images. Generate video with Sora 2. + + `generate_image` · `edit_image` · `generate_sora_2_video` + + + Transcribe audio with Whisper. Analyze music with Recoup's Audio Language Model. + + `transcribe_audio` · `analyze_music` - - Organize and analyze fan bases by demographics, engagement levels, and behavior patterns. + + Create scheduled tasks, monitor runs, automate recurring operations. + + ```bash + recoup tasks status --run + ``` - - Schedule and automate recurring tasks with cron-based scheduling and AI-powered execution. + + Query catalogs, find songs by ISRC, add tracks in batch. + + `select_catalogs` · `select_catalog_songs` · `insert_catalog_songs` -## Platform Integrations +[See all 40+ tools →](/mcp) + +## Why Recoup - - Search artists, albums, and tracks. + + Not a generic API with a music skin. Built for artists, catalogs, releases, and fans. - - Scrape profiles and comments. + + Every tool knows the artist's songs, brand voice, audience, and history. Output is artist-specific. - - Search tweets and trending topics. + + Spotify, YouTube, Instagram, content generation, analytics, tasks — all through one CLI or one MCP connection. -## Need Help? +## Next steps - - Reach out to our team for assistance with the Recoup API. - + + + Content workflows, artist management, task monitoring. + + + All 40+ tools with descriptions and inputs. + + + Why Recoup output is artist-specific, not generic AI. + + + API key + first request in 5 minutes. + + 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).