From 77c0e76223e7d78e8f17989e0bb5572688279abe Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 12 Apr 2026 15:38:16 -0400 Subject: [PATCH 01/24] feat: redesign docs with achromatic design system and sharper narrative MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Theme: mint → sequoia with achromatic colors, Plus Jakarta Sans headings, Inter body - Background: "windows" decoration, dark mode #080808, always-dark code blocks - Navigation: reorganized into Overview/Research/Releases/Content/Social/Platform tabs - Homepage: aligned with "music intelligence" positioning, 3-mode access pattern, LLM endpoint table - Quickstart: leads with research endpoint, CLI inline, MCP connection step - Agent onboarding: simplified to agent-only flow, human verification moved to auth page - Authentication: use-case guidance at top, consolidated key creation methods - All guide pages: tighter copy, proof numbers, brand voice compliance - No API reference files touched (auto-generated from OpenAPI) Made-with: Cursor --- agents.mdx | 81 ++++------- authentication.mdx | 123 ++++++++-------- cli.mdx | 351 ++++++++------------------------------------- content-agent.mdx | 222 ++++++++++------------------ docs.json | 183 ++++++++++++----------- index.mdx | 220 +++++++++++++--------------- mcp.mdx | 79 +++++----- quickstart.mdx | 183 +++++++++-------------- 8 files changed, 524 insertions(+), 918 deletions(-) diff --git a/agents.mdx b/agents.mdx index 8bbf1f0..181f936 100644 --- a/agents.mdx +++ b/agents.mdx @@ -1,11 +1,13 @@ --- -title: 'Agents' -description: 'Programmatic agent onboarding — sign up and obtain API keys in one call, no dashboard, no human in the loop.' +title: "Agent Onboarding" +description: "Get an API key programmatically — one call, no browser, no verification, no human in the loop." --- -## Quickest start +Two unauthenticated endpoints let any AI agent create an account and get an API key instantly. -Get a working API key in a single unauthenticated request: +## Get a key + +One POST. No auth required. Key comes back in the response. ```bash curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ @@ -13,20 +15,18 @@ curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' ``` -Response: - ```json { "account_id": "123e4567-e89b-12d3-a456-426614174000", "api_key": "recoup_sk_abc123...", - "message": "If this is a new agent+ email, your API key is included. Otherwise, check your email for a verification code." + "message": "If this is a new agent+ email, your API key is included." } ``` -That's it. Store `api_key`, pass it in the `x-api-key` header on every subsequent request, and you're done. +Store `api_key`. Pass it as `x-api-key` on every request. Done. -**One-liner — sign up and export the key in one shot.** Drop this into your shell and you'll have `$RECOUP_API_KEY` ready to use on the next line: +**One-liner** — sign up and export in one command: ```bash export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ @@ -34,63 +34,36 @@ export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agent -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) ``` -Verify it worked: - -```bash -curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id -``` - - - -The `agent+{unique-suffix}@recoupable.com` shape is the recommended path for agents — it always returns an API key instantly, with no email verification required. Combining `$(date +%s)` with `$RANDOM` guarantees a fresh, collision-free address on every call (including multiple signups within the same second) and is portable across macOS and Linux shells. -## How it works - -Two unauthenticated endpoints power agent onboarding: - -- **[`POST /api/agents/signup`](/api-reference/agents/signup)** — Register with an email address. Emails with the `agent+` prefix that have never been seen before receive an API key immediately. Any other email (or a previously-used `agent+` address) receives a 6-digit verification code via email. -- **[`POST /api/agents/verify`](/api-reference/agents/verify)** — Submit the verification code to receive an API key. +--- -Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones. +## Endpoints -## Standard signup (email verification) +| Endpoint | Auth | What it does | +|----------|------|-------------| +| [`POST /api/agents/signup`](/api-reference/agents/signup) | None | New `agent+` emails → instant API key. Other emails → verification code sent via email. | +| [`POST /api/agents/verify`](/api-reference/agents/verify) | None | Submit verification code → receive API key. | -If you're building a human-facing integration and want the user to verify their real email, use any non-`agent+` address: + +`agent+{unique}@recoupable.com` emails always return a key immediately — no verification step. Combining `$(date +%s)` with `$RANDOM` guarantees unique addresses across calls. + -Step 1 — request a verification code: +Each signup or verification creates a new key without revoking existing ones. -```bash -curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ - -H "Content-Type: application/json" \ - -d '{"email": "you@example.com"}' -``` +--- -Step 2 — submit the 6-digit code from the verification email: +## Use the key ```bash -curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ - -H "Content-Type: application/json" \ - -d '{"email": "you@example.com", "code": "123456"}' -``` - -Response: - -```json -{ - "account_id": "123e4567-e89b-12d3-a456-426614174000", - "api_key": "recoup_sk_abc123...", - "message": "Verified" -} +curl "https://recoup-api.vercel.app/api/research?q=Drake" \ + -H "x-api-key: $RECOUP_API_KEY" ``` -## Using your API key +That request searches the entire music industry for "Drake" and returns structured artist data. From here, you have access to 40+ tools — see the [Quickstart](/quickstart) for a guided walkthrough, or browse the [endpoint map](/#for-ai-agents) for the full API surface. -Pass the returned `api_key` in the `x-api-key` header on every authenticated request: +--- -```bash -curl -X GET "https://recoup-api.vercel.app/api/tasks" \ - -H "x-api-key: YOUR_API_KEY" -``` +## For humans -See [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request. +If your integration requires email verification (real email, not `agent+`), see the **Create a key** section in [Authentication](/authentication). diff --git a/authentication.mdx b/authentication.mdx index e7b7850..2391f2e 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -1,115 +1,106 @@ --- title: "Authentication" -description: "How authentication works in the Recoup API — API keys, access tokens, and organization access control." +description: "API keys and Bearer tokens — how to authenticate every request to the Recoup API." --- -## Overview +**Use API keys** for server-to-server, CLI, and agent integrations. **Use Bearer tokens** for frontend apps authenticated via Privy. Include exactly one — providing both returns `401`. -Every request to the Recoup API must be authenticated using exactly one of two mechanisms: - -| Method | Header | Use case | +| Method | Header | Best for | |--------|--------|----------| -| 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 Key | `x-api-key` | Servers, scripts, CLI, AI agents | +| Bearer Token | `Authorization: Bearer ` | Frontend apps via Privy | -Agent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details. +[Agent signup](/agents) endpoints are unauthenticated — they let agents get their first key without any credentials. --- -## API Keys +## Create a key -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. +### Instant (for agents) -### Creating an API Key +One call, no verification: -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** +```bash +export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ + -H "Content-Type: application/json" \ + -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) +``` + +### With email verification (for humans) + +```bash +# Step 1 — request a code +curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ + -H "Content-Type: application/json" \ + -d '{"email": "you@example.com"}' + +# Step 2 — submit the code +curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ + -H "Content-Type: application/json" \ + -d '{"email": "you@example.com", "code": "123456"}' +``` + +### From the dashboard + +Go to [chat.recoupable.com/keys](https://chat.recoupable.com/keys), sign in, and create a key. -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. +Keys are shown once. They are stored as HMAC-SHA256 hashes and cannot be retrieved after creation. -### Using an API Key +--- -Pass your key in the `x-api-key` header: +## Use a key ```bash -curl -X GET "https://recoup-api.vercel.app/api/tasks" \ +curl "https://recoup-api.vercel.app/api/research?q=Drake" \ -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. +## Organization access -- **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 +If your account belongs to an organization, your key can access data for any account in that org by passing `account_id`: - -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. - +- **No org** — key accesses its own data only +- **Org member** — key can pass `account_id` to access any member's data --- -## Access Tokens (Privy) +## Bearer tokens (Privy) -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. +For frontend apps with [Privy](https://privy.io) authentication: ```bash -curl -X GET "https://recoup-api.vercel.app/api/tasks" \ +curl "https://recoup-api.vercel.app/api/tasks" \ -H "Authorization: Bearer YOUR_PRIVY_JWT" ``` -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. +The API validates the JWT against Privy, extracts the user's email, and resolves it to a Recoup account. --- -## How We Verify Access on API Calls - -Every authenticated request goes through `validateAuthContext`, which enforces the following access rules: - -### API Key or Bearer Token - -By default, requests access the key owner's own account. When `account_id` is provided: +## Access control ``` -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 +Request includes account_id? + ├── Same as key owner → allowed + ├── Shares an organization → allowed + └── No shared org → 403 ``` -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. - - -### 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** - ---- - -## Error Responses +## Errors | 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` | - ---- +| `401` | Missing/invalid credentials, or both headers | +| `403` | Valid credentials, insufficient access | -## Security Notes +## Security -- 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) +- Keys stored as HMAC-SHA256 hashes — never plaintext +- Rotate compromised keys at [chat.recoupable.com/keys](https://chat.recoupable.com/keys) +- Never commit keys to version control diff --git a/cli.mdx b/cli.mdx index f64a361..2f86060 100644 --- a/cli.mdx +++ b/cli.mdx @@ -1,19 +1,19 @@ --- title: "CLI" -description: "Install and use the Recoup CLI to interact with the platform from your terminal." +description: "Install the Recoup CLI and interact with the platform from your terminal." --- -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`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments. -## Installation +## Install ```bash npm install -g @recoupable/cli ``` -## Authentication +## Authenticate -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: ```bash export RECOUP_API_KEY=your-api-key @@ -25,6 +25,10 @@ Verify it works: recoup whoami ``` + +Get an API key from the [API Keys page](https://chat.recoupable.com/keys) or use the [agent signup](/agents) for instant key generation. + + ## Configuration | Variable | Required | Default | Description | @@ -34,7 +38,11 @@ recoup whoami All commands support `--json` for machine-readable output and `--help` for usage info. -## whoami +--- + +## Commands + +### whoami Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id). @@ -43,111 +51,93 @@ recoup whoami recoup whoami --json ``` -## orgs +### orgs -Manage organizations. See [`GET /api/organizations`](/api-reference/organizations/list). +List organizations. See [`GET /api/organizations`](/api-reference/organizations/list). ```bash recoup orgs list recoup orgs list --account -recoup orgs list --json ``` -## artists +### artists -Manage artists. See [`GET /api/artists`](/api-reference/artists/list). +List artists. See [`GET /api/artists`](/api-reference/artists/list). ```bash recoup artists list recoup artists list --org recoup artists list --account -recoup artists list --json ``` -## notifications +### notifications -Send a notification email to the authenticated account's email address. The recipient is automatically resolved from your API key — no need to specify a `to` address. +Send a notification email to the authenticated account. See [`POST /api/notifications`](/api-reference/notifications/create). ```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 notifications --subject "Update" --html "

Report

Details here.

" ``` | Flag | Required | Description | |------|----------|-------------| | `--subject ` | Yes | Email subject line | -| `--text ` | No | Plain text or Markdown body (rendered as HTML) | +| `--text ` | No | Plain text or Markdown body | | `--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 +### chats -Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create). +Manage chats. See [`GET /api/chats`](/api-reference/chat/chats). ```bash recoup chats list recoup chats create --name "My Topic" recoup chats create --name "My Topic" --artist -recoup chats list --json ``` -## sandboxes +### sandboxes -Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create). +Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list). ```bash recoup sandboxes list recoup sandboxes create recoup sandboxes create --command "ls -la" -recoup sandboxes list --json ``` -## tasks +### tasks -Check the status of background task runs. See [`GET /api/tasks/runs`](/api-reference/tasks/runs). +Check background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs). ```bash recoup tasks status --run -recoup tasks status --run --json ``` -| Flag | Required | Description | -|------|----------|-------------| -| `--run ` | Yes | Trigger.dev run ID | +--- ## research -Music industry research — streaming metrics, audience demographics, playlist placements, competitive analysis, and web intelligence. All data is accessed through your `RECOUP_API_KEY`. +Music industry research — streaming metrics, audience demographics, playlist placements, competitive analysis, and web intelligence. -Artist-scoped commands (like `metrics`, `audience`, `similar`) accept an **artist name** or a **Recoup artist ID** (UUID). The API resolves the artist automatically. If the name is ambiguous (multiple matches), the API returns the top results for disambiguation. +Artist-scoped commands accept an **artist name** or a **Recoup artist ID** (UUID). The API resolves the artist automatically. -### Search for an artist +### Search ```bash recoup research "Drake" recoup research "Phoebe Bridgers" --json ``` -See [`GET /api/research`](/api-reference/research/search). - -### Lookup by platform URL - -Find an artist from a Spotify URL, Apple Music link, or any platform ID. +### Lookup by URL ```bash recoup research lookup "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4" -recoup research lookup "3TVXtAsR1Inumwj472S9r4" ``` -See [`GET /api/research/lookup`](/api-reference/research/lookup). - -### Artist profile and career +### Profile and career ```bash recoup research profile "Drake" @@ -155,61 +145,24 @@ recoup research career "Drake" recoup research insights "Drake" ``` -| Subcommand | Description | API endpoint | -|------------|-------------|-------------| -| `profile` | Full artist profile — bio, genres, social URLs, label | [`GET /api/research/profile`](/api-reference/research/profile) | -| `career` | Career timeline and key milestones | [`GET /api/research/career`](/api-reference/research/career) | -| `insights` | AI-generated observations and trends | [`GET /api/research/insights`](/api-reference/research/insights) | - -### Streaming and social metrics - -Get platform-specific metrics over time. Supports 14 platforms. +### Streaming metrics ```bash recoup research metrics "Drake" --source spotify recoup research metrics "Drake" --source instagram recoup research metrics "Drake" --source tiktok -recoup research metrics "Drake" --source youtube_channel ``` Valid `--source` values: `spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown`. -See [`GET /api/research/metrics`](/api-reference/research/metrics). - ### Audience and geography ```bash recoup research audience "Drake" recoup research audience "Drake" --platform tiktok -recoup research audience "Drake" --platform youtube recoup research cities "Drake" ``` -| Subcommand | Description | API endpoint | -|------------|-------------|-------------| -| `audience` | Age, gender, country breakdown. `--platform`: `instagram` (default), `tiktok`, `youtube` | [`GET /api/research/audience`](/api-reference/research/audience) | -| `cities` | Top cities by listener concentration | [`GET /api/research/cities`](/api-reference/research/cities) | - -### Social URLs - -Get all social and streaming links for an artist. - -```bash -recoup research urls "Drake" -``` - -See [`GET /api/research/urls`](/api-reference/research/urls). - -### Instagram posts - -Get an artist's top Instagram posts and reels by engagement. - -```bash -recoup research instagram-posts "Drake" -``` - -See [`GET /api/research/instagram-posts`](/api-reference/research/instagram-posts). - ### Competitive landscape ```bash @@ -217,232 +170,58 @@ recoup research similar "Drake" recoup research similar "Drake" --audience high --genre high --limit 20 ``` -Configuration options: `--audience`, `--genre`, `--mood`, `--musicality` (values: `high`, `medium`, `low`). - -See [`GET /api/research/similar`](/api-reference/research/similar). - ### Playlists ```bash recoup research playlists "Drake" recoup research playlists "Drake" --platform applemusic -recoup research playlists "Drake" --editorial -recoup research playlists "Drake" --status past --since 2025-01-01 -recoup research playlists "Drake" --sort followers --limit 50 +recoup research playlists "Drake" --editorial --status past --since 2025-01-01 ``` -| Flag | Description | -|------|-------------| -| `--platform

