diff --git a/agents.mdx b/agents.mdx
index 8bbf1f0..47b3c9d 100644
--- a/agents.mdx
+++ b/agents.mdx
@@ -1,96 +1,146 @@
---
-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: "The operating manual for AI agents using the Recoupable API."
---
-## Quickest start
+This page is for AI agents. Follow these steps in order.
+
+## 1. Authenticate
+
+If your human has an API key, pass it via `x-api-key`. If not, generate one:
+
+
+
+ ```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.
+
+
+
+**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+user@example.com` is NOT linked to `user@example.com`. To work on behalf of an existing human, use their real email.
+
-Get a working API key in a single unauthenticated request:
-
-```bash
-curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
- -H "Content-Type: application/json" \
- -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."
-}
-```
+---
-That's it. Store `api_key`, pass it in the `x-api-key` header on every subsequent request, and you're done.
+## 2. Understand the roster
-
-**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:
+After getting a key, your next call should always be to check what the human 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"
```
-Verify it worked:
+**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.
-```bash
-curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id
-```
-
+**If the human has organizations**, pass `organization_id` to scope to a specific label's roster.
-
-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.
-
+**If neither is specified**, you operate at the account level and can see everything available to the human.
-## How it works
+---
-Two unauthenticated endpoints power agent onboarding:
+## 3. Know the filesystem
-- **[`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.
+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.
-Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones.
+### Artist directory structure
-## Standard signup (email verification)
+```
+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
+│ ├── era.json # Current era metadata
+│ └── 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
+```
-If you're building a human-facing integration and want the user to verify their real email, use any non-`agent+` address:
+The `RECOUP.md` file ties the folder to the platform — it contains YAML frontmatter with `artistName`, `artistSlug`, and `artistId`.
-Step 1 — request a verification code:
+### Accessing sandbox files
```bash
-curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
- -H "Content-Type: application/json" \
- -d '{"email": "you@example.com"}'
-```
+# List the full file tree
+curl "https://recoup-api.vercel.app/api/sandboxes" \
+ -H "x-api-key: $API_KEY"
-Step 2 — submit the 6-digit code from the verification email:
+# 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"
-```bash
-curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \
+# 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 '{"email": "you@example.com", "code": "123456"}'
+ -d '{"files": [{"url": "https://...", "path": "orgs/my-label/artists/drake/context/audience.md"}]}'
```
-Response:
+---
-```json
-{
- "account_id": "123e4567-e89b-12d3-a456-426614174000",
- "api_key": "recoup_sk_abc123...",
- "message": "Verified"
-}
-```
+## 4. Decide what to do
-## Using your API key
+
+
+ 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.
-Pass the returned `api_key` in the `x-api-key` header on every authenticated request:
+ **Content** — generate images, videos, and captions with the content endpoints. Artist context from the filesystem makes output more on-brand.
-```bash
-curl -X GET "https://recoup-api.vercel.app/api/tasks" \
- -H "x-api-key: YOUR_API_KEY"
+ **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.
+
+
+ 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 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.
+
+
+
+---
+
+## Base URL
+
+```
+https://recoup-api.vercel.app/api
```
-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.
+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/api-reference/openapi/content.json b/api-reference/openapi/content.json
index 6979004..9a83001 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 (`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": []
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..31504e2 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,50 +51,44 @@ 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 "
"
```
| 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).
@@ -94,10 +96,9 @@ Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/
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).
@@ -105,49 +106,38 @@ Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and
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..72b5313 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 endpoints
+
+The content API provides seven independent endpoints. Each does one thing well. You orchestrate them.
+
+| 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 |
+| 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.
-| 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 |
+## Video modes
-### Data Flow
+| 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..a8638d8 100644
--- a/docs.json
+++ b/docs.json
@@ -1,69 +1,68 @@
{
"$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Recoup",
+ "theme": "sequoia",
+ "name": "Recoupable",
"colors": {
- "primary": "#345A5D",
- "light": "#4A7A7D",
- "dark": "#1E3A3D"
+ "primary": "#0a0a0a",
+ "light": "#ededed",
+ "dark": "#171717"
},
"favicon": "/favicon.ico",
+ "appearance": {
+ "default": "system"
+ },
+ "fonts": {
+ "heading": {
+ "family": "Plus Jakarta Sans",
+ "weight": 700
+ },
+ "body": {
+ "family": "Inter",
+ "weight": 400
+ }
+ },
+ "background": {
+ "color": {
+ "light": "#f7f7f7",
+ "dark": "#0a0a0a"
+ }
+ },
+ "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",
+ "tab": "Chat",
"groups": [
{
- "group": "Chat",
+ "group": "AI Chat",
"pages": [
"api-reference/chat/stream",
"api-reference/chat/create",
@@ -78,9 +77,14 @@
"api-reference/chat/generate",
"api-reference/chat/compact"
]
- },
+ }
+ ]
+ },
+ {
+ "tab": "Research",
+ "groups": [
{
- "group": "Research",
+ "group": "Artist Research",
"pages": [
"api-reference/research/search",
"api-reference/research/lookup",
@@ -102,30 +106,99 @@
"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": "Artist Management",
+ "pages": [
+ "api-reference/artists/list",
+ "api-reference/artists/create",
+ "api-reference/artists/delete",
+ "api-reference/artist/profile",
+ "api-reference/artist/socials",
+ "api-reference/artist/socials-scrape"
+ ]
+ },
+ {
+ "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 & Catalogs",
+ "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",
@@ -133,13 +206,6 @@
"api-reference/songs/catalog-songs-add",
"api-reference/songs/catalog-songs-delete"
]
- },
- {
- "group": "Fans & Segments",
- "pages": [
- "api-reference/segment/fans",
- "api-reference/fans/get"
- ]
}
]
},
@@ -147,9 +213,8 @@
"tab": "Content",
"groups": [
{
- "group": "Content Creation",
+ "group": "Content Endpoints",
"pages": [
- "api-reference/content/create",
"api-reference/content/generate-image",
"api-reference/content/generate-video",
"api-reference/content/generate-caption",
@@ -157,6 +222,13 @@
"api-reference/content/edit",
"api-reference/content/upscale",
"api-reference/content/analyze-video",
+ "api-reference/image/generation",
+ "api-reference/transcribe/audio"
+ ]
+ },
+ {
+ "group": "Templates",
+ "pages": [
"api-reference/content/templates",
"api-reference/content/template-detail",
"api-reference/content/validate",
@@ -164,11 +236,9 @@
]
},
{
- "group": "Posts & Comments",
+ "group": "Pipeline (Legacy)",
"pages": [
- "api-reference/posts/get",
- "api-reference/post/comments",
- "api-reference/comments/get"
+ "api-reference/content/create"
]
},
{
@@ -177,71 +247,33 @@
"api-reference/content-agent/webhook",
"api-reference/content-agent/callback"
]
- },
- {
- "group": "Image",
- "pages": [
- "api-reference/image/generation"
- ]
- },
- {
- "group": "Transcribe",
- "pages": [
- "api-reference/transcribe/audio"
- ]
- },
- {
- "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"
- ]
}
]
},
{
- "tab": "Social Media",
+ "tab": "Automation",
"groups": [
{
- "group": "Social",
- "pages": [
- "api-reference/social/posts",
- "api-reference/social/scrape"
- ]
- },
- {
- "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",
+ "group": "Scheduled Tasks",
"pages": [
- "api-reference/instagram/comments",
- "api-reference/instagram/profiles"
+ "api-reference/tasks/get",
+ "api-reference/tasks/create",
+ "api-reference/tasks/update",
+ "api-reference/tasks/delete",
+ "api-reference/tasks/runs"
]
},
{
- "group": "X (Twitter)",
+ "group": "Pulses",
"pages": [
- "api-reference/x/search",
- "api-reference/x/trends"
+ "api-reference/pulses/update",
+ "api-reference/pulses/list"
]
},
{
- "group": "Apify",
+ "group": "Notifications",
"pages": [
- "api-reference/apify/scraper"
+ "api-reference/notifications/create"
]
}
]
@@ -256,21 +288,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 +306,26 @@
"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": [
+ "api-reference/connectors/list",
+ "api-reference/connectors/authorize",
+ "api-reference/connectors/disconnect"
+ ]
+ },
{
"group": "Workspaces",
"pages": [
@@ -313,12 +350,6 @@
"api-reference/admins/coding-pr",
"api-reference/admins/content-slack-tags"
]
- },
- {
- "group": "Notifications",
- "pages": [
- "api-reference/notifications/create"
- ]
}
]
}
@@ -326,29 +357,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.svg",
+ "href": "https://recoupable.com"
},
"navbar": {
"links": [
+ {
+ "label": "Blog",
+ "href": "https://research.recoupable.com/"
+ },
{
"label": "Support",
"href": "mailto:agent@recoupable.com"
@@ -356,8 +387,8 @@
],
"primary": {
"type": "button",
- "label": "Dashboard",
- "href": "https://chat.recoupable.com"
+ "label": "Get API Key",
+ "href": "https://chat.recoupable.com/keys"
}
},
"contextual": {
@@ -375,13 +406,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": "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 62bb714..f7ddca1 100644
--- a/index.mdx
+++ b/index.mdx
@@ -1,187 +1,224 @@
---
-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: "What is Recoupable?"
+description: "Infrastructure for agents to run record labels."
---
-# Welcome to the Recoup API
+
+**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)
+
-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.
+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.
-## Quickest start — one curl call
-
-Get a working API key in a single unauthenticated request. No dashboard, no browser, no human in the loop.
-
-```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)
-```
-
-`$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
-```
+## Core concepts
+
+| 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
+
+
+
+ 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.
+
+
-## 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.
+## Get an 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)
+One call. No signup form. No dashboard.
```bash
-curl -X GET "https://recoup-api.vercel.app/api/artists?accountId=YOUR_ACCOUNT_ID" \
+export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \
-H "Content-Type: application/json" \
- -H "x-api-key: YOUR_API_KEY"
+ -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key)
```
-
-Keep your API key secure. Do not share it publicly or commit it to version control.
-
+
+The `agent+` prefix bypasses email verification. Your API key comes back in the response — ready to use immediately.
+
-## Get Started
+---
-
+## Three interfaces
+
+
- 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+ endpoints.
- Get your API key and make your first request in minutes.
+ Connect Claude, ChatGPT, Cursor, or any MCP-compatible agent directly. 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
+---
+
+## What's in the API
-The API is organized into six main sections. Use these links to jump to the right area.
+Organized by what agents actually do when running a label.
- 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.
+ 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. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.
+ Manage the roster. Artist profiles, social accounts, fan segments, posts, and comments — the people side of your label.
- Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.
+ Songs, catalogs, and AI-powered audio analysis. Organize releases into collections. The music side of your label.
- Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.
+ 7 content endpoints for images, videos, captions, transcription, editing, upscaling, and analysis. Run the full pipeline or call each one directly.
- Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.
+ Scheduled tasks, automated pulses, and notifications. The engine that lets agents work while you sleep.
- Accounts, organizations, workspaces, subscriptions, pulses, notifications, sandboxes, and admin tools.
+ Accounts, organizations, sandboxes, connectors, workspaces, and subscriptions. The business infrastructure.
-## Agents
+---
+
+## 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: `https://recoup-api.vercel.app/api`
-
-[OpenAPI Specification](https://github.com/sweetmantech/docs/blob/main/api-reference/openapi.json)
-
-## Need Help?
-
-
- Reach out to our team at agent@recoupable.com for assistance with the Recoup API.
-
+---
+
+## Base URL
+
+```
+https://recoup-api.vercel.app/api
+```
+
+All endpoints require `x-api-key` header authentication unless noted.
+
+---
+
+## 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 |
+| `/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/*` | 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 |
+| `/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 |
+| `/content-agent/*` | webhook, callback |
+| `/agents/*` | signup, verify *(unauthenticated)* |
+| `/pulses/*` | update, list |
+| `/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.
+
+[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..98b9be5
--- /dev/null
+++ b/logo/dark.svg
@@ -0,0 +1,11 @@
+
diff --git a/logo/light.svg b/logo/light.svg
index fa35f85..915c488 100644
--- a/logo/light.svg
+++ b/logo/light.svg
@@ -1,9 +1,11 @@
-