diff --git a/agents.mdx b/agents.mdx
index 8bbf1f0..e94d749 100644
--- a/agents.mdx
+++ b/agents.mdx
@@ -1,96 +1,172 @@
---
-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 Recoup API."
---
-## Quickest start
+This page is for AI agents that act on a user's behalf. Follow the steps in order.
-Get a working API key in a single unauthenticated request:
+
+**Just trying the API yourself?** See [Quickstart](/quickstart) for a 5-minute hello-world. This page is the production operating manual — it covers the throwaway-vs-account decision, the roster, the filesystem, and the agent loop.
+
-```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"}'
-```
+## 0. Choose your path
-Response:
+**Ask the human which path they want before authenticating.** Guessing wrong creates records under a throwaway account that can't be recovered if the API key is lost — the user re-prompts later and their roster is gone.
-```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."
-}
-```
+Use this question — paraphrase if needed, but keep the trade-off explicit:
-That's it. Store `api_key`, pass it in the `x-api-key` header on every subsequent request, and you're done.
+> "Are you just exploring Recoup, or do you want me to set this up against your account so the work persists? If you have an account, what email should I use? Otherwise I'll create a temporary account — but you won't be able to save artists, releases, or scheduled tasks under it."
-
-**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:
+Once you have the answer, match the human's intent to the right path:
-```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)
-```
+| Human's answer | Auth path | Then |
+|----------------|-----------|------|
+| "Just exploring / quick demo / one-shot research" | Throwaway [`agent+...@recoupable.com`](#1-authenticate) signup | Use research and content endpoints. **Don't create artists** — they'll orphan when the API key is lost. |
+| "I have an account, here's my email" — they want to work on their existing roster | Sign in with their real email | List [`/api/artists`](/api-reference/artists/list); work with the roster they already have |
+| "I have an account, here's my email" — they want to add a new artist | Sign in with their real email | Run the [Create a New Artist](/workflows/create-artist) workflow |
+| "I don't have an account but I want to set one up" | Sign in with their real email | After auth, run [Create a New Artist](/workflows/create-artist) to start their roster |
-Verify it worked:
+**The key distinction:** `agent+` emails create isolated, unrecoverable accounts. Use them ONLY for one-shot work (research, content generation) where losing the API key has no cost. For anything that creates persistent records — artists, releases, scheduled tasks — use the user's real email.
-```bash
-curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id
-```
-
+**When you can skip the question:** If the human's instruction explicitly names the path (e.g., *"just try the demo"*, *"use my Recoup account, my email is x@y.com"*, or you were invoked autonomously by another agent with no human in the loop), you don't need to ask — proceed directly.
-
-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.
-
+## 1. Authenticate
-## How it works
+If your human has an API key, pass it via `x-api-key`. If not, generate one based on the path you chose above:
-Two unauthenticated endpoints power agent onboarding:
+
+
+ ```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` (e.g. `export RECOUP_API_KEY=your-api-key`) and pass it as `x-api-key` on every request.
+
+
-- **[`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.
+**After authenticating, immediately check the roster.** Don't wait for the human to tell you what to do.
-Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones.
+
+`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.
+
-## Standard signup (email verification)
+---
-If you're building a human-facing integration and want the user to verify their real email, use any non-`agent+` address:
+## 2. Understand the roster
-Step 1 — request a verification code:
+After getting a key, your next call should always be to check what the human has:
```bash
-curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
- -H "Content-Type: application/json" \
- -d '{"email": "you@example.com"}'
+# List all artists available to this account
+curl "https://recoup-api.vercel.app/api/artists" \
+ -H "x-api-key: $RECOUP_API_KEY"
+
+# List organizations (labels/teams) the account belongs to
+curl "https://recoup-api.vercel.app/api/organizations" \
+ -H "x-api-key: $RECOUP_API_KEY"
+```
+
+**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 data all become artist-specific.
+
+**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 human.
+
+---
+
+## 3. Know the filesystem
+
+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
+
```
+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
+```
+
+The `RECOUP.md` file ties the folder to the platform — it contains YAML frontmatter with `artistName`, `artistSlug`, and `artistId`.
-Step 2 — submit the 6-digit code from the verification email:
+### Accessing sandbox files
```bash
-curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \
+# List the full file tree
+curl "https://recoup-api.vercel.app/api/sandboxes" \
+ -H "x-api-key: $RECOUP_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: $RECOUP_API_KEY"
+
+# Upload files to the repo
+# path is top-level (target directory); each file needs url + name
+curl -X POST "https://recoup-api.vercel.app/api/sandboxes/files" \
+ -H "x-api-key: $RECOUP_API_KEY" \
-H "Content-Type: application/json" \
- -d '{"email": "you@example.com", "code": "123456"}'
+ -d '{"path": "orgs/my-label/artists/drake/context", "files": [{"url": "https://...", "name": "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/authentication.mdx b/authentication.mdx
index e7b7850..f856c36 100644
--- a/authentication.mdx
+++ b/authentication.mdx
@@ -1,115 +1,94 @@
---
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.
+The [agent signup and verify](/agents) endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are both unauthenticated — they let agents get their first key without any credentials.
---
-## API Keys
-
-API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are **personal keys** — they are always tied to the account that created them.
+## Create a key
-### Creating an API Key
+Two ways to get a key:
-1. Navigate to [chat.recoupable.com/keys](https://chat.recoupable.com/keys)
-2. Enter a descriptive name (e.g. `"Production Server"`)
-3. Click **Create API Key**
+- **Via API** — see [Quickstart](/quickstart#1-get-your-api-key) for the two-call signup + verify flow. When an agent runs this on behalf of a human, the agent passes the code the human reads back from their inbox.
+- **Via dashboard** — go to [chat.recoupable.com/keys](https://chat.recoupable.com/keys), sign in, and create one.
-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
+## Access control
-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:
+Scoping parameters follow the same organization-membership rule:
```
-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
+
+Request includes organization_id?
+ ├── Key owner is a member of that org → allowed
+ └── Not a member → 403
+
+Request includes artist_account_id?
+ ├── Artist belongs to the key owner → allowed
+ ├── Artist belongs to an org the key owner is a member of → allowed
+ └── Neither → 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/index.mdx b/index.mdx
index e2e5cbf..068376f 100644
--- a/index.mdx
+++ b/index.mdx
@@ -1,187 +1,175 @@
---
-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 Recoup?"
+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. Recoup 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:
+## Core concepts
-```bash
-https://recoup-api.vercel.app/api
-```
+| 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. |
-## Authentication
+## Get started
-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.
+- **[Quickstart](/quickstart)** — Get an API key and make your first call. ~5 minutes.
+- **[Agent onboarding](/agents)** — The operating manual for AI agents using Recoup in production. Covers the throwaway-vs-account decision, the roster, and the persistent filesystem.
+- **[Authentication](/authentication)** — Reference for API keys, Bearer tokens, and access scoping.
-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"
-```
-
-
-Keep your API key secure. Do not share it publicly or commit it to version control.
-
+---
-## 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 whoami` to verify, `recoup artists list` to explore. 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.
+
+ Stream completions, manage threads, copy or delete messages, compact long histories. 11 endpoints. Pass `artist_account_id` to scope responses to a specific artist.
+
- 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.
+ 31 endpoints. Streaming metrics, audience demographics, playlist placements, festivals, charts, deep research, and web extraction across Chartmetric, Spotify, Instagram, and X.
- Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.
+ Add artists, link social accounts, pin priority work, browse fans, 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-driven 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 endpoints — generate images, videos, captions; transcribe audio; edit, upscale, analyze video. Compose them yourself, end to end.
- Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.
+ Schedule recurring tasks. Trigger pulses on events. Dispatch notifications when work completes.
- Accounts, organizations, workspaces, subscriptions, pulses, notifications, sandboxes, and admin tools.
+ Sign up agents, scope to organizations, connect external platforms via OAuth, run isolated sandboxes, manage subscriptions.
-## 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 two calls (signup + verify) — 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, 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, 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, fetch the canonical OpenAPI specifications — they're the single source of truth for endpoint paths, parameters, and response shapes. Base URL: `https://recoup-api.vercel.app/api`.
+
+| Domain | OpenAPI spec |
+|--------|--------------|
+| Research (streaming metrics, audience, playlists, charts, web intelligence) | [`openapi/research.json`](/api-reference/openapi/research.json) |
+| Content (images, videos, captions, transcription, editing, upscaling, analysis) | [`openapi/content.json`](/api-reference/openapi/content.json) |
+| Releases (artists, songs, catalogs) | [`openapi/releases.json`](/api-reference/openapi/releases.json) |
+| Accounts (agents, accounts, organizations, sandboxes, subscriptions, admins) | [`openapi/accounts.json`](/api-reference/openapi/accounts.json) |
+| Social (Spotify, Instagram, X, social scraping, connectors) | [`openapi/social.json`](/api-reference/openapi/social.json) |
+
+Authentication: `x-api-key` header (or `Authorization: Bearer ` for Privy). To get a key, `POST /api/agents/signup` with the human's email, then `POST /api/agents/verify` with the code from their inbox. Full flow at [/agents](/agents).
+
+For a guided entry point by category, use the top navigation — every endpoint has its own reference page.
diff --git a/quickstart.mdx b/quickstart.mdx
index 29092dd..f20d51a 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -1,175 +1,132 @@
---
title: "Quickstart"
-description: "Get a Recoup API key in one call and make your first request — no browser, no dashboard."
+description: "API key in 2 calls. First request in minutes. No signup form, no dashboard."
---
-## Quickest start
+A 5-minute hello-world. Get an API key, hit the research endpoint, optionally connect an MCP-compatible agent.
-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`:
+
+**Building an AI agent that acts on a user's behalf?** See [Agent onboarding](/agents) instead — it covers the throwaway-vs-account decision, the user's roster, and the persistent filesystem. This page assumes you're trying the API yourself.
+
+
+## 1. Get your API key
```bash
-export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \
+# 1. Trigger a verification code to your inbox
+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)
-```
+ -d '{"email": "you@example.com"}'
-Verify it worked:
-
-```bash
-curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id
+# 2. Check your email, then exchange the code for a key
+export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/verify" \
+ -H "Content-Type: application/json" \
+ -d '{"email": "you@example.com", "code": "123456"}' | jq -r .api_key)
```
-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 flow including how an agent passes the code on behalf of a human.
-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 os
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": os.environ["RECOUP_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);
-```
-
-```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);
+const response = await fetch(
+ "https://recoup-api.vercel.app/api/research?q=Drake",
+ { headers: { "x-api-key": process.env.RECOUP_API_KEY } },
+);
+console.log(await response.json());
```
-**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
- }
- ]
-}
+---
+
+## 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?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?artist=Drake" \
+ -H "x-api-key: $RECOUP_API_KEY"
+
+# Editorial playlist placements
+curl "https://recoup-api.vercel.app/api/research/playlists?artist=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).
-
+See the [Research tab](/api-reference/research/search) for all 30+ research endpoints.
-## 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+ endpoints. See the [MCP guide](/mcp) for setup.
-With your API key ready, you can now:
+---
+
+## Next steps
- Fetch artist profiles and social accounts.
+ 30+ endpoints — metrics across 14 platforms, audience data, playlists, career history, web intelligence.
- Access fan data across all connected social platforms.
+ 7 endpoints for images, videos, captions, transcription, editing, upscaling, and analysis.
- 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).
diff --git a/workflows/create-artist.mdx b/workflows/create-artist.mdx
index a64d640..8cadea6 100644
--- a/workflows/create-artist.mdx
+++ b/workflows/create-artist.mdx
@@ -3,6 +3,10 @@ title: 'Create a New Artist'
description: 'End-to-end workflow to create, research and enrich a new artist account in a single session.'
---
+
+**Don't run this workflow under a throwaway `agent+` account.** Artist data created against a `agent+...@recoupable.com` email is permanently isolated to that account and can't be recovered if the API key is lost. Only run this workflow after the user has authenticated with their real email — see [Choose your path](/agents#0-choose-your-path) for guidance on which auth scenario fits.
+
+
This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to "researched + enriched" parity from a sandbox or any external agent.
The chain is 8 sequential API calls. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.