` | `spotify` (default), `applemusic`, `deezer`, `amazon`, `youtube` | -| `--editorial` | Only editorial playlists | -| `--status ` | `current` (default) or `past` | -| `--since ` | Filter by date (YYYY-MM-DD) | -| `--sort ` | Sort results (e.g., `followers`) | -| `--limit ` | Max results | - -See [`GET /api/research/playlists`](/api-reference/research/playlists). - ### Discography ```bash recoup research albums "Drake" recoup research tracks "Drake" -``` - -See [`GET /api/research/albums`](/api-reference/research/albums) and [`GET /api/research/tracks`](/api-reference/research/tracks). - -### Track details - -Get metadata for a specific track — look up by name or Spotify URL. - -```bash recoup research track "God's Plan" -recoup research track "https://open.spotify.com/track/2grjqo0Frpf2..." ``` -See [`GET /api/research/track`](/api-reference/research/track). - -### Playlist and curator details - -Get metadata for a specific playlist or its curator. - -```bash -recoup research playlist spotify 37i9dQZF1DXcBWIGoYBM5M -recoup research curator spotify 1 -``` - -See [`GET /api/research/playlist`](/api-reference/research/playlist) and [`GET /api/research/curator`](/api-reference/research/curator). - -### Discover artists - -Find artists by criteria — country, genre, listener ranges, growth rate. +### Discovery ```bash recoup research discover --country US --spotify-listeners 100000 500000 recoup research discover --genre 86 --sort weekly_diff.sp_monthly_listeners ``` -| Flag | Description | -|------|-------------| -| `--country ` | ISO country code (US, BR, GB, etc.) | -| `--genre ` | Genre ID (use `recoup research genres` to list) | -| `--spotify-listeners ` | Monthly listener range | -| `--sort ` | Sort field (e.g., `weekly_diff.sp_monthly_listeners`) | -| `--limit ` | Max results | - -See [`GET /api/research/discover`](/api-reference/research/discover). - -### Milestones - -Get an artist's activity feed — playlist adds, chart entries, and notable events. - -```bash -recoup research milestones "Drake" -recoup research milestones "Drake" --json -``` - -See [`GET /api/research/milestones`](/api-reference/research/milestones). - -### Venues - -Get venues an artist has performed at, including capacity and location. - -```bash -recoup research venues "Drake" -recoup research venues "Drake" --json -``` - -See [`GET /api/research/venues`](/api-reference/research/venues). - -### Rank - -Get an artist's global Chartmetric ranking. - -```bash -recoup research rank "Drake" -recoup research rank "Drake" --json -``` - -See [`GET /api/research/rank`](/api-reference/research/rank). - -### Charts - -Get global chart positions for a platform. NOT artist-scoped — returns the full chart. - -```bash -recoup research charts --platform spotify -recoup research charts --platform spotify --country US -recoup research charts --platform applemusic --country GB --interval weekly --json -``` - -| Flag | Required | Description | -|------|----------|-------------| -| `--platform ` | Yes | Chart platform (spotify, applemusic, tiktok, youtube, itunes, shazam) | -| `--country ` | No | ISO country code (US, GB, DE, etc.) | -| `--interval ` | No | Time interval (e.g. daily, weekly) | -| `--type ` | No | Chart type (varies by platform) | -| `--latest` | No | Return only the most recent chart | - -See [`GET /api/research/charts`](/api-reference/research/charts). - -### Radio stations - -List radio stations tracked by Chartmetric. - -```bash -recoup research radio -recoup research radio --json -``` - -See [`GET /api/research/radio`](/api-reference/research/radio). - -### Reference data - -```bash -recoup research genres -recoup research festivals -``` - -See [`GET /api/research/genres`](/api-reference/research/genres) and [`GET /api/research/festivals`](/api-reference/research/festivals). - ### Web research -Search the web for narrative context, press coverage, and cultural information that structured data doesn't cover. - ```bash recoup research web "Drake brand partnerships sync licensing" -recoup research web "Phoebe Bridgers fan community psychographics" -``` - -See [`POST /api/research/web`](/api-reference/research/web). - -### Deep research report - -Comprehensive multi-source research that synthesizes information from across the web into a cited report. - -```bash -recoup research report "Drake" -recoup research report "Tell me everything about Phoebe Bridgers — bio, streaming metrics, fan base, competitive landscape, and revenue opportunities" -``` - -See [`POST /api/research/deep`](/api-reference/research/deep). - -### People search - -Search for people in the music industry — artists, managers, A&R reps, producers. Returns profiles with LinkedIn data. - -```bash +recoup research report "Tell me everything about Phoebe Bridgers" recoup research people "A&R reps at Atlantic Records" -recoup research people "music managers in Los Angeles R&B" +recoup research extract "https://en.wikipedia.org/wiki/Drake_(musician)" ``` -See [`POST /api/research/people`](/api-reference/research/people). - -### Extract URL - -Extract clean markdown content from any public URL. Handles JavaScript-heavy pages and PDFs. - -```bash -recoup research extract "https://en.wikipedia.org/wiki/Drake_(musician)" --objective "biography and discography" -recoup research extract "https://open.spotify.com/artist/..." --full-content -``` - -Accepts up to 10 URLs per call. - -See [`POST /api/research/extract`](/api-reference/research/extract). - -### Enrich - -Get structured data about any entity from web research. Provide a description and a JSON schema — get typed data back with citations. - -```bash -recoup research enrich "Drake rapper" --schema '{"properties": {"real_name": {"type": "string"}, "label": {"type": "string"}, "hometown": {"type": "string"}}}' -``` - -Processors: `base` (fast, default), `core` (balanced), `ultra` (comprehensive). - -See [`POST /api/research/enrich`](/api-reference/research/enrich). - -### Using Recoup artist IDs - -Artist IDs are supported on artist-scoped commands (see the note above). Example: +### Reference data ```bash -recoup research metrics de05ba8c-7e29-4f1a-93a7-3635653599f6 --source spotify +recoup research genres +recoup research festivals +recoup research radio +recoup research milestones "Drake" +recoup research venues "Drake" +recoup research rank "Drake" +recoup research charts --platform spotify --country US ``` -### Workflow example: full artist research +### Workflow example ```bash -# Pull structured data (all by name, run in parallel) recoup research metrics "Phoebe Bridgers" --source spotify --json recoup research audience "Phoebe Bridgers" --json recoup research cities "Phoebe Bridgers" --json recoup research similar "Phoebe Bridgers" --audience high --genre high --json recoup research playlists "Phoebe Bridgers" --editorial --json - -# Add web context -recoup research web "Phoebe Bridgers biography career milestones" --json recoup research web "Phoebe Bridgers fan community brand partnerships" --json ``` @@ -450,54 +229,38 @@ recoup research web "Phoebe Bridgers fan community brand partnerships" --json ## content -Content-creation pipeline commands. Generate AI-powered social videos for artists. +Content creation pipeline — generate AI-powered social videos for artists. -### List templates - -List available content templates. See [`GET /api/content/templates`](/api-reference/content/templates). +### Templates ```bash recoup content templates -recoup content templates --json ``` -### Validate artist +### Validate -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). +Check that an artist has the required assets before creating content: ```bash recoup content validate --artist -recoup content validate --artist --json ``` -| Flag | Required | Description | -|------|----------|-------------| -| `--artist ` | Yes | Artist account ID | +### Estimate -### Estimate cost - -Preview the estimated cost and duration for a content run without starting it. See [`POST /api/content/estimate`](/api-reference/content/estimate). +Preview estimated cost and duration: ```bash recoup content estimate --artist -recoup content estimate --artist --template --json +recoup content estimate --artist --template ``` -| Flag | Required | Description | -|------|----------|-------------| -| `--artist ` | Yes | Artist account ID | -| `--template ` | No | Template name (default: random) | -| `--lipsync` | No | Enable lipsync mode | -| `--upscale` | No | Enable upscaling | - -### Create content +### Create -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). +Trigger the full content creation pipeline: ```bash recoup content create --artist recoup content create --artist --template --lipsync --upscale -recoup content create --artist --json ``` | Flag | Required | Description | diff --git a/content-agent.mdx b/content-agent.mdx index 4f78a55..6bd291b 100644 --- a/content-agent.mdx +++ b/content-agent.mdx @@ -1,112 +1,11 @@ --- -title: 'Content' -description: 'Generate images, videos, captions, and social-ready content using AI-powered primitives' +title: "Content Agent" +description: "AI content creation agent accessible via Slack — generates social-ready artist videos on @mention." --- -## Overview +The Recoup Content Agent is a Slack bot that generates social-ready artist videos on @mention. It connects to the content creation pipeline and delivers results directly in your Slack thread. -Recoup's content API gives you seven independent primitives for generating and editing visual content. Each primitive does one thing well. You orchestrate them. - -**Every primitive works without a template.** Pass your own prompt, reference images, and parameters directly. Templates are optional shortcuts — opinionated creative recipes that pre-fill parameters for a specific look. - -## Primitives - -| Primitive | Endpoint | What it does | -|-----------|----------|-------------| -| Generate Image | [POST /api/content/image](/api-reference/content/generate-image) | Create an image from a text prompt, optionally with a reference image for face/style | -| Generate Video | [POST /api/content/video](/api-reference/content/generate-video) | Create a video — 6 modes: prompt, animate, reference, extend, first-last, lipsync | -| Generate Caption | [POST /api/content/caption](/api-reference/content/generate-caption) | Generate on-screen text for social media videos | -| Transcribe Audio | [POST /api/content/transcribe](/api-reference/content/transcribe-audio) | Transcribe audio to timestamped lyrics/text | -| Edit Content | [PATCH /api/content](/api-reference/content/edit) | Trim, crop, resize, overlay text, or add audio — one processing pass | -| Upscale | [POST /api/content/upscale](/api-reference/content/upscale) | Upscale image or video resolution (up to 4x) | -| Analyze Video | [POST /api/content/analyze](/api-reference/content/analyze-video) | AI video analysis — describe scenes, check quality, evaluate content | - -There is also [POST /api/content/create](/api-reference/content/create) which runs the full pipeline in one call — use it when you want a video without creative control over each step. - -## How It Works - -### Without a template (malleable mode) - -Pass your own parameters directly to any primitive. Maximum creative control. - -```bash -# Generate an image with your own prompt -curl -X POST https://recoup-api.vercel.app/api/content/image \ - -H "x-api-key: YOUR_KEY" \ - -H "Content-Type: application/json" \ - -d '{"prompt": "A moody portrait in a dimly lit room, front-facing phone camera"}' - -# Generate a video from that image -curl -X POST https://recoup-api.vercel.app/api/content/video \ - -H "x-api-key: YOUR_KEY" \ - -H "Content-Type: application/json" \ - -d '{"image_url": "IMAGE_URL_FROM_ABOVE", "prompt": "subtle breathing motion, nearly still"}' -``` - -### With a template (shortcut mode) - -Pass a template ID and the primitive fills in prompts, reference images, and style rules automatically. You can still override any parameter. - -```bash -# Same image, but the template provides the prompt and reference images -curl -X POST https://recoup-api.vercel.app/api/content/image \ - -H "x-api-key: YOUR_KEY" \ - -H "Content-Type: application/json" \ - -d '{"template": "artist-caption-bedroom", "reference_image_url": "YOUR_FACE_IMAGE"}' -``` - -Use [GET /api/content/templates](/api-reference/content/templates) to see available templates with descriptions. - -## Templates - -A template is a complete creative recipe — it defines what a piece of content looks like across every primitive: - -- **Image config**: prompt, reference images, style rules (camera, lighting, composition) -- **Video config**: mood variations, movement descriptions -- **Caption config**: tone, formatting rules, example captions -- **Edit config**: crop ratio, text overlay style, audio mixing - -Templates are optional. They save time by pre-filling parameters with curated defaults. When you see customers repeatedly creating the same kind of content, that pattern becomes a template. - -### Override priority - -When using a template, your explicit parameters always win: - -1. **Your params** — highest priority. What you pass overrides everything. -2. **Artist context** — if the artist has a style guide, it personalizes the template. -3. **Template defaults** — lowest priority. The recipe's built-in values. - -## Video Modes - -The video primitive supports 6 generation modes: - -| Mode | What it does | Required inputs | -|------|-------------|-----------------| -| `prompt` | Create from text description | `prompt` | -| `animate` | Animate a still image | `image_url`, `prompt` | -| `reference` | Use image as style reference (not first frame) | `image_url`, `prompt` | -| `extend` | Continue an existing video | `video_url`, `prompt` | -| `first-last` | Transition between two images | `image_url`, `end_image_url`, `prompt` | -| `lipsync` | Sync face to audio | `image_url`, `audio_url` | - -Set `mode` explicitly, or omit it and the API infers the mode from the inputs you provide. - -## Iteration - -Each primitive is independent. Redo any step without rerunning the whole pipeline: - -- Bad image? Regenerate with a different prompt or reference -- Caption too long? Regenerate with `length: "short"` -- Video glitchy? Analyze it, then regenerate with adjusted params -- Clip too short? Use `extend` mode to continue it -- Low quality? Upscale the image or video -- Everything good but wrong caption? Just re-run the edit step - -## Content Agent (Slack Bot) - -The **Recoup Content Agent** is a Slack bot that generates social-ready artist videos on @mention. It plugs into the content creation pipeline and delivers results directly in your Slack thread. - -### @Mention Syntax +## @Mention syntax ``` @RecoupContentAgent [template] [batch=N] [lipsync] @@ -115,13 +14,13 @@ The **Recoup Content Agent** is a Slack bot that generates social-ready artist v | Parameter | Required | Description | |-----------|----------|-------------| | `artist_account_id` | Yes | UUID of the artist account | -| `template` | No | Content template name. Optional — when omitted, the pipeline runs with default settings. See [GET /api/content/templates](/api-reference/content/templates) for options. | -| `batch=N` | No | Number of videos to generate (1-30, default 1) | +| `template` | No | Content template name — see [GET /api/content/templates](/api-reference/content/templates) | +| `batch=N` | No | Number of videos to generate (1–30, default 1) | | `lipsync` | No | Enable lipsync mode (audio baked into video) | -### Examples +## Examples -**Basic — single video with default template:** +**Single video with default template:** ``` @RecoupContentAgent abc-123-uuid ``` @@ -136,66 +35,93 @@ The **Recoup Content Agent** is a Slack bot that generates social-ready artist v @RecoupContentAgent abc-123-uuid batch=3 lipsync ``` -### Architecture +--- + +## Content primitives -| Component | Location | Purpose | -|-----------|----------|---------| -| Slack webhook | `POST /api/content-agent/slack` | Receives @mention events | -| Callback endpoint | `POST /api/content-agent/callback` | Receives polling results | -| Bot singleton | `lib/content-agent/bot.ts` | Chat SDK with Slack adapter + Redis state | -| Mention handler | `lib/content-agent/handlers/` | Parses args, validates artist, triggers pipeline | -| Poll task | `poll-content-run` (Trigger.dev) | Monitors content runs, posts results via callback | +The content API provides seven independent primitives. Each does one thing well. You orchestrate them. -### Data Flow +| Primitive | Endpoint | What it does | +|-----------|----------|-------------| +| Generate Image | [POST /api/content/image](/api-reference/content/generate-image) | Create an image from a text prompt with optional reference image | +| Generate Video | [POST /api/content/video](/api-reference/content/generate-video) | Create a video — 6 modes: prompt, animate, reference, extend, first-last, lipsync | +| Generate Caption | [POST /api/content/caption](/api-reference/content/generate-caption) | Generate on-screen text for social media videos | +| Transcribe Audio | [POST /api/content/transcribe](/api-reference/content/transcribe-audio) | Transcribe audio to timestamped lyrics/text | +| Edit Content | [PATCH /api/content](/api-reference/content/edit) | Trim, crop, resize, overlay text, or add audio | +| Upscale | [POST /api/content/upscale](/api-reference/content/upscale) | Upscale image or video resolution (up to 4x) | +| Analyze Video | [POST /api/content/analyze](/api-reference/content/analyze-video) | AI video analysis — describe scenes, check quality | + +Use [POST /api/content/create](/api-reference/content/create) to run the full pipeline in one call. + +## Video modes + +| Mode | What it does | Required inputs | +|------|-------------|-----------------| +| `prompt` | Create from text description | `prompt` | +| `animate` | Animate a still image | `image_url`, `prompt` | +| `reference` | Use image as style reference | `image_url`, `prompt` | +| `extend` | Continue an existing video | `video_url`, `prompt` | +| `first-last` | Transition between two images | `image_url`, `end_image_url`, `prompt` | +| `lipsync` | Sync face to audio | `image_url`, `audio_url` | + +--- + +## Architecture + +| Component | Purpose | +|-----------|---------| +| Slack webhook (`POST /api/content-agent/slack`) | Receives @mention events | +| Callback endpoint (`POST /api/content-agent/callback`) | Receives polling results | +| Bot singleton (`lib/content-agent/bot.ts`) | Chat SDK with Slack adapter + Redis state | +| Mention handler (`lib/content-agent/handlers/`) | Parses args, validates artist, triggers pipeline | +| Poll task (`poll-content-run`) | Monitors runs, posts results via callback | + +## Data flow 1. **Slack event** → `POST /api/content-agent/slack` handles the webhook -2. **Mention handler** parses the command, calls [`GET /api/content/validate`](/api-reference/content/validate) to check artist readiness -3. **Content creation** triggered via [`POST /api/content/create`](/api-reference/content/create) — returns `runIds` -4. **Poll task** (`poll-content-run`) monitors the Trigger.dev runs every 30 seconds (up to 30 minutes) -5. **Callback** → [`POST /api/content-agent/callback`](/api-reference/content-agent/callback) receives results and posts video URLs back to the Slack thread +2. **Mention handler** parses the command, calls [`GET /api/content/validate`](/api-reference/content/validate) +3. **Content creation** triggered via [`POST /api/content/create`](/api-reference/content/create) +4. **Poll task** monitors runs every 30 seconds (up to 30 minutes) +5. **Callback** posts video URLs back to the Slack thread + +--- -### Setup +## Setup -#### 1. Create a Slack App +### 1. Create a Slack App -1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app -2. Under **OAuth & Permissions**, add bot scopes: - - `chat:write` — post messages - - `app_mentions:read` — receive @mention events -3. Under **Event Subscriptions**: - - Enable events - - Set the request URL to `https://recoup-api.vercel.app/api/content-agent/slack` - - Subscribe to `app_mention` bot event -4. Install the app to your workspace +1. Go to [api.slack.com/apps](https://api.slack.com/apps) +2. Add bot scopes: `chat:write`, `app_mentions:read` +3. Enable Event Subscriptions → set request URL to `https://recoup-api.vercel.app/api/content-agent/slack` +4. Subscribe to `app_mention` bot event +5. Install the app to your workspace -#### 2. Configure Environment Variables +### 2. Configure environment variables | Variable | Where | Description | |----------|-------|-------------| -| `SLACK_CONTENT_BOT_TOKEN` | API (Vercel) | Bot OAuth token (`xoxb-...`) from Slack app | -| `SLACK_CONTENT_SIGNING_SECRET` | API (Vercel) | Signing secret from Slack app **Basic Information** | -| `CONTENT_AGENT_CALLBACK_SECRET` | API + Tasks | Shared secret for callback authentication (generate a random string) | -| `RECOUP_API_KEY` | API + Tasks | Recoup API key for authenticating pipeline requests | -| `RECOUP_API_BASE_URL` | Tasks (Trigger.dev) | API base URL (e.g., `https://recoup-api.vercel.app`) | +| `SLACK_CONTENT_BOT_TOKEN` | API | Bot OAuth token (`xoxb-...`) | +| `SLACK_CONTENT_SIGNING_SECRET` | API | Signing secret from Slack app | +| `CONTENT_AGENT_CALLBACK_SECRET` | API + Tasks | Shared secret for callback auth | +| `RECOUP_API_KEY` | API + Tasks | Recoup API key for pipeline requests | +| `RECOUP_API_BASE_URL` | Tasks | API base URL | -#### 3. Verify +### 3. Verify -Mention the bot in any Slack channel where it's been added: +Mention the bot in any channel where it's been added: ``` @RecoupContentAgent ``` -You should see: -1. An immediate acknowledgment message -2. A video URL reply in the thread after ~5-10 minutes +You should see an immediate acknowledgment followed by a video URL reply in the thread after ~5–10 minutes. -### Troubleshooting +## Troubleshooting | Issue | Cause | Fix | |-------|-------|-----| | No response from bot | Event subscription URL not configured | Check Slack app Event Subscriptions | | "Artist not found" | Invalid `artist_account_id` | Verify the UUID exists in the platform | -| "No GitHub repository found" | Artist missing repo config | Ensure the artist account has a linked GitHub repo | -| Timeout after 30 min | Pipeline took too long | Check Trigger.dev dashboard for the failed run | -| "Unsupported template" | Invalid template name | Use [`GET /api/content/templates`](/api-reference/content/templates) to list available templates | +| "No GitHub repository found" | Artist missing repo config | Ensure the artist has a linked GitHub repo | +| Timeout after 30 min | Pipeline took too long | Check Trigger.dev dashboard | +| "Unsupported template" | Invalid template name | Use [`GET /api/content/templates`](/api-reference/content/templates) | diff --git a/docs.json b/docs.json index a78bcd0..8e7e9ec 100644 --- a/docs.json +++ b/docs.json @@ -1,64 +1,63 @@ { "$schema": "https://mintlify.com/docs.json", - "theme": "mint", + "theme": "sequoia", "name": "Recoup", "colors": { - "primary": "#345A5D", - "light": "#4A7A7D", - "dark": "#1E3A3D" + "primary": "#0a0a0a", + "light": "#ededed", + "dark": "#0a0a0a" }, "favicon": "/favicon.ico", + "appearance": { + "default": "system" + }, + "fonts": { + "heading": { + "family": "Plus Jakarta Sans", + "weight": 700 + }, + "body": { + "family": "Inter", + "weight": 400 + } + }, + "background": { + "decoration": "windows", + "color": { + "dark": "#080808" + } + }, + "styling": { + "eyebrows": "breadcrumbs", + "codeblocks": "dark" + }, + "icons": { + "library": "lucide" + }, "navigation": { "tabs": [ { - "tab": "Quickstart", + "tab": "Overview", "groups": [ { - "group": "Getting started", + "group": "Start here", "pages": [ "index", "quickstart", - "cli", - "mcp", - "authentication" + "authentication", + "agents" ] }, { - "group": "Agents", + "group": "Interfaces", "pages": [ - "agents", + "cli", + "mcp", "content-agent" ] } ] }, - { - "tab": "Artists", - "groups": [ - { - "group": "Artists", - "pages": [ - "api-reference/artists/list", - "api-reference/artists/create", - "api-reference/artists/delete", - "api-reference/artist/segments", - "api-reference/artist/socials", - "api-reference/artist/socials-scrape", - "api-reference/artist/profile" - ] - }, - { - "group": "Tasks", - "pages": [ - "api-reference/tasks/get", - "api-reference/tasks/create", - "api-reference/tasks/update", - "api-reference/tasks/delete", - "api-reference/tasks/runs" - ] - } - ] - }, { "tab": "Research", "groups": [ @@ -119,6 +118,18 @@ { "tab": "Releases", "groups": [ + { + "group": "Artists", + "pages": [ + "api-reference/artists/list", + "api-reference/artists/create", + "api-reference/artists/delete", + "api-reference/artist/segments", + "api-reference/artist/socials", + "api-reference/artist/socials-scrape", + "api-reference/artist/profile" + ] + }, { "group": "Songs & Catalogs", "pages": [ @@ -134,6 +145,16 @@ "api-reference/songs/catalog-songs-delete" ] }, + { + "group": "Tasks", + "pages": [ + "api-reference/tasks/get", + "api-reference/tasks/create", + "api-reference/tasks/update", + "api-reference/tasks/delete", + "api-reference/tasks/runs" + ] + }, { "group": "Fans & Segments", "pages": [ @@ -205,13 +226,14 @@ ] }, { - "tab": "Social Media", + "tab": "Social", "groups": [ { - "group": "Social", + "group": "Connectors", "pages": [ - "api-reference/social/posts", - "api-reference/social/scrape" + "api-reference/connectors/list", + "api-reference/connectors/authorize", + "api-reference/connectors/disconnect" ] }, { @@ -238,6 +260,13 @@ "api-reference/x/trends" ] }, + { + "group": "Social", + "pages": [ + "api-reference/social/scrape", + "api-reference/social/posts" + ] + }, { "group": "Apify", "pages": [ @@ -247,7 +276,7 @@ ] }, { - "tab": "Accounts", + "tab": "Platform", "groups": [ { "group": "Agent Onboarding", @@ -256,21 +285,6 @@ "api-reference/agents/verify" ] }, - { - "group": "Connectors", - "pages": [ - "api-reference/connectors/list", - "api-reference/connectors/authorize", - "api-reference/connectors/disconnect" - ] - }, - { - "group": "Pulses", - "pages": [ - "api-reference/pulses/update", - "api-reference/pulses/list" - ] - }, { "group": "Accounts", "pages": [ @@ -289,6 +303,13 @@ "api-reference/organizations/add-artist" ] }, + { + "group": "Pulses", + "pages": [ + "api-reference/pulses/update", + "api-reference/pulses/list" + ] + }, { "group": "Workspaces", "pages": [ @@ -301,6 +322,12 @@ "api-reference/subscriptions/get" ] }, + { + "group": "Notifications", + "pages": [ + "api-reference/notifications/create" + ] + }, { "group": "Admins", "pages": [ @@ -313,12 +340,6 @@ "api-reference/admins/coding-pr", "api-reference/admins/content-slack-tags" ] - }, - { - "group": "Notifications", - "pages": [ - "api-reference/notifications/create" - ] } ] } @@ -326,29 +347,29 @@ "global": { "anchors": [ { - "anchor": "Recoup App", + "anchor": "Launch App", "href": "https://chat.recoupable.com", - "icon": "rocket" - }, - { - "anchor": "Website", - "href": "https://recoupable.com", - "icon": "globe" + "icon": "arrow-up-right" }, { - "anchor": "Blog", - "href": "https://research.recoupable.com/", - "icon": "newspaper" + "anchor": "GitHub", + "href": "https://github.com/recoupable", + "icon": "github" } ] } }, "logo": { "light": "/logo/light.svg", - "dark": "/logo/dark.png" + "dark": "/logo/dark.png", + "href": "https://recoupable.com" }, "navbar": { "links": [ + { + "label": "Blog", + "href": "https://research.recoupable.com/" + }, { "label": "Support", "href": "mailto:agent@recoupable.com" @@ -356,8 +377,8 @@ ], "primary": { "type": "button", - "label": "Dashboard", - "href": "https://chat.recoupable.com" + "label": "Get API Key", + "href": "https://chat.recoupable.com/keys" } }, "contextual": { @@ -375,13 +396,15 @@ "footer": { "socials": { "x": "https://x.com/recoupai", - "github": "https://github.com/recoupable-com", - "linkedin": "https://www.linkedin.com/company/recoupable" + "github": "https://github.com/recoupable", + "linkedin": "https://www.linkedin.com/company/recoupable", + "website": "https://recoupable.com" } }, "metatags": { "og:image": "/images/icon-with-background.png", - "og:site_name": "Recoup", + "og:site_name": "Recoup API", + "og:description": "Music intelligence API — 40+ tools for artist research, content creation, and music business automation. Built for developers and AI agents.", "twitter:card": "summary_large_image" } } diff --git a/index.mdx b/index.mdx index 62bb714..c513174 100644 --- a/index.mdx +++ b/index.mdx @@ -1,15 +1,13 @@ --- -title: "Recoup API Documentation" -description: "Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints." +title: "Recoup API" +description: "Music intelligence API — research any artist, generate content, and automate music operations. Built for developers and AI agents." --- -# Welcome to the Recoup API +Music intelligence for every team in music. 40+ tools for artist research, content creation, social analytics, and business automation — accessible from your code, your CLI, or your AI agent. -Use the Recoup API to build your record label. Generate content, Access artist analytics, Manage catalogs, Team chats, and task automation to power your record labels. +## Get an API key -## Quickest start — one curl call - -Get a working API key in a single unauthenticated request. No dashboard, no browser, no human in the loop. +One call. No signup form. No dashboard. ```bash export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ @@ -17,171 +15,155 @@ export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agent -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) ``` -`$RECOUP_API_KEY` is now ready to pass in the `x-api-key` header on any request. See the [Agents guide](/agents) for the full signup and verification flow. - -## 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. - -This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. - -## Base URL - -All API requests should be made to: - -```bash -https://recoup-api.vercel.app/api -``` - -## Authentication - -Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first 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) - -```bash -curl -X GET "https://recoup-api.vercel.app/api/artists?accountId=YOUR_ACCOUNT_ID" \ - -H "Content-Type: application/json" \ - -H "x-api-key: YOUR_API_KEY" -``` + +The `agent+` prefix bypasses email verification entirely. Your API key comes back in the response — ready to use immediately. + - -Keep your API key secure. Do not share it publicly or commit it to version control. - +--- -## Get Started +## How you access it - + - Get an API key in one curl call. The fastest path for AI agents — no dashboard required. + Standard HTTP endpoints. Pass your API key in `x-api-key` and call any of the 40+ tools. - Get your API key and make your first request in minutes. + Connect Claude, ChatGPT, Cursor, or any MCP-compatible agent directly to Recoup. One URL. - Install and use the Recoup CLI to interact with the platform from your terminal. - - - Connect Recoup to AI assistants via the Model Context Protocol. + `recoup research "Any Artist"` — that's it. Install with `npm i -g @recoupable/cli`. -## API Sections +--- -The API is organized into six main sections. Use these links to jump to the right area. +## What's in the API - 30 endpoints for artist research: search, lookup, profile, metrics, audience, cities, similar artists, playlists, albums, tracks, career history, insights, genres, festivals, web presence, and more. + Search any artist. Pull streaming metrics across 14 platforms, audience demographics, playlist placements, career timelines, competitive analysis, web intelligence, and people search. - Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs. - - - Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history. - - - Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors. + Generate images, videos, and captions with AI. Transcribe audio, edit media, upscale resolution, and analyze video content. Each primitive works independently. - Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation. + Manage artists, songs, and catalogs. Analyze tracks with AI. Schedule cron-based tasks to automate recurring work. - Accounts, organizations, workspaces, subscriptions, pulses, notifications, sandboxes, and admin tools. + Spotify, Instagram, X, and generic social scraping. Search artists, pull profiles and comments, track trends, and manage OAuth connectors. -## Agents + + Accounts, organizations, workspaces, subscriptions, automated pulses, notifications, and sandboxed code execution. + + +--- + +## Guides - Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically. + API key → first request → working integration. Under a minute. - API key authentication, account-scoped access, and organization-level permissions. + API keys, Bearer tokens, and organization-level access control. + + + Programmatic signup for AI agents. API key in one call — no browser required. + + + Slack bot that generates social-ready artist videos on @mention. -## Quick Reference for LLMs - -If you are an LLM navigating these docs, here is a summary of the endpoint structure: +--- -- **`/api/artists/*`** — Artist management (list, create, segments, socials, socials-scrape, profile) -- **`/api/research/*`** — Artist research (search, lookup, profile, metrics, audience, cities, similar, urls, instagram-posts, playlists, albums, track, tracks, career, insights, genres, festivals, web, deep, people, extract, enrich, milestones, venues, rank, charts, radio, discover, curator, playlist) -- **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate) -- **`/api/chat/*`** — Chat (chats, artist, segment, messages, messages-copy, messages-trailing-delete, create, update, delete, generate, stream, compact) -- **`/api/songs/*`** — Songs and catalogs (songs, create, analyze, analyze-presets, catalogs, catalogs-create, catalogs-delete, catalog-songs, catalog-songs-add, catalog-songs-delete) -- **`/api/tasks/*`** — Task automation (get, create, update, delete, runs) -- **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album) -- **`/api/instagram/*`** — Instagram (comments, profiles) -- **`/api/x/*`** — X/Twitter (search, trends) -- **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect) -- **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist) -- **`/api/organizations/*`** — Organizations (list, create, add-artist) -- **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload) -- **`/api/content-agent/*`** — Content agent webhooks (webhook, callback) -- **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required +## Base URL -Base URL: `https://recoup-api.vercel.app/api` +``` +https://recoup-api.vercel.app/api +``` -[OpenAPI Specification](https://github.com/sweetmantech/docs/blob/main/api-reference/openapi.json) +All endpoints require `x-api-key` header authentication unless noted. -## Need Help? +--- - - Reach out to our team at agent@recoupable.com for assistance with the Recoup API. - +## For AI agents + +If you are an LLM or AI agent, here is the complete endpoint map. All paths are relative to `https://recoup-api.vercel.app/api`. + +| Domain | Endpoints | +|--------|-----------| +| `/research/*` | search, lookup, profile, metrics, audience, cities, similar, urls, instagram-posts, playlists, albums, tracks, track, career, insights, playlist, curator, discover, genres, festivals, web, deep, people, extract, enrich, milestones, venues, rank, charts, radio | +| `/content/*` | create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, template-detail, validate, estimate | +| `/chat/*` | stream, create, chats, artist, segment, messages, messages-copy, messages-trailing-delete, update, delete, generate, compact | +| `/artists/*` | list, create, delete | +| `/artist/*` | segments, socials, socials-scrape, profile | +| `/songs/*` | songs, create, analyze, analyze-presets, catalogs, catalogs-create, catalogs-delete, catalog-songs, catalog-songs-add, catalog-songs-delete | +| `/tasks/*` | get, create, update, delete, runs | +| `/spotify/*` | search, artist, artist-albums, artist-top-tracks, album | +| `/instagram/*` | comments, profiles | +| `/x/*` | search, trends | +| `/connectors/*` | list, authorize, disconnect | +| `/accounts/*` | get, id, create, update, add-artist | +| `/organizations/*` | list, create, add-artist | +| `/sandboxes/*` | list, create, snapshot, delete, setup, file, upload | +| `/content-agent/*` | webhook, callback | +| `/agents/*` | signup, verify *(unauthenticated)* | +| `/pulses/*` | update, list | +| `/workspaces/*` | create | +| `/subscriptions/*` | get | +| `/notifications/*` | create | + +Authentication: `x-api-key` header (or `Authorization: Bearer ` for Privy). Get a key instantly via `POST /api/agents/signup` with an `agent+` email — no verification required. + +[OpenAPI specification →](https://github.com/sweetmantech/docs/blob/main/api-reference/openapi.json) diff --git a/mcp.mdx b/mcp.mdx index 05709d8..c72b26a 100644 --- a/mcp.mdx +++ b/mcp.mdx @@ -1,78 +1,73 @@ --- -title: "MCP" -description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP) server." +title: "MCP Server" +description: "Connect any AI agent to Recoup via the Model Context Protocol — Claude, ChatGPT, Cursor, and more." --- -The Recoup API exposes an [MCP](https://modelcontextprotocol.io/) server that AI agents can connect to for tool use. The server is available at: +Recoup exposes an [MCP](https://modelcontextprotocol.io/) server so any AI agent can use Recoup tools natively. Claude, ChatGPT, Cursor, Windsurf, and any MCP-compatible agent can research artists, generate content, and automate tasks — without writing API calls. ``` https://recoup-api.vercel.app/mcp ``` -## Authentication +## Setup -All MCP tools require an API key. Pass it as a Bearer token in the `Authorization` header when connecting to the MCP server. +Pass your API key as a Bearer token when connecting: -You can get a key from the [API Keys page](https://chat.recoupable.com/keys). +```typescript +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; -## Tools +const transport = new StreamableHTTPClientTransport( + new URL("https://recoup-api.vercel.app/mcp"), + { requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } }, +); -### prompt_sandbox +const client = new Client({ name: "my-agent", version: "1.0.0" }); +await client.connect(transport); +``` + +Get a key from the [API Keys page](https://chat.recoupable.com/keys) or use the [agent signup](/agents) for instant generation. + +--- -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. +## Available tools -Returns raw `stdout` and `stderr` from the command. The sandbox stays alive after each prompt for follow-up interactions. +### prompt_sandbox -**Input schema:** +Send a prompt to a persistent per-account sandbox. The sandbox is reused across calls — if one is running, it picks up where you left off. Otherwise a new one is created from the account's latest snapshot. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `prompt` | `string` | Yes | The prompt to send to OpenClaw in the sandbox. | +| `prompt` | `string` | Yes | The prompt to execute in the sandbox | -**Response fields:** +**Response:** | 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. | - -**Example usage (TypeScript with MCP SDK):** +| `sandboxId` | `string` | The sandbox ID | +| `stdout` | `string` | Standard output | +| `stderr` | `string` | Standard error | +| `exitCode` | `number` | Exit code (`0` = success) | +| `created` | `boolean` | `true` if a new sandbox was created | ```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); - const result = await client.callTool({ name: "prompt_sandbox", arguments: { prompt: "list all files in the orgs directory" }, }); - console.log(result.content); ``` ### 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. - -**Input schema:** +Create a new sandbox and run a shell command or prompt asynchronously via a background task. Returns a sandbox ID and run ID to track progress. | 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). | +| `command` | `string` | No | Shell command (cannot be used with `prompt`) | +| `args` | `string[]` | No | Command arguments | +| `cwd` | `string` | No | Working directory | +| `prompt` | `string` | No | Prompt (cannot be used with `command`) | +| `account_id` | `string` | No | Target account (org keys only) | + +See [`POST /api/sandboxes`](/api-reference/sandboxes/create) for the equivalent REST endpoint. diff --git a/quickstart.mdx b/quickstart.mdx index 95dd61b..ed74a56 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,11 +1,9 @@ --- title: "Quickstart" -description: "Get a Recoup API key in one call and make your first request — no browser, no dashboard." +description: "API key in 10 seconds. First request in 30. No signup form, no dashboard." --- -## Quickest start - -Sign up your agent and get an API key in a single API call — no dashboard, no browser, no human in the loop. This one-liner signs up a fresh `agent+` address and exports the returned key to `$RECOUP_API_KEY`: +## 1. Get your API key ```bash export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ @@ -13,163 +11,118 @@ export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agent -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) ``` -Verify it worked: - -```bash -curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id -``` +That's it. `$RECOUP_API_KEY` is now ready. No email verification, no waiting. -The `agent+{timestamp}@recoupable.com` shape is the fastest path for agents — it guarantees a fresh `agent+` address and returns an API key instantly without email verification. +Prefer the dashboard? Create keys at [chat.recoupable.com/keys](https://chat.recoupable.com/keys). See the [Agents guide](/agents) for the full signup flow with email verification. -For the full signup + email-verification flow, see the [Agents guide](/agents). - -## Base URL - -All API requests should be made to: - -```bash -https://recoup-api.vercel.app/api -``` +--- -## Your First Request +## 2. Search for an artist -Once you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks: +The research API has 30 endpoints. Start with search — it works for any artist on earth: ```bash cURL -curl -X GET "https://recoup-api.vercel.app/api/tasks" \ - -H "Content-Type: application/json" \ - -H "x-api-key: YOUR_API_KEY" +curl "https://recoup-api.vercel.app/api/research?q=Drake" \ + -H "x-api-key: $RECOUP_API_KEY" ``` ```python Python import requests -headers = { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY" -} - response = requests.get( - "https://recoup-api.vercel.app/api/tasks", - headers=headers + "https://recoup-api.vercel.app/api/research", + params={"q": "Drake"}, + headers={"x-api-key": "YOUR_API_KEY"} ) print(response.json()) ``` ```javascript JavaScript -const response = await fetch("https://recoup-api.vercel.app/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://recoup-api.vercel.app/api/research?q=Drake", + { headers: { "x-api-key": "YOUR_API_KEY" } } +); +console.log(await response.json()); ``` -```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://recoup-api.vercel.app/api/tasks", { - headers: { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY", - }, -}); -const data: TasksResponse = await response.json(); -console.log(data.tasks); + + +From the CLI: + +```bash +npm install -g @recoupable/cli +recoup research "Drake" ``` - +--- + +## 3. Go deeper + +Once you have an artist, pull data across 14 platforms: + +```bash +# Streaming metrics (Spotify, Instagram, TikTok, YouTube, and 10 more) +curl "https://recoup-api.vercel.app/api/research/metrics?q=Drake&source=spotify" \ + -H "x-api-key: $RECOUP_API_KEY" + +# Audience demographics (age, gender, geography) +curl "https://recoup-api.vercel.app/api/research/audience?q=Drake" \ + -H "x-api-key: $RECOUP_API_KEY" -**Example Response:** - -```json -{ - "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 - } - ] -} +# Editorial playlist placements +curl "https://recoup-api.vercel.app/api/research/playlists?q=Drake&editorial=true" \ + -H "x-api-key: $RECOUP_API_KEY" ``` - -For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). - +The research API has 30 endpoints total — see the [Research reference](/api-reference/research/search) for the full list. -## Prefer the dashboard? +--- -If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint: +## 4. Connect your AI agent -1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.com/keys) -2. Sign in with your account -3. Enter a descriptive name (e.g. "Production Server") -4. Click **Create API Key** +If you're using Claude, ChatGPT, Cursor, or any MCP-compatible tool, connect directly: - -Copy and securely store your API key immediately — it will only be shown once. - +``` +https://recoup-api.vercel.app/mcp +``` -## Next Steps +Pass your API key as a Bearer token. Your agent gets access to all 40+ tools. See the [MCP guide](/mcp) for setup. -With your API key ready, you can now: +--- + +## Next steps - Fetch artist profiles, social accounts, and segments. + 30 endpoints — metrics across 14 platforms, audience data, playlists, career history, web research. - Access fan data across all connected social platforms. + Generate images, videos, captions. Transcribe audio. Upscale and analyze content. - Build AI-powered conversations with artist context. + Full command reference — research, content, chats, sandboxes, tasks. - Schedule and automate recurring tasks. + API keys, Bearer tokens, org-level access, and security. - -## 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 d66dd2ae40b86e9c5e1d9139b86143c06ec55be9 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 12 Apr 2026 16:12:23 -0400 Subject: [PATCH 02/24] feat: rethink docs taxonomy around agent workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Old categories organized by data type (Releases, Social, Platform). New categories organized by what agents actually do: - Research: ALL intelligence from ANY source (chat, research, Spotify, Instagram, X, web intel, social scraping) - Artists: roster management (artists, songs, catalogs, fans, segments, posts, comments) - Content: media production (pipeline, 7 primitives, content agent) - Automation: scheduled agent work (tasks, sandboxes, connectors, pulses, notifications) - Accounts: business infrastructure (agent onboarding, accounts, orgs, workspaces, subscriptions, admins) Key moves: - Tasks out of "Releases" → Automation (they automate anything, not just releases) - Sandboxes out of "Content" → Automation (agent execution infrastructure) - Connectors out of "Social" → Automation (OAuth for any tool, not just social) - Spotify/Instagram/X into Research (they're data sources) - Fans/Segments/Posts/Comments into Artists (audience is part of roster context) - Research split into Artist Research + Web Intelligence subgroups - Content split into Pipeline + Primitives subgroups - Homepage updated with real value prop from strategy docs - Recoupable wordmark logos (clean vector SVGs) Made-with: Cursor --- docs.json | 181 +++++++++++++++++++++++-------------------------- index.mdx | 54 ++++++++------- logo/dark.svg | 11 +++ logo/light.svg | 14 ++-- 4 files changed, 134 insertions(+), 126 deletions(-) create mode 100644 logo/dark.svg diff --git a/docs.json b/docs.json index 8e7e9ec..9eb6ae3 100644 --- a/docs.json +++ b/docs.json @@ -24,7 +24,8 @@ "background": { "decoration": "windows", "color": { - "dark": "#080808" + "light": "#f7f7f7", + "dark": "#0a0a0a" } }, "styling": { @@ -62,7 +63,7 @@ "tab": "Research", "groups": [ { - "group": "Chat", + "group": "AI Chat", "pages": [ "api-reference/chat/stream", "api-reference/chat/create", @@ -79,7 +80,7 @@ ] }, { - "group": "Research", + "group": "Artist Research", "pages": [ "api-reference/research/search", "api-reference/research/lookup", @@ -101,33 +102,69 @@ "api-reference/research/discover", "api-reference/research/genres", "api-reference/research/festivals", - "api-reference/research/web", - "api-reference/research/deep", - "api-reference/research/people", - "api-reference/research/extract", - "api-reference/research/enrich", "api-reference/research/milestones", "api-reference/research/venues", "api-reference/research/rank", "api-reference/research/charts", "api-reference/research/radio" ] + }, + { + "group": "Web Intelligence", + "pages": [ + "api-reference/research/web", + "api-reference/research/deep", + "api-reference/research/people", + "api-reference/research/extract", + "api-reference/research/enrich" + ] + }, + { + "group": "Spotify", + "pages": [ + "api-reference/spotify/search", + "api-reference/spotify/artist", + "api-reference/spotify/artist-albums", + "api-reference/spotify/artist-top-tracks", + "api-reference/spotify/album" + ] + }, + { + "group": "Instagram", + "pages": [ + "api-reference/instagram/comments", + "api-reference/instagram/profiles" + ] + }, + { + "group": "X (Twitter)", + "pages": [ + "api-reference/x/search", + "api-reference/x/trends" + ] + }, + { + "group": "Social Scraping", + "pages": [ + "api-reference/social/scrape", + "api-reference/social/posts", + "api-reference/apify/scraper" + ] } ] }, { - "tab": "Releases", + "tab": "Artists", "groups": [ { - "group": "Artists", + "group": "Artist Management", "pages": [ "api-reference/artists/list", "api-reference/artists/create", "api-reference/artists/delete", - "api-reference/artist/segments", + "api-reference/artist/profile", "api-reference/artist/socials", - "api-reference/artist/socials-scrape", - "api-reference/artist/profile" + "api-reference/artist/socials-scrape" ] }, { @@ -145,21 +182,15 @@ "api-reference/songs/catalog-songs-delete" ] }, - { - "group": "Tasks", - "pages": [ - "api-reference/tasks/get", - "api-reference/tasks/create", - "api-reference/tasks/update", - "api-reference/tasks/delete", - "api-reference/tasks/runs" - ] - }, { "group": "Fans & Segments", "pages": [ + "api-reference/artist/segments", "api-reference/segment/fans", - "api-reference/fans/get" + "api-reference/fans/get", + "api-reference/posts/get", + "api-reference/post/comments", + "api-reference/comments/get" ] } ] @@ -168,16 +199,9 @@ "tab": "Content", "groups": [ { - "group": "Content Creation", + "group": "Content Pipeline", "pages": [ "api-reference/content/create", - "api-reference/content/generate-image", - "api-reference/content/generate-video", - "api-reference/content/generate-caption", - "api-reference/content/transcribe-audio", - "api-reference/content/edit", - "api-reference/content/upscale", - "api-reference/content/analyze-video", "api-reference/content/templates", "api-reference/content/template-detail", "api-reference/content/validate", @@ -185,11 +209,17 @@ ] }, { - "group": "Posts & Comments", + "group": "Primitives", "pages": [ - "api-reference/posts/get", - "api-reference/post/comments", - "api-reference/comments/get" + "api-reference/content/generate-image", + "api-reference/content/generate-video", + "api-reference/content/generate-caption", + "api-reference/content/transcribe-audio", + "api-reference/content/edit", + "api-reference/content/upscale", + "api-reference/content/analyze-video", + "api-reference/image/generation", + "api-reference/transcribe/audio" ] }, { @@ -198,17 +228,20 @@ "api-reference/content-agent/webhook", "api-reference/content-agent/callback" ] - }, - { - "group": "Image", - "pages": [ - "api-reference/image/generation" - ] - }, + } + ] + }, + { + "tab": "Automation", + "groups": [ { - "group": "Transcribe", + "group": "Scheduled Tasks", "pages": [ - "api-reference/transcribe/audio" + "api-reference/tasks/get", + "api-reference/tasks/create", + "api-reference/tasks/update", + "api-reference/tasks/delete", + "api-reference/tasks/runs" ] }, { @@ -222,12 +255,7 @@ "api-reference/sandboxes/file", "api-reference/sandboxes/upload" ] - } - ] - }, - { - "tab": "Social", - "groups": [ + }, { "group": "Connectors", "pages": [ @@ -237,46 +265,22 @@ ] }, { - "group": "Spotify", - "pages": [ - "api-reference/spotify/search", - "api-reference/spotify/artist", - "api-reference/spotify/artist-albums", - "api-reference/spotify/artist-top-tracks", - "api-reference/spotify/album" - ] - }, - { - "group": "Instagram", - "pages": [ - "api-reference/instagram/comments", - "api-reference/instagram/profiles" - ] - }, - { - "group": "X (Twitter)", - "pages": [ - "api-reference/x/search", - "api-reference/x/trends" - ] - }, - { - "group": "Social", + "group": "Pulses", "pages": [ - "api-reference/social/scrape", - "api-reference/social/posts" + "api-reference/pulses/update", + "api-reference/pulses/list" ] }, { - "group": "Apify", + "group": "Notifications", "pages": [ - "api-reference/apify/scraper" + "api-reference/notifications/create" ] } ] }, { - "tab": "Platform", + "tab": "Accounts", "groups": [ { "group": "Agent Onboarding", @@ -303,13 +307,6 @@ "api-reference/organizations/add-artist" ] }, - { - "group": "Pulses", - "pages": [ - "api-reference/pulses/update", - "api-reference/pulses/list" - ] - }, { "group": "Workspaces", "pages": [ @@ -322,12 +319,6 @@ "api-reference/subscriptions/get" ] }, - { - "group": "Notifications", - "pages": [ - "api-reference/notifications/create" - ] - }, { "group": "Admins", "pages": [ @@ -361,7 +352,7 @@ }, "logo": { "light": "/logo/light.svg", - "dark": "/logo/dark.png", + "dark": "/logo/dark.svg", "href": "https://recoupable.com" }, "navbar": { diff --git a/index.mdx b/index.mdx index c513174..58dbba1 100644 --- a/index.mdx +++ b/index.mdx @@ -1,9 +1,11 @@ --- title: "Recoup API" -description: "Music intelligence API — research any artist, generate content, and automate music operations. Built for developers and AI agents." +description: "Music intelligence API — the infrastructure for agents to run record labels. 40+ tools for artist research, content creation, and music business automation." --- -Music intelligence for every team in music. 40+ tools for artist research, content creation, social analytics, and business automation — accessible from your code, your CLI, or your AI agent. +The infrastructure for agents to run record labels. 40+ tools that give artists the power of a major label in their pocket, and executives a way to scale operations without headcount. + +Recoup captures context around your catalog, artists, releases, and fans — then context-engineers it so agents get exactly what they need, exactly when they need it, to perform the work of a major label. Programmatically. ## Get an API key @@ -16,7 +18,7 @@ export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agent ``` -The `agent+` prefix bypasses email verification entirely. Your API key comes back in the response — ready to use immediately. +The `agent+` prefix bypasses email verification. Your API key comes back in the response — ready to use immediately. --- @@ -36,7 +38,7 @@ The `agent+` prefix bypasses email verification entirely. Your API key comes bac icon="cpu" href="/mcp" > - Connect Claude, ChatGPT, Cursor, or any MCP-compatible agent directly to Recoup. One URL. + Connect Claude, ChatGPT, Cursor, or any MCP-compatible agent directly. One URL. - Search any artist. Pull streaming metrics across 14 platforms, audience demographics, playlist placements, career timelines, competitive analysis, web intelligence, and people search. + Everything about any artist from any source. 30 research endpoints across 14 platforms, plus AI chat, Spotify, Instagram, X, web intelligence, and deep research reports. - Generate images, videos, and captions with AI. Transcribe audio, edit media, upscale resolution, and analyze video content. Each primitive works independently. + Manage the roster. Artists, profiles, social accounts, songs, catalogs, fan segments, posts, and comments — the full context layer. - Manage artists, songs, and catalogs. Analyze tracks with AI. Schedule cron-based tasks to automate recurring work. + Seven independent primitives for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each primitive directly. - Spotify, Instagram, X, and generic social scraping. Search artists, pull profiles and comments, track trends, and manage OAuth connectors. + Scheduled tasks, sandboxed code execution, OAuth connectors, automated pulses, and notifications. The engine that lets agents work while you sleep. - Accounts, organizations, workspaces, subscriptions, automated pulses, notifications, and sandboxed code execution. + Accounts, organizations, workspaces, subscriptions, and agent onboarding. The business infrastructure. --- @@ -144,26 +148,26 @@ If you are an LLM or AI agent, here is the complete endpoint map. All paths are | Domain | Endpoints | |--------|-----------| | `/research/*` | search, lookup, profile, metrics, audience, cities, similar, urls, instagram-posts, playlists, albums, tracks, track, career, insights, playlist, curator, discover, genres, festivals, web, deep, people, extract, enrich, milestones, venues, rank, charts, radio | -| `/content/*` | create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, template-detail, validate, estimate | | `/chat/*` | stream, create, chats, artist, segment, messages, messages-copy, messages-trailing-delete, update, delete, generate, compact | +| `/content/*` | create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, template-detail, validate, estimate | | `/artists/*` | list, create, delete | -| `/artist/*` | segments, socials, socials-scrape, profile | +| `/artist/*` | profile, segments, socials, socials-scrape | | `/songs/*` | songs, create, analyze, analyze-presets, catalogs, catalogs-create, catalogs-delete, catalog-songs, catalog-songs-add, catalog-songs-delete | | `/tasks/*` | get, create, update, delete, runs | +| `/sandboxes/*` | list, create, snapshot, delete, setup, file, upload | | `/spotify/*` | search, artist, artist-albums, artist-top-tracks, album | | `/instagram/*` | comments, profiles | | `/x/*` | search, trends | | `/connectors/*` | list, authorize, disconnect | | `/accounts/*` | get, id, create, update, add-artist | | `/organizations/*` | list, create, add-artist | -| `/sandboxes/*` | list, create, snapshot, delete, setup, file, upload | | `/content-agent/*` | webhook, callback | | `/agents/*` | signup, verify *(unauthenticated)* | | `/pulses/*` | update, list | +| `/notifications/*` | create | | `/workspaces/*` | create | | `/subscriptions/*` | get | -| `/notifications/*` | create | -Authentication: `x-api-key` header (or `Authorization: Bearer ` for Privy). Get a key instantly via `POST /api/agents/signup` with an `agent+` email — no verification required. +Authentication: `x-api-key` header (or `Authorization: Bearer ` for Privy). Get a key instantly via `POST /api/agents/signup` with an `agent+` email. [OpenAPI specification →](https://github.com/sweetmantech/docs/blob/main/api-reference/openapi.json) diff --git a/logo/dark.svg b/logo/dark.svg new file mode 100644 index 0000000..eb8f7f3 --- /dev/null +++ b/logo/dark.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/logo/light.svg b/logo/light.svg index fa35f85..d86546a 100644 --- a/logo/light.svg +++ b/logo/light.svg @@ -1,9 +1,11 @@ - - + + + + + - - - - + + + From 712783b7c54c13deb7d1b28c7a2b9a0f3a00497f Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 12 Apr 2026 16:21:33 -0400 Subject: [PATCH 03/24] refactor: split Catalog tab, move Connectors to Accounts, standardize on "tools" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - New Catalog tab: Songs + Catalogs separated from Artists (catalogs are label-level, not artist-level) - Artists tab: now just roster management + fans/segments - Connectors moved from Automation → Accounts (they're per-account OAuth connections) - "Primitives" → "Content Tools", "endpoints" → "tools" everywhere (matches marketing "40+ agent tools") - Homepage cards updated to reflect 7-tab structure Made-with: Cursor --- content-agent.mdx | 4 ++-- docs.json | 54 ++++++++++++++++++++++++++++------------------- index.mdx | 30 +++++++++++++++----------- quickstart.mdx | 12 +++++------ 4 files changed, 58 insertions(+), 42 deletions(-) diff --git a/content-agent.mdx b/content-agent.mdx index 6bd291b..471cf1a 100644 --- a/content-agent.mdx +++ b/content-agent.mdx @@ -37,9 +37,9 @@ The Recoup Content Agent is a Slack bot that generates social-ready artist video --- -## Content primitives +## Content tools -The content API provides seven independent primitives. Each does one thing well. You orchestrate them. +The content API provides seven independent tools. Each does one thing well. You orchestrate them. | Primitive | Endpoint | What it does | |-----------|----------|-------------| diff --git a/docs.json b/docs.json index 9eb6ae3..d6e3d7f 100644 --- a/docs.json +++ b/docs.json @@ -168,12 +168,33 @@ ] }, { - "group": "Songs & Catalogs", + "group": "Fans & Segments", + "pages": [ + "api-reference/artist/segments", + "api-reference/segment/fans", + "api-reference/fans/get", + "api-reference/posts/get", + "api-reference/post/comments", + "api-reference/comments/get" + ] + } + ] + }, + { + "tab": "Catalog", + "groups": [ + { + "group": "Songs", "pages": [ "api-reference/songs/songs", "api-reference/songs/create", "api-reference/songs/analyze", - "api-reference/songs/analyze-presets", + "api-reference/songs/analyze-presets" + ] + }, + { + "group": "Catalogs", + "pages": [ "api-reference/songs/catalogs", "api-reference/songs/catalogs-create", "api-reference/songs/catalogs-delete", @@ -181,17 +202,6 @@ "api-reference/songs/catalog-songs-add", "api-reference/songs/catalog-songs-delete" ] - }, - { - "group": "Fans & Segments", - "pages": [ - "api-reference/artist/segments", - "api-reference/segment/fans", - "api-reference/fans/get", - "api-reference/posts/get", - "api-reference/post/comments", - "api-reference/comments/get" - ] } ] }, @@ -209,7 +219,7 @@ ] }, { - "group": "Primitives", + "group": "Content Tools", "pages": [ "api-reference/content/generate-image", "api-reference/content/generate-video", @@ -256,14 +266,6 @@ "api-reference/sandboxes/upload" ] }, - { - "group": "Connectors", - "pages": [ - "api-reference/connectors/list", - "api-reference/connectors/authorize", - "api-reference/connectors/disconnect" - ] - }, { "group": "Pulses", "pages": [ @@ -307,6 +309,14 @@ "api-reference/organizations/add-artist" ] }, + { + "group": "Connectors", + "pages": [ + "api-reference/connectors/list", + "api-reference/connectors/authorize", + "api-reference/connectors/disconnect" + ] + }, { "group": "Workspaces", "pages": [ diff --git a/index.mdx b/index.mdx index 58dbba1..0100f37 100644 --- a/index.mdx +++ b/index.mdx @@ -61,39 +61,45 @@ Organized by what agents actually do when running a label. icon="search" href="/api-reference/research/search" > - Everything about any artist from any source. 30 research endpoints across 14 platforms, plus AI chat, Spotify, Instagram, X, web intelligence, and deep research reports. + Everything about any artist from any source. 30+ research tools across 14 platforms, plus AI chat, Spotify, Instagram, X, web intelligence, and deep research reports. - Manage the roster. Artists, profiles, social accounts, songs, catalogs, fan segments, posts, and comments — the full context layer. + Manage the roster. Artist profiles, social accounts, fan segments, posts, and comments — the people side of your label. + + + Songs, catalogs, and AI-powered audio analysis. Organize releases into collections. The music side of your label. - Seven independent primitives for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each primitive directly. + 7 content tools for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each tool directly. - Scheduled tasks, sandboxed code execution, OAuth connectors, automated pulses, and notifications. The engine that lets agents work while you sleep. + Scheduled tasks, sandboxed code execution, automated pulses, and notifications. The engine that lets agents work while you sleep. + + + Accounts, organizations, connectors, workspaces, and subscriptions. The business infrastructure. - - Accounts, organizations, workspaces, subscriptions, and agent onboarding. The business infrastructure. - - --- ## Guides diff --git a/quickstart.mdx b/quickstart.mdx index ed74a56..885c3c6 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -21,7 +21,7 @@ Prefer the dashboard? Create keys at [chat.recoupable.com/keys](https://chat.rec ## 2. Search for an artist -The research API has 30 endpoints. Start with search — it works for any artist on earth: +The research API has 30+ tools. Start with search — it works for any artist on earth: @@ -78,7 +78,7 @@ curl "https://recoup-api.vercel.app/api/research/playlists?q=Drake&editorial=tru -H "x-api-key: $RECOUP_API_KEY" ``` -The research API has 30 endpoints total — see the [Research reference](/api-reference/research/search) for the full list. +See the [Research tab](/api-reference/research/search) for the full list of 30+ research tools. --- @@ -98,18 +98,18 @@ Pass your API key as a Bearer token. Your agent gets access to all 40+ tools. Se - 30 endpoints — metrics across 14 platforms, audience data, playlists, career history, web research. + 30+ tools — metrics across 14 platforms, audience data, playlists, career history, web intelligence. - Generate images, videos, captions. Transcribe audio. Upscale and analyze content. + 7 tools for images, videos, captions, transcription, editing, upscaling, and analysis. Date: Mon, 13 Apr 2026 12:58:35 -0400 Subject: [PATCH 04/24] fix: use "endpoints" in technical docs, keep "tools" in marketing/MCP contexts - Homepage intro + meta descriptions: "40+ tools" (marketing copy) - MCP page: "tools" (MCP protocol term) - All technical docs: "endpoints" (industry standard for API docs) Made-with: Cursor --- agents.mdx | 2 +- content-agent.mdx | 4 ++-- docs.json | 2 +- index.mdx | 4 ++-- quickstart.mdx | 14 +++++++------- 5 files changed, 13 insertions(+), 13 deletions(-) diff --git a/agents.mdx b/agents.mdx index 181f936..c9703f6 100644 --- a/agents.mdx +++ b/agents.mdx @@ -60,7 +60,7 @@ curl "https://recoup-api.vercel.app/api/research?q=Drake" \ -H "x-api-key: $RECOUP_API_KEY" ``` -That request searches the entire music industry for "Drake" and returns structured artist data. From here, you have access to 40+ tools — see the [Quickstart](/quickstart) for a guided walkthrough, or browse the [endpoint map](/#for-ai-agents) for the full API surface. +That request searches the entire music industry for "Drake" and returns structured artist data. From here, you have access to 40+ endpoints — see the [Quickstart](/quickstart) for a guided walkthrough, or browse the [endpoint map](/#for-ai-agents) for the full API surface. --- diff --git a/content-agent.mdx b/content-agent.mdx index 471cf1a..a2946da 100644 --- a/content-agent.mdx +++ b/content-agent.mdx @@ -37,9 +37,9 @@ The Recoup Content Agent is a Slack bot that generates social-ready artist video --- -## Content tools +## Content endpoints -The content API provides seven independent tools. Each does one thing well. You orchestrate them. +The content API provides seven independent endpoints. Each does one thing well. You orchestrate them. | Primitive | Endpoint | What it does | |-----------|----------|-------------| diff --git a/docs.json b/docs.json index d6e3d7f..f3cc3e4 100644 --- a/docs.json +++ b/docs.json @@ -219,7 +219,7 @@ ] }, { - "group": "Content Tools", + "group": "Content Endpoints", "pages": [ "api-reference/content/generate-image", "api-reference/content/generate-video", diff --git a/index.mdx b/index.mdx index 0100f37..01adbe7 100644 --- a/index.mdx +++ b/index.mdx @@ -31,7 +31,7 @@ The `agent+` prefix bypasses email verification. Your API key comes back in the icon="code" href="/quickstart" > - Standard HTTP endpoints. Pass your API key in `x-api-key` and call any of the 40+ tools. + Standard HTTP endpoints. Pass your API key in `x-api-key` and call any of the 40+ endpoints. - 7 content tools for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each tool directly. + 7 endpoints for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each endpoint directly. @@ -78,7 +78,7 @@ curl "https://recoup-api.vercel.app/api/research/playlists?q=Drake&editorial=tru -H "x-api-key: $RECOUP_API_KEY" ``` -See the [Research tab](/api-reference/research/search) for the full list of 30+ research tools. +See the [Research tab](/api-reference/research/search) for all 30+ research endpoints. --- @@ -90,7 +90,7 @@ If you're using Claude, ChatGPT, Cursor, or any MCP-compatible tool, connect dir https://recoup-api.vercel.app/mcp ``` -Pass your API key as a Bearer token. Your agent gets access to all 40+ tools. See the [MCP guide](/mcp) for setup. +Pass your API key as a Bearer token. Your agent gets access to all 40+ endpoints. See the [MCP guide](/mcp) for setup. --- @@ -98,18 +98,18 @@ Pass your API key as a Bearer token. Your agent gets access to all 40+ tools. Se - 30+ tools — metrics across 14 platforms, audience data, playlists, career history, web intelligence. + 30+ endpoints — metrics across 14 platforms, audience data, playlists, career history, web intelligence. - 7 tools for images, videos, captions, transcription, editing, upscaling, and analysis. + 7 endpoints for images, videos, captions, transcription, editing, upscaling, and analysis. Date: Mon, 13 Apr 2026 13:20:42 -0400 Subject: [PATCH 05/24] feat: add problem statement, core concepts, how-it-works flow, rename to Recoupable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Homepage now has the narrative structure of world-class docs: - Problem statement ("Running a record label takes a team") - What is Recoupable? (infrastructure for agents to run labels) - Core concepts table (Artist, Catalog, Chat, Task, Sandbox, Pulse, Connector) - How it works flow (Connect → Research → Build context → Create → Automate) - Then quickstart, interfaces, API reference, guides, agent endpoint map Inspired by Claude Managed Agents (concepts table, how-it-works steps), Paperclip (problem-first framing), and OpenClaw (clear what-is explanation). Site name: "Recoup" → "Recoupable" everywhere. Made-with: Cursor --- docs.json | 5 ++--- index.mdx | 54 +++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 49 insertions(+), 10 deletions(-) diff --git a/docs.json b/docs.json index f3cc3e4..2ee38c9 100644 --- a/docs.json +++ b/docs.json @@ -1,7 +1,7 @@ { "$schema": "https://mintlify.com/docs.json", "theme": "sequoia", - "name": "Recoup", + "name": "Recoupable", "colors": { "primary": "#0a0a0a", "light": "#ededed", @@ -22,7 +22,6 @@ } }, "background": { - "decoration": "windows", "color": { "light": "#f7f7f7", "dark": "#0a0a0a" @@ -404,7 +403,7 @@ }, "metatags": { "og:image": "/images/icon-with-background.png", - "og:site_name": "Recoup API", + "og:site_name": "Recoupable API", "og:description": "Music intelligence API — 40+ tools for artist research, content creation, and music business automation. Built for developers and AI agents.", "twitter:card": "summary_large_image" } diff --git a/index.mdx b/index.mdx index 01adbe7..cd3f329 100644 --- a/index.mdx +++ b/index.mdx @@ -1,11 +1,51 @@ --- -title: "Recoup API" -description: "Music intelligence API — the infrastructure for agents to run record labels. 40+ tools for artist research, content creation, and music business automation." +title: "Recoupable API" +description: "The infrastructure for agents to run record labels. Research, content, catalog management, and automation — all programmable." --- -The infrastructure for agents to run record labels. 40+ tools that give artists the power of a major label in their pocket, and executives a way to scale operations without headcount. +## The problem -Recoup captures context around your catalog, artists, releases, and fans — then context-engineers it so agents get exactly what they need, exactly when they need it, to perform the work of a major label. Programmatically. +Running a record label takes a team. Research, content, marketing, distribution, fan engagement, catalog management — it's a full company of work. Most artists can't afford that team. Most executives can't scale it. + +## What is Recoupable? + +Recoupable is the infrastructure that lets AI agents run record labels. It captures all the context around your catalog, artists, releases, and fans — then context-engineers it so agents get exactly what they need, exactly when they need it, to perform the work of a major label. Programmatically. + +It gives artists the power of a major label in their pocket, and executives a way to scale operations without headcount. + +## Core concepts + +| Concept | What it is | +|---------|------------| +| **Artist** | A managed artist account with profile, social handles, and linked catalog. The unit agents work on behalf of. | +| **Catalog** | A collection of songs belonging to a label or artist. Catalogs can be analyzed, organized, and used as context for content creation. | +| **Chat** | An AI conversation with artist context. Agents use chats to research, plan, and execute — with full memory of prior work. | +| **Task** | A scheduled prompt that runs on a cron against an artist. Tasks automate recurring agent work — daily reports, weekly content, monthly analysis. | +| **Sandbox** | An isolated Linux environment where agents can run code, manage files, and execute complex workflows. Persistent across calls. | +| **Pulse** | An automated digest channel. When enabled, Recoupable sends periodic intelligence updates about an artist to the account owner. | +| **Connector** | An OAuth connection to an external platform (Spotify, Google Sheets, TikTok, etc.) linked to an account. | + +## How it works + + + + Get an API key via the agent signup endpoint. Connect via REST API, MCP server, or CLI — whichever interface your agent prefers. + + + Pull data on any artist from 14+ platforms. Streaming metrics, audience demographics, playlist placements, career history, web intelligence, and competitive analysis. + + + Create artists, link social accounts, build catalogs of songs, and segment fans. Recoupable captures this context so every subsequent agent call is informed. + + + Generate images, videos, and captions with AI. Transcribe audio, edit media, upscale quality. Seven independent content endpoints, or run the full pipeline in one call. + + + Schedule recurring tasks, spin up sandboxes for complex workflows, enable pulses for automated intelligence, and send notifications. Agents work while you sleep. + + + +--- ## Get an API key @@ -23,7 +63,7 @@ The `agent+` prefix bypasses email verification. Your API key comes back in the --- -## How you access it +## Three interfaces - Everything about any artist from any source. 30+ research tools across 14 platforms, plus AI chat, Spotify, Instagram, X, web intelligence, and deep research reports. + Everything about any artist from any source. 30+ research endpoints across 14 platforms, plus AI chat, Spotify, Instagram, X, web intelligence, and deep research reports. - 7 endpoints for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each endpoint directly. + 7 content endpoints for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each one directly. Date: Mon, 13 Apr 2026 20:58:09 -0400 Subject: [PATCH 06/24] feat: rebuild Agent Onboarding as operating manual, tighten homepage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agent Onboarding (agents.mdx) is now a real operating manual for AI agents: 1. Authenticate — key reuse, email verification flow with exact user prompt 2. Understand the roster — list artists, orgs, scoping behavior 3. Know the sandbox filesystem — full directory structure, RECOUP.md, content readiness 4. Decide what to do — decision tree (have roster? → research or create? → save? → automate?) Homepage changes: - Agent callout links to Agent guide (not Quickstart) — agents need the operating manual - Tightened intro to one paragraph (problem + solution, no repetition) - Info callout instead of Note/Tip (neutral styling) - AccordionGroup for core concepts Made-with: Cursor --- agents.mdx | 149 ++++++++++++++++++++++++++++++++++++++++------------- index.mdx | 50 +++++++++++------- 2 files changed, 146 insertions(+), 53 deletions(-) diff --git a/agents.mdx b/agents.mdx index c9703f6..d34ee1e 100644 --- a/agents.mdx +++ b/agents.mdx @@ -1,69 +1,148 @@ --- title: "Agent Onboarding" -description: "Get an API key programmatically — one call, no browser, no verification, no human in the loop." +description: "The operating manual for AI agents using the Recoupable API. Authentication, roster awareness, sandbox filesystem, and decision-making." --- -Two unauthenticated endpoints let any AI agent create an account and get an API key instantly. +This page is for AI agents. It tells you how to authenticate, understand your user's roster, navigate the sandbox filesystem, and decide what to do. -## Get a key +## 1. Authenticate -One POST. No auth required. Key comes back in the response. +If your user already has an API key, use it: ```bash +curl "https://recoup-api.vercel.app/api/accounts/id" \ + -H "x-api-key: USER_API_KEY" +``` + +If they don't have a key, generate one from their email. This sends a 6-digit verification code to their inbox — ask the user for the code. + +```bash +# Step 1 — request verification code curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ -H "Content-Type: application/json" \ - -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' -``` + -d '{"email": "user@example.com"}' -```json -{ - "account_id": "123e4567-e89b-12d3-a456-426614174000", - "api_key": "recoup_sk_abc123...", - "message": "If this is a new agent+ email, your API key is included." -} +# Step 2 — ask the user: "Check your email for a verification code and share it with me." + +# Step 3 — submit the code +curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ + -H "Content-Type: application/json" \ + -d '{"email": "user@example.com", "code": "123456"}' ``` -Store `api_key`. Pass it as `x-api-key` on every request. Done. +The verify response includes `api_key`. Store it and pass it as `x-api-key` on every subsequent request. - -**One-liner** — sign up and export in one command: + +`agent+` emails (e.g. `agent+test@recoupable.com`) skip verification and return a key instantly — but create a blank account with no roster or catalog. Use this for testing, not for working on behalf of an existing user. + + +--- + +## 2. Understand the roster + +After authenticating, check what the user has: ```bash -export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ - -H "Content-Type: application/json" \ - -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) +# List all artists available to this account +curl "https://recoup-api.vercel.app/api/artists" \ + -H "x-api-key: $API_KEY" + +# List organizations (labels/teams) the account belongs to +curl "https://recoup-api.vercel.app/api/organizations" \ + -H "x-api-key: $API_KEY" ``` - +**If the user has artists**, you can scope work to a specific artist by passing `artist_account_id` on supported endpoints. Research, content, tasks, and fan segments all become artist-specific. + +**If the user has organizations**, pass `organization_id` to scope to a specific label's roster. + +**If neither is specified**, you operate at the account level and can see everything available to the user. --- -## Endpoints +## 3. Know the sandbox filesystem -| Endpoint | Auth | What it does | -|----------|------|-------------| -| [`POST /api/agents/signup`](/api-reference/agents/signup) | None | New `agent+` emails → instant API key. Other emails → verification code sent via email. | -| [`POST /api/agents/verify`](/api-reference/agents/verify) | None | Submit verification code → receive API key. | +Each account has a persistent sandbox backed by a GitHub repo. This is where artist context lives — the files agents use to do informed work. - -`agent+{unique}@recoupable.com` emails always return a key immediately — no verification step. Combining `$(date +%s)` with `$RANDOM` guarantees unique addresses across calls. - +### Artist directory structure -Each signup or verification creates a new key without revoking existing ones. +``` +orgs/{org-name}/artists/{artist-slug}/ +├── RECOUP.md # Identity file (artistName, artistSlug, artistId) +├── context/ +│ ├── artist.md # Brand voice, bio, constraints +│ ├── audience.md # Audience insights, resonance +│ └── images/ +│ └── face-guide.png # Face reference for visual content +├── songs/{song-slug}/ +│ └── {song-slug}.mp3 # Audio files +├── releases/{release-slug}/ +│ └── RELEASE.md # Release plan and metadata +└── config/ + └── content-creation/ + └── config.json # Pipeline overrides +``` ---- +The `RECOUP.md` file ties the folder to the platform — it contains YAML frontmatter with `artistName`, `artistSlug`, and `artistId`. + +### Content readiness + +Before generating content for an artist, the minimum required files are: +- `context/images/face-guide.png` (face reference) +- At least one `.mp3` file under the artist tree + +Recommended for better output: +- `context/artist.md` (brand/voice) +- `context/audience.md` (audience insights) +- `context/era.json` (current era metadata) + +Use `POST /api/content/validate` with `artist_account_id` to check readiness programmatically. -## Use the key +### Accessing sandbox files ```bash -curl "https://recoup-api.vercel.app/api/research?q=Drake" \ - -H "x-api-key: $RECOUP_API_KEY" +# List the full file tree +curl "https://recoup-api.vercel.app/api/sandboxes" \ + -H "x-api-key: $API_KEY" + +# Read a specific file +curl "https://recoup-api.vercel.app/api/sandboxes/file?path=orgs/my-label/artists/drake/context/artist.md" \ + -H "x-api-key: $API_KEY" + +# Upload files to the repo +curl -X POST "https://recoup-api.vercel.app/api/sandboxes/files" \ + -H "x-api-key: $API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"files": [{"url": "https://...", "path": "orgs/my-label/artists/drake/context/audience.md"}]}' ``` -That request searches the entire music industry for "Drake" and returns structured artist data. From here, you have access to 40+ endpoints — see the [Quickstart](/quickstart) for a guided walkthrough, or browse the [endpoint map](/#for-ai-agents) for the full API surface. +--- + +## 4. Decide what to do + + + + Call `GET /api/artists`. If they have artists, list them and ask which one to work with. If not, you can research any artist with `GET /api/research?q=...` or create one with `POST /api/artists`. + + + **Research** — use the 30+ research endpoints. Pass `artist_account_id` to scope to a rostered artist, or search by name for any artist globally. + + **Content** — check readiness with `POST /api/content/validate`, then generate with the content endpoints. Artist context from the sandbox filesystem makes output more on-brand. + + + Research and generated content can be saved to the artist's sandbox directory for future context. Use `POST /api/sandboxes/files` to upload files, or use `POST /api/sandboxes` with a prompt to run complex file operations in the sandbox directly. + + + If the work should happen automatically, create a task with `POST /api/tasks` — set a cron schedule and a prompt. The task runs on schedule against the specified artist. + + --- -## For humans +## Base URL + +``` +https://recoup-api.vercel.app/api +``` -If your integration requires email verification (real email, not `agent+`), see the **Create a key** section in [Authentication](/authentication). +All endpoints require `x-api-key` header unless noted. See [Authentication](/authentication) for the full auth model, and the [endpoint map](/#for-ai-agents) for every available endpoint. diff --git a/index.mdx b/index.mdx index cd3f329..ed64e72 100644 --- a/index.mdx +++ b/index.mdx @@ -1,29 +1,43 @@ --- -title: "Recoupable API" -description: "The infrastructure for agents to run record labels. Research, content, catalog management, and automation — all programmable." +title: "What is Recoupable?" +description: "The infrastructure for agents to run record labels." --- -## The problem + +**AI agent?** Base URL: `https://recoup-api.vercel.app/api`. Use `x-api-key` if your user has a key. Otherwise, `POST /api/agents/signup` with their email — ask them for the verification code from their inbox, then `POST /api/agents/verify` to get a key. [Agent guide →](/agents) | [Endpoint map ↓](#for-ai-agents) + -Running a record label takes a team. Research, content, marketing, distribution, fan engagement, catalog management — it's a full company of work. Most artists can't afford that team. Most executives can't scale it. +Running a record label takes a full team. Most artists can't afford it. Most executives can't scale it. Recoupable captures context around your catalog, artists, releases, and fans, then context-engineers it so agents get exactly what they need to perform the work of a major label. Programmatically. -## What is Recoupable? - -Recoupable is the infrastructure that lets AI agents run record labels. It captures all the context around your catalog, artists, releases, and fans — then context-engineers it so agents get exactly what they need, exactly when they need it, to perform the work of a major label. Programmatically. - -It gives artists the power of a major label in their pocket, and executives a way to scale operations without headcount. +--- ## Core concepts -| Concept | What it is | -|---------|------------| -| **Artist** | A managed artist account with profile, social handles, and linked catalog. The unit agents work on behalf of. | -| **Catalog** | A collection of songs belonging to a label or artist. Catalogs can be analyzed, organized, and used as context for content creation. | -| **Chat** | An AI conversation with artist context. Agents use chats to research, plan, and execute — with full memory of prior work. | -| **Task** | A scheduled prompt that runs on a cron against an artist. Tasks automate recurring agent work — daily reports, weekly content, monthly analysis. | -| **Sandbox** | An isolated Linux environment where agents can run code, manage files, and execute complex workflows. Persistent across calls. | -| **Pulse** | An automated digest channel. When enabled, Recoupable sends periodic intelligence updates about an artist to the account owner. | -| **Connector** | An OAuth connection to an external platform (Spotify, Google Sheets, TikTok, etc.) linked to an account. | + + + Recoupable has three levels of identity. You can scope agent work at any level. + + | Concept | What it is | + |---------|------------| + | **Account** | A user or agent that authenticates with an API key. Your account owns artists, chats, tasks, and connectors. When no artist is specified, you see everything available to you. | + | **Organization** | A label or team that groups multiple accounts. Pass `organization_id` to scope to a specific roster. Accounts can belong to multiple organizations, each with different artists. | + | **Artist** | A managed artist with profile, social handles, and linked catalog. Pass `artist_account_id` to scope to a specific artist. When omitted, agents see all artists available to the account. | + + + | Concept | What it is | + |---------|------------| + | **Catalog** | A collection of songs belonging to a label or artist. Catalogs can be analyzed, organized, and used as context for content creation. | + | **Chat** | An AI conversation with artist context. Agents use chats to research, plan, and execute — with full memory of prior work. | + | **Connector** | An OAuth connection to an external platform (Spotify, Google Sheets, TikTok, etc.) linked to an account. | + + + | Concept | What it is | + |---------|------------| + | **Task** | A scheduled prompt that runs on a cron. Automates recurring agent work — daily reports, weekly content, monthly analysis. Scope to a specific artist or run across the whole roster. | + | **Sandbox** | An isolated Linux environment where agents can run code, manage files, and execute complex workflows. Persistent across calls. | + | **Pulse** | An automated digest channel. When enabled, Recoupable sends periodic intelligence updates about an artist to the account owner. | + + ## How it works From 6ba14ca95378221b88a24afeb8b093f8ce26b7af Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 21:03:28 -0400 Subject: [PATCH 07/24] =?UTF-8?q?fix:=20correct=20agent+=20email=20documen?= =?UTF-8?q?tation=20=E2=80=94=20they=20create=20separate=20accounts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit agent+ emails are NOT linked to the base email address. agent+sidney@recoupable.com creates a completely separate account from sidney@recoupable.com. Email lookup uses exact match with no plus-address normalization (verified from selectAccountByEmail code). Made-with: Cursor --- agents.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/agents.mdx b/agents.mdx index d34ee1e..11f715f 100644 --- a/agents.mdx +++ b/agents.mdx @@ -32,9 +32,9 @@ curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ The verify response includes `api_key`. Store it and pass it as `x-api-key` on every subsequent request. - -`agent+` emails (e.g. `agent+test@recoupable.com`) skip verification and return a key instantly — but create a blank account with no roster or catalog. Use this for testing, not for working on behalf of an existing user. - + +`agent+` emails create a **separate account** — `agent+sidney@recoupable.com` is NOT linked to `sidney@recoupable.com`. To get a key for an existing user, use their actual email and go through the verification flow above. + --- From 691e3a3371e5817f741c224e4d60604854000f94 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 21:38:46 -0400 Subject: [PATCH 08/24] fix: deprecate content pipeline, promote individual endpoints - POST /api/content/create marked as legacy with Warning callout - Individual content endpoints (generate-image, generate-video, etc.) moved to top of Content tab - Templates split into own group - Pipeline moved to "Pipeline (Legacy)" group at bottom - Removed content readiness section from Agent Onboarding (face guide not universally required) - Added proactive roster check instruction after auth in Agent Onboarding Made-with: Cursor --- agents.mdx | 19 +++---------------- api-reference/content/create.mdx | 4 ++++ docs.json | 25 +++++++++++++++---------- 3 files changed, 22 insertions(+), 26 deletions(-) diff --git a/agents.mdx b/agents.mdx index 11f715f..461f415 100644 --- a/agents.mdx +++ b/agents.mdx @@ -30,17 +30,17 @@ curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ -d '{"email": "user@example.com", "code": "123456"}' ``` -The verify response includes `api_key`. Store it and pass it as `x-api-key` on every subsequent request. +The verify response includes `api_key`. Store it and pass it as `x-api-key` on every subsequent request. **Then immediately check the roster** — don't wait for the user to tell you what to do. -`agent+` emails create a **separate account** — `agent+sidney@recoupable.com` is NOT linked to `sidney@recoupable.com`. To get a key for an existing user, use their actual email and go through the verification flow above. +`agent+` emails create a **separate account** — `agent+sidney@recoupable.com` is NOT linked to `sidney@recoupable.com`. To get a key for an existing user, call signup with their real email, ask them to check their inbox for the 6-digit code, then call verify with that code. --- ## 2. Understand the roster -After authenticating, check what the user has: +After getting a key, your next call should always be to check what the user has: ```bash # List all artists available to this account @@ -85,19 +85,6 @@ orgs/{org-name}/artists/{artist-slug}/ The `RECOUP.md` file ties the folder to the platform — it contains YAML frontmatter with `artistName`, `artistSlug`, and `artistId`. -### Content readiness - -Before generating content for an artist, the minimum required files are: -- `context/images/face-guide.png` (face reference) -- At least one `.mp3` file under the artist tree - -Recommended for better output: -- `context/artist.md` (brand/voice) -- `context/audience.md` (audience insights) -- `context/era.json` (current era metadata) - -Use `POST /api/content/validate` with `artist_account_id` to check readiness programmatically. - ### Accessing sandbox files ```bash diff --git a/api-reference/content/create.mdx b/api-reference/content/create.mdx index b3bf5d7..23fa770 100644 --- a/api-reference/content/create.mdx +++ b/api-reference/content/create.mdx @@ -2,3 +2,7 @@ title: 'Create Content' openapi: "/api-reference/openapi/content.json POST /api/content/create" --- + + +This pipeline endpoint is being phased out. Use the individual content endpoints (`generate-image`, `generate-video`, `generate-caption`, etc.) directly — they accept template parameters and don't require pre-configured artist files. + diff --git a/docs.json b/docs.json index 2ee38c9..82c9bfc 100644 --- a/docs.json +++ b/docs.json @@ -207,16 +207,6 @@ { "tab": "Content", "groups": [ - { - "group": "Content Pipeline", - "pages": [ - "api-reference/content/create", - "api-reference/content/templates", - "api-reference/content/template-detail", - "api-reference/content/validate", - "api-reference/content/estimate" - ] - }, { "group": "Content Endpoints", "pages": [ @@ -231,6 +221,21 @@ "api-reference/transcribe/audio" ] }, + { + "group": "Templates", + "pages": [ + "api-reference/content/templates", + "api-reference/content/template-detail", + "api-reference/content/validate", + "api-reference/content/estimate" + ] + }, + { + "group": "Pipeline (Legacy)", + "pages": [ + "api-reference/content/create" + ] + }, { "group": "Content Agent", "pages": [ From 0c4fd2596480a6d77e78bb4a4d833e85f3850a45 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 22:19:16 -0400 Subject: [PATCH 09/24] =?UTF-8?q?polish:=20tighten=20copy,=20rename=20Auto?= =?UTF-8?q?mation=E2=86=92Tasks,=20move=20Sandboxes=E2=86=92Accounts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Homepage: refined problem statement, dropped "the", removed condescending copy - Agent Onboarding: "user"→"human", Steps for auth flow, manage as work type, smarter task guidelines, filesystem not "sandbox filesystem", fixed content readiness reference, agent+ email warning with generic email - Navigation: Automation→Tasks (time-based only), Sandboxes→Accounts (infrastructure) - Content: pipeline endpoint marked legacy, individual endpoints promoted - OpenAPI create.mdx: deprecation warning added Made-with: Cursor --- agents.mdx | 82 ++++++++++++++++++-------------- api-reference/content/create.mdx | 2 +- docs.json | 26 +++++----- index.mdx | 10 ++-- 4 files changed, 65 insertions(+), 55 deletions(-) diff --git a/agents.mdx b/agents.mdx index 461f415..f279e0d 100644 --- a/agents.mdx +++ b/agents.mdx @@ -1,46 +1,46 @@ --- title: "Agent Onboarding" -description: "The operating manual for AI agents using the Recoupable API. Authentication, roster awareness, sandbox filesystem, and decision-making." +description: "The operating manual for AI agents using the Recoupable API." --- -This page is for AI agents. It tells you how to authenticate, understand your user's roster, navigate the sandbox filesystem, and decide what to do. +This page is for AI agents. Follow these steps in order. ## 1. Authenticate -If your user already has an API key, use it: +If your human has an API key, pass it via `x-api-key`. If not, generate one: -```bash -curl "https://recoup-api.vercel.app/api/accounts/id" \ - -H "x-api-key: USER_API_KEY" -``` - -If they don't have a key, generate one from their email. This sends a 6-digit verification code to their inbox — ask the user for the code. - -```bash -# Step 1 — request verification code -curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ - -H "Content-Type: application/json" \ - -d '{"email": "user@example.com"}' - -# Step 2 — ask the user: "Check your email for a verification code and share it with me." - -# Step 3 — submit the code -curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ - -H "Content-Type: application/json" \ - -d '{"email": "user@example.com", "code": "123456"}' -``` + + + ```bash + curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ + -H "Content-Type: application/json" \ + -d '{"email": "user@example.com"}' + ``` + + + A 6-digit code was sent to their inbox. Ask them: *"Check your email for a verification code and share it with me."* + + + ```bash + curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ + -H "Content-Type: application/json" \ + -d '{"email": "user@example.com", "code": "123456"}' + ``` + Store the returned `api_key`. Pass it as `x-api-key` on every request. + + -The verify response includes `api_key`. Store it and pass it as `x-api-key` on every subsequent request. **Then immediately check the roster** — don't wait for the user to tell you what to do. +**After authenticating, immediately check the roster.** Don't wait for the human to tell you what to do. -`agent+` emails create a **separate account** — `agent+sidney@recoupable.com` is NOT linked to `sidney@recoupable.com`. To get a key for an existing user, call signup with their real email, ask them to check their inbox for the 6-digit code, then call verify with that code. +`agent+` emails create a **separate account** — `agent+user@example.com` is NOT linked to `user@example.com`. To work on behalf of an existing human, use their real email. --- ## 2. Understand the roster -After getting a key, your next call should always be to check what the user has: +After getting a key, your next call should always be to check what the human has: ```bash # List all artists available to this account @@ -52,17 +52,17 @@ curl "https://recoup-api.vercel.app/api/organizations" \ -H "x-api-key: $API_KEY" ``` -**If the user has artists**, you can scope work to a specific artist by passing `artist_account_id` on supported endpoints. Research, content, tasks, and fan segments all become artist-specific. +**If the human has artists**, you can scope work to a specific artist by passing `artist_account_id` on supported endpoints. Research, content, tasks, and fan segments all become artist-specific. -**If the user has organizations**, pass `organization_id` to scope to a specific label's roster. +**If the human has organizations**, pass `organization_id` to scope to a specific label's roster. -**If neither is specified**, you operate at the account level and can see everything available to the user. +**If neither is specified**, you operate at the account level and can see everything available to the human. --- -## 3. Know the sandbox filesystem +## 3. Know the filesystem -Each account has a persistent sandbox backed by a GitHub repo. This is where artist context lives — the files agents use to do informed work. +Each account has a persistent filesystem backed by a GitHub repo. This is where artist context lives — the files agents use to do informed work. ### Artist directory structure @@ -108,19 +108,29 @@ curl -X POST "https://recoup-api.vercel.app/api/sandboxes/files" \ ## 4. Decide what to do - + Call `GET /api/artists`. If they have artists, list them and ask which one to work with. If not, you can research any artist with `GET /api/research?q=...` or create one with `POST /api/artists`. - + **Research** — use the 30+ research endpoints. Pass `artist_account_id` to scope to a rostered artist, or search by name for any artist globally. - **Content** — check readiness with `POST /api/content/validate`, then generate with the content endpoints. Artist context from the sandbox filesystem makes output more on-brand. + **Content** — generate images, videos, and captions with the content endpoints. Artist context from the filesystem makes output more on-brand. + + **Manage** — plan and track releases by creating and updating `RELEASE.md` files in the artist's `releases/` directory. Add songs to catalogs, update artist context, and organize the roster. - Research and generated content can be saved to the artist's sandbox directory for future context. Use `POST /api/sandboxes/files` to upload files, or use `POST /api/sandboxes` with a prompt to run complex file operations in the sandbox directly. + Save research, generated content, or notes to the artist's directory in the filesystem so future calls have more context. Use `POST /api/sandboxes/files` to upload files to the repo. - If the work should happen automatically, create a task with `POST /api/tasks` — set a cron schedule and a prompt. The task runs on schedule against the specified artist. + If the human asks for something more than once, or if the work is time-sensitive and repeating, turn it into a task with `POST /api/tasks`. + + Good candidates for tasks: + - Daily or weekly reports (streaming stats, fan growth, playlist adds) + - Monitoring competitors or trending artists + - Generating recurring content (weekly social posts, monthly recaps) + - Checking release milestones as a date approaches + + If the human only needs it once, just do it. Don't create a task for everything. diff --git a/api-reference/content/create.mdx b/api-reference/content/create.mdx index 23fa770..e210217 100644 --- a/api-reference/content/create.mdx +++ b/api-reference/content/create.mdx @@ -4,5 +4,5 @@ openapi: "/api-reference/openapi/content.json POST /api/content/create" --- -This pipeline endpoint is being phased out. Use the individual content endpoints (`generate-image`, `generate-video`, `generate-caption`, etc.) directly — they accept template parameters and don't require pre-configured artist files. +This endpoint is being phased out. Use the individual content endpoints directly. diff --git a/docs.json b/docs.json index 82c9bfc..88d5855 100644 --- a/docs.json +++ b/docs.json @@ -246,7 +246,7 @@ ] }, { - "tab": "Automation", + "tab": "Tasks", "groups": [ { "group": "Scheduled Tasks", @@ -258,18 +258,6 @@ "api-reference/tasks/runs" ] }, - { - "group": "Sandboxes", - "pages": [ - "api-reference/sandboxes/list", - "api-reference/sandboxes/create", - "api-reference/sandboxes/snapshot", - "api-reference/sandboxes/delete", - "api-reference/sandboxes/setup", - "api-reference/sandboxes/file", - "api-reference/sandboxes/upload" - ] - }, { "group": "Pulses", "pages": [ @@ -313,6 +301,18 @@ "api-reference/organizations/add-artist" ] }, + { + "group": "Sandboxes", + "pages": [ + "api-reference/sandboxes/list", + "api-reference/sandboxes/create", + "api-reference/sandboxes/snapshot", + "api-reference/sandboxes/delete", + "api-reference/sandboxes/setup", + "api-reference/sandboxes/file", + "api-reference/sandboxes/upload" + ] + }, { "group": "Connectors", "pages": [ diff --git a/index.mdx b/index.mdx index ed64e72..acd24d0 100644 --- a/index.mdx +++ b/index.mdx @@ -1,13 +1,13 @@ --- title: "What is Recoupable?" -description: "The infrastructure for agents to run record labels." +description: "Infrastructure for agents to run record labels." --- **AI agent?** Base URL: `https://recoup-api.vercel.app/api`. Use `x-api-key` if your user has a key. Otherwise, `POST /api/agents/signup` with their email — ask them for the verification code from their inbox, then `POST /api/agents/verify` to get a key. [Agent guide →](/agents) | [Endpoint map ↓](#for-ai-agents) -Running a record label takes a full team. Most artists can't afford it. Most executives can't scale it. Recoupable captures context around your catalog, artists, releases, and fans, then context-engineers it so agents get exactly what they need to perform the work of a major label. Programmatically. +Running a record label takes a full team. Research, content, marketing, distribution, fan engagement. Whether you're an artist doing it all yourself or a label team managing a roster, that's a lot of work. That's what agents are for. Recoupable captures context around your catalog, artists, releases, and fans, and structures it so agents can perform the work of a major label — programmatically. --- @@ -139,18 +139,18 @@ Organized by what agents actually do when running a label. 7 content endpoints for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each one directly. - Scheduled tasks, sandboxed code execution, automated pulses, and notifications. The engine that lets agents work while you sleep. + Scheduled tasks, automated pulses, and notifications. The engine that lets agents work while you sleep. - Accounts, organizations, connectors, workspaces, and subscriptions. The business infrastructure. + Accounts, organizations, sandboxes, connectors, workspaces, and subscriptions. The business infrastructure. From 87adf0065110683fb40280e3ab9bc1ce91cb4b63 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 22:38:17 -0400 Subject: [PATCH 10/24] polish: simplify core concepts, refine copy throughout - Core concepts: reduced to 4 essentials (Account, Organization, Artist, Filesystem) - Dropped Catalog, Task, Chat, Connector, Pulse, Sandbox from core concepts - Back to clean table format (cards were too cramped) - Intro copy: "That's what agents are for." bridge, no jargon - Agent onboarding: "human" not "user", manage as work type, task guidelines - Tasks tab renamed from Automation, Sandboxes moved to Accounts - Content pipeline marked legacy Made-with: Cursor --- index.mdx | 31 ++++++------------------------- 1 file changed, 6 insertions(+), 25 deletions(-) diff --git a/index.mdx b/index.mdx index acd24d0..1e09fb3 100644 --- a/index.mdx +++ b/index.mdx @@ -13,31 +13,12 @@ Running a record label takes a full team. Research, content, marketing, distribu ## Core concepts - - - Recoupable has three levels of identity. You can scope agent work at any level. - - | Concept | What it is | - |---------|------------| - | **Account** | A user or agent that authenticates with an API key. Your account owns artists, chats, tasks, and connectors. When no artist is specified, you see everything available to you. | - | **Organization** | A label or team that groups multiple accounts. Pass `organization_id` to scope to a specific roster. Accounts can belong to multiple organizations, each with different artists. | - | **Artist** | A managed artist with profile, social handles, and linked catalog. Pass `artist_account_id` to scope to a specific artist. When omitted, agents see all artists available to the account. | - - - | Concept | What it is | - |---------|------------| - | **Catalog** | A collection of songs belonging to a label or artist. Catalogs can be analyzed, organized, and used as context for content creation. | - | **Chat** | An AI conversation with artist context. Agents use chats to research, plan, and execute — with full memory of prior work. | - | **Connector** | An OAuth connection to an external platform (Spotify, Google Sheets, TikTok, etc.) linked to an account. | - - - | Concept | What it is | - |---------|------------| - | **Task** | A scheduled prompt that runs on a cron. Automates recurring agent work — daily reports, weekly content, monthly analysis. Scope to a specific artist or run across the whole roster. | - | **Sandbox** | An isolated Linux environment where agents can run code, manage files, and execute complex workflows. Persistent across calls. | - | **Pulse** | An automated digest channel. When enabled, Recoupable sends periodic intelligence updates about an artist to the account owner. | - - +| Concept | What it is | +|---------|------------| +| **Account** | A user or agent that authenticates with an API key. When no artist is specified, you see everything available to the account. | +| **Organization** | A label or team that groups multiple accounts. Pass `organization_id` to scope to a specific roster. | +| **Artist** | A managed artist with profile, social handles, and linked catalog. Pass `artist_account_id` to scope to a specific artist. | +| **Filesystem** | A persistent Git repo where artist context lives — brand voice, audience insights, songs, release plans, and generated content. | ## How it works From f5d587b334c429d13e3bd310175bba87005dc93b Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 22:49:42 -0400 Subject: [PATCH 11/24] =?UTF-8?q?feat:=20give=20Chat=20its=20own=20tab=20?= =?UTF-8?q?=E2=80=94=20it's=20the=20conversational=20AI=20layer,=20not=20r?= =?UTF-8?q?esearch?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Made-with: Cursor --- docs.json | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 88d5855..c07d2b1 100644 --- a/docs.json +++ b/docs.json @@ -59,7 +59,7 @@ ] }, { - "tab": "Research", + "tab": "Chat", "groups": [ { "group": "AI Chat", @@ -77,7 +77,12 @@ "api-reference/chat/generate", "api-reference/chat/compact" ] - }, + } + ] + }, + { + "tab": "Research", + "groups": [ { "group": "Artist Research", "pages": [ From e167c4fe2d6748227c40d664a32a8845c1916d55 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:42:44 -0400 Subject: [PATCH 12/24] =?UTF-8?q?rename:=20Tasks=20=E2=86=92=20Automation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Made-with: Cursor --- docs.json | 2 +- index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index c07d2b1..1e7f6bb 100644 --- a/docs.json +++ b/docs.json @@ -251,7 +251,7 @@ ] }, { - "tab": "Tasks", + "tab": "Automation", "groups": [ { "group": "Scheduled Tasks", diff --git a/index.mdx b/index.mdx index 1e09fb3..7802a32 100644 --- a/index.mdx +++ b/index.mdx @@ -120,7 +120,7 @@ Organized by what agents actually do when running a label. 7 content endpoints for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each one directly. From 02d48d25a60f7d58ffe46949eb56344a5a557975 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:46:42 -0400 Subject: [PATCH 13/24] polish: bigger logo, human not user, Automation tab name Made-with: Cursor --- index.mdx | 2 +- logo/dark.svg | 2 +- logo/light.svg | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/index.mdx b/index.mdx index 7802a32..04dc32c 100644 --- a/index.mdx +++ b/index.mdx @@ -4,7 +4,7 @@ description: "Infrastructure for agents to run record labels." --- -**AI agent?** Base URL: `https://recoup-api.vercel.app/api`. Use `x-api-key` if your user has a key. Otherwise, `POST /api/agents/signup` with their email — ask them for the verification code from their inbox, then `POST /api/agents/verify` to get a key. [Agent guide →](/agents) | [Endpoint map ↓](#for-ai-agents) +**AI agent?** Base URL: `https://recoup-api.vercel.app/api`. Use `x-api-key` if your human has a key. Otherwise, `POST /api/agents/signup` with their email — ask them for the verification code from their inbox, then `POST /api/agents/verify` to get a key. [Agent guide →](/agents) | [Endpoint map ↓](#for-ai-agents) Running a record label takes a full team. Research, content, marketing, distribution, fan engagement. Whether you're an artist doing it all yourself or a label team managing a roster, that's a lot of work. That's what agents are for. Recoupable captures context around your catalog, artists, releases, and fans, and structures it so agents can perform the work of a major label — programmatically. diff --git a/logo/dark.svg b/logo/dark.svg index eb8f7f3..98b9be5 100644 --- a/logo/dark.svg +++ b/logo/dark.svg @@ -1,4 +1,4 @@ - + diff --git a/logo/light.svg b/logo/light.svg index d86546a..915c488 100644 --- a/logo/light.svg +++ b/logo/light.svg @@ -1,4 +1,4 @@ - + From 1a24534d9eb8bee82a0325ca7b911f9891921dad Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:51:53 -0400 Subject: [PATCH 14/24] fix: use ?artist= not ?q= for research/metrics, audience, playlists endpoints Made-with: Cursor --- quickstart.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 8d4829b..51d3d4c 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -66,15 +66,15 @@ Once you have an artist, pull data across 14 platforms: ```bash # Streaming metrics (Spotify, Instagram, TikTok, YouTube, and 10 more) -curl "https://recoup-api.vercel.app/api/research/metrics?q=Drake&source=spotify" \ +curl "https://recoup-api.vercel.app/api/research/metrics?artist=Drake&source=spotify" \ -H "x-api-key: $RECOUP_API_KEY" # Audience demographics (age, gender, geography) -curl "https://recoup-api.vercel.app/api/research/audience?q=Drake" \ +curl "https://recoup-api.vercel.app/api/research/audience?artist=Drake" \ -H "x-api-key: $RECOUP_API_KEY" # Editorial playlist placements -curl "https://recoup-api.vercel.app/api/research/playlists?q=Drake&editorial=true" \ +curl "https://recoup-api.vercel.app/api/research/playlists?artist=Drake&editorial=true" \ -H "x-api-key: $RECOUP_API_KEY" ``` From d40b6d43d8feea2f7cd6d077498369f249466cd6 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:52:48 -0400 Subject: [PATCH 15/24] fix: add 10 missing endpoint groups to LLM endpoint map Made-with: Cursor --- index.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/index.mdx b/index.mdx index 04dc32c..f7ddca1 100644 --- a/index.mdx +++ b/index.mdx @@ -199,6 +199,15 @@ If you are an LLM or AI agent, here is the complete endpoint map. All paths are | `/spotify/*` | search, artist, artist-albums, artist-top-tracks, album | | `/instagram/*` | comments, profiles | | `/x/*` | search, trends | +| `/segment/*` | fans | +| `/fans/*` | get | +| `/posts/*` | get | +| `/post/*` | comments | +| `/comments/*` | get | +| `/image/*` | generation | +| `/transcribe/*` | audio | +| `/social/*` | scrape, posts | +| `/apify/*` | scraper | | `/connectors/*` | list, authorize, disconnect | | `/accounts/*` | get, id, create, update, add-artist | | `/organizations/*` | list, create, add-artist | @@ -208,6 +217,7 @@ If you are an LLM or AI agent, here is the complete endpoint map. All paths are | `/notifications/*` | create | | `/workspaces/*` | create | | `/subscriptions/*` | get | +| `/admins/*` | check, sandboxes, sandboxes-orgs, emails, privy, coding-agent-slack-tags, coding-pr, content-slack-tags | Authentication: `x-api-key` header (or `Authorization: Bearer ` for Privy). Get a key instantly via `POST /api/agents/signup` with an `agent+` email. From 65defe55abb081519c39c9a673d5e0c0fb89f474 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:53:51 -0400 Subject: [PATCH 16/24] fix: adjust dark accent color for better button contrast in dark mode Made-with: Cursor --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 1e7f6bb..a8638d8 100644 --- a/docs.json +++ b/docs.json @@ -5,7 +5,7 @@ "colors": { "primary": "#0a0a0a", "light": "#ededed", - "dark": "#0a0a0a" + "dark": "#171717" }, "favicon": "/favicon.ico", "appearance": { From 04966301728ec003da48913b80518e838d5b404a Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:54:39 -0400 Subject: [PATCH 17/24] fix: restore POST /api/sandboxes link in CLI docs Made-with: Cursor --- cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli.mdx b/cli.mdx index 2f86060..fc2d32f 100644 --- a/cli.mdx +++ b/cli.mdx @@ -100,7 +100,7 @@ recoup chats create --name "My Topic" --artist ### sandboxes -Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list). +Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create). ```bash recoup sandboxes list From c978054882beade81b413d1de8ebfb530a6ea6f9 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:55:42 -0400 Subject: [PATCH 18/24] fix: restore POST /api/chats link in CLI docs Made-with: Cursor --- cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli.mdx b/cli.mdx index fc2d32f..31504e2 100644 --- a/cli.mdx +++ b/cli.mdx @@ -90,7 +90,7 @@ recoup notifications --subject "Update" --html "

Report

Details here.< ### chats -Manage chats. See [`GET /api/chats`](/api-reference/chat/chats). +Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create). ```bash recoup chats list From d68be440d0eff635819b8f3ca9b8de02abf98663 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:56:45 -0400 Subject: [PATCH 19/24] fix: clarify that instant key issuance is specific to agent+ email pattern Made-with: Cursor --- quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quickstart.mdx b/quickstart.mdx index 51d3d4c..0eaa719 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -11,7 +11,7 @@ export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agent -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) ``` -That's it. `$RECOUP_API_KEY` is now ready. No email verification, no waiting. +That's it. The `agent+...@recoupable.com` pattern returns a key instantly — no email verification, no waiting. Prefer the dashboard? Create keys at [chat.recoupable.com/keys](https://chat.recoupable.com/keys). See the [Agents guide](/agents) for the full signup flow with email verification. From b5b17cdf57161ae4c2141bf67bf6cbc6a1c69568 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:57:31 -0400 Subject: [PATCH 20/24] fix: content endpoints card links to generate-image, not legacy pipeline Made-with: Cursor --- quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quickstart.mdx b/quickstart.mdx index 0eaa719..cfabb00 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -107,7 +107,7 @@ Pass your API key as a Bearer token. Your agent gets access to all 40+ endpoints 7 endpoints for images, videos, captions, transcription, editing, upscaling, and analysis. From 3f70b3420f54e62fd5690fe46f5165796a6210aa Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:58:05 -0400 Subject: [PATCH 21/24] fix: rename Primitive column header to Endpoint in content-agent Made-with: Cursor --- content-agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content-agent.mdx b/content-agent.mdx index a2946da..72b5313 100644 --- a/content-agent.mdx +++ b/content-agent.mdx @@ -41,7 +41,7 @@ The Recoup Content Agent is a Slack bot that generates social-ready artist video The content API provides seven independent endpoints. Each does one thing well. You orchestrate them. -| Primitive | Endpoint | What it does | +| Endpoint | Path | What it does | |-----------|----------|-------------| | Generate Image | [POST /api/content/image](/api-reference/content/generate-image) | Create an image from a text prompt with optional reference image | | Generate Video | [POST /api/content/video](/api-reference/content/generate-video) | Create a video — 6 modes: prompt, animate, reference, extend, first-last, lipsync | From 16b7bbc78d23f87c9aee846d6f5b000382dec894 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 14 Apr 2026 00:03:01 -0400 Subject: [PATCH 22/24] fix: add era.json to filesystem directory tree Made-with: Cursor --- agents.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/agents.mdx b/agents.mdx index f279e0d..47b3c9d 100644 --- a/agents.mdx +++ b/agents.mdx @@ -72,6 +72,7 @@ orgs/{org-name}/artists/{artist-slug}/ ├── context/ │ ├── artist.md # Brand voice, bio, constraints │ ├── audience.md # Audience insights, resonance +│ ├── era.json # Current era metadata │ └── images/ │ └── face-guide.png # Face reference for visual content ├── songs/{song-slug}/ From 02d761c8283143c13a0c9e398f38410fe94caaa2 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 14 Apr 2026 00:04:01 -0400 Subject: [PATCH 23/24] fix: move deprecation from MDX warning to OpenAPI deprecated field Made-with: Cursor --- api-reference/content/create.mdx | 4 ---- api-reference/openapi/content.json | 3 ++- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/api-reference/content/create.mdx b/api-reference/content/create.mdx index e210217..b3bf5d7 100644 --- a/api-reference/content/create.mdx +++ b/api-reference/content/create.mdx @@ -2,7 +2,3 @@ title: 'Create Content' openapi: "/api-reference/openapi/content.json POST /api/content/create" --- - - -This endpoint is being phased out. Use the individual content endpoints directly. - diff --git a/api-reference/openapi/content.json b/api-reference/openapi/content.json index 6979004..f20d5c7 100644 --- a/api-reference/openapi/content.json +++ b/api-reference/openapi/content.json @@ -615,7 +615,8 @@ }, "/api/content/create": { "post": { - "description": "Trigger the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).", + "deprecated": true, + "description": "This pipeline endpoint is being phased out. Use the individual content endpoints directly. Triggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).", "security": [ { "apiKeyAuth": [] From f0abb3730d3de6a84228c795e15383aeef23f29d Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 14 Apr 2026 00:04:39 -0400 Subject: [PATCH 24/24] fix: add specific endpoint names to deprecation notice in OpenAPI spec Made-with: Cursor --- api-reference/openapi/content.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi/content.json b/api-reference/openapi/content.json index f20d5c7..9a83001 100644 --- a/api-reference/openapi/content.json +++ b/api-reference/openapi/content.json @@ -616,7 +616,7 @@ "/api/content/create": { "post": { "deprecated": true, - "description": "This pipeline endpoint is being phased out. Use the individual content endpoints directly. Triggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).", + "description": "This pipeline endpoint is being phased out. Use the individual content endpoints (`generate-image`, `generate-video`, `generate-caption`, etc.) directly. Triggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).", "security": [ { "apiKeyAuth": []