From 8de8e57d4846620879af2c4722703d744df297bc Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 27 Apr 2026 13:45:46 -0400 Subject: [PATCH 1/7] docs: agent-first onboarding overhaul MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites the onboarding surface so AI agents landing on the docs can self-serve API access in two unauthenticated curl calls instead of being routed to a browser-based dashboard signup. The four pages in this PR form one coherent narrative — index → quickstart → authentication → agents — and they're now consistent with each other. index.mdx (homepage): - New box at the top dedicated to agents, with the base URL, auth model, and one-step signup decision tree. - Reorganized into three reader paths: REST API, MCP Server, CLI. - New "What's in the API" card group organized by what agents do (Chat, Research, Artists, Catalog, Content, Automation, Accounts) rather than by HTTP verb or resource shape. - New "For AI agents" footer section with a domain → OpenAPI spec table, root-relative paths so the links don't 404 if served from a non-prod domain. quickstart.mdx: - Two-call agent-signup flow as the primary path (signup → ask user for verification code → verify → API key in env var). - Tabbed code samples (cURL / Python / JavaScript) all pull the API key from RECOUP_API_KEY env var consistently — no literal YOUR_API_KEY placeholders. - Removed the fictional `recoup research "Drake"` CLI snippet. authentication.mdx: - Honest, scoped access-control rules: account_id, organization_id, and artist_account_id each documented separately with allow/deny conditions. - Single source of truth for the HMAC-SHA256 storage note (was previously duplicated in two places). - Note that BOTH /agents/signup and /agents/verify are unauthenticated, so readers don't wonder which header to send to /verify before they have a key. agents.mdx: - Reframes as the "operating manual for AI agents using the Recoup API" — explicit, ordered steps an agent should follow on first contact: authenticate → understand the roster → know the filesystem → decide what to do. - Documents the artist-workspace filesystem convention (orgs/{org}/artists/{slug}/RECOUP.md, context/, songs/, etc.) so agents know how to persist context across runs. - Sandbox upload example uses the correct request shape ({path, files: [{url, name}]}) per the OpenAPI spec. These changes don't touch nav structure or content reference pages — those concerns ship in the other stack PRs. Made-with: Cursor --- agents.mdx | 179 ++++++++++++++++++++----------- authentication.mdx | 124 ++++++++++----------- index.mdx | 261 +++++++++++++++++++++++++-------------------- quickstart.mdx | 187 ++++++++++++-------------------- 4 files changed, 387 insertions(+), 364 deletions(-) diff --git a/agents.mdx b/agents.mdx index 8bbf1f04..d2fbeed9 100644 --- a/agents.mdx +++ b/agents.mdx @@ -1,96 +1,147 @@ --- -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. 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 data 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" \ +# List the full file tree +curl "https://recoup-api.vercel.app/api/sandboxes" \ + -H "x-api-key: $API_KEY" + +# Read a specific file +curl "https://recoup-api.vercel.app/api/sandboxes/file?path=orgs/my-label/artists/drake/context/artist.md" \ + -H "x-api-key: $API_KEY" + +# Upload files to the repo +# 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: $API_KEY" \ -H "Content-Type: application/json" \ - -d '{"email": "you@example.com"}' + -d '{"path": "orgs/my-label/artists/drake/context", "files": [{"url": "https://...", "name": "audience.md"}]}' ``` -Step 2 — submit the 6-digit code from the verification email: +--- -```bash -curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ - -H "Content-Type: application/json" \ - -d '{"email": "you@example.com", "code": "123456"}' -``` +## 4. Decide what to do -Response: + + + 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. -```json -{ - "account_id": "123e4567-e89b-12d3-a456-426614174000", - "api_key": "recoup_sk_abc123...", - "message": "Verified" -} -``` + **Content** — generate images, videos, and captions with the content endpoints. Artist context from the filesystem makes output more on-brand. -## Using 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`. -Pass the returned `api_key` in the `x-api-key` header on every authenticated request: + 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 -```bash -curl -X GET "https://recoup-api.vercel.app/api/tasks" \ - -H "x-api-key: YOUR_API_KEY" + 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 e7b7850e..ff5bde36 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -1,115 +1,109 @@ --- 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 +## Create a key + +### Sign up via API + +```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 from your inbox +curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ + -H "Content-Type: application/json" \ + -d '{"email": "you@example.com", "code": "123456"}' +``` -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. +When an agent runs the same flow on behalf of a human, the agent passes the code the human reads back from their inbox. -### Creating an API Key +### From the dashboard -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** +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: +## Access control -### 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 e2e5cbf0..df8ead8d 100644 --- a/index.mdx +++ b/index.mdx @@ -1,187 +1,214 @@ --- -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. +## 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 + +The shape of an agent loop on Recoup. + + + + Use the human's API key — that's how the agent inherits their roster, label, and history. If they don't have one, `POST /agents/signup` with their email, then pass the verification code from their inbox to `/agents/verify`. + + + `GET /accounts` and `/organizations` tell you what the human gave the agent access to. Pass `artist_account_id` or `organization_id` on subsequent calls to scope the work. + + + `/research/*` for outside-world data on any artist. `/artists/*` and `/songs/*` for what's already inside the label. The Filesystem holds the agent's persistent notes — brand voice, audience insights, prior decisions. + + + Your LLM reasons over the context. Recoup doesn't decide; it gives you the inputs and accepts the outputs. Call `/content/*` to make assets, `/tasks/*` to schedule recurring work, `/notifications/*` to message the human. + + + Write the new state back to the Filesystem. The next agent run picks up exactly where this one stopped. + + -This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. +--- -## Base URL +## Get an API key -All API requests should be made to: +Two calls. No dashboard. ```bash -https://recoup-api.vercel.app/api -``` - -## Authentication - -Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key. - -1. Navigate to the [API Keys Management Page](https://chat.recoupable.com/keys) -2. Sign in with your account -3. Create a new API key and copy it immediately (it's only shown once) +# 1. Trigger a verification code to the human's inbox +curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ + -H "Content-Type: application/json" \ + -d '{"email": "human@example.com"}' -```bash -curl -X GET "https://recoup-api.vercel.app/api/artists?accountId=YOUR_ACCOUNT_ID" \ +# 2. Ask the human for the code, then exchange it for a key +export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/verify" \ -H "Content-Type: application/json" \ - -H "x-api-key: YOUR_API_KEY" + -d '{"email": "human@example.com", "code": "123456"}' | jq -r .api_key) ``` - -Keep your API key secure. Do not share it publicly or commit it to version control. - + +The key is tied to the human's account, so the agent inherits everything they've already set up — artists, organizations, prior work. See the [Agents guide](/agents) for the full flow. + + +--- -## 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 29092dde..85a2a70a 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,175 +1,126 @@ --- 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 - -Sign up your agent and get an API key in a single API call — no dashboard, no browser, no human in the loop. This one-liner signs up a fresh `agent+` address and exports the returned key to `$RECOUP_API_KEY`: +## 1. Get your API key ```bash -export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ +# 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). From b7fdac6da8b8e9ef3cbdf38570572baede641950 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 27 Apr 2026 15:24:01 -0400 Subject: [PATCH 2/7] docs(agents): use $RECOUP_API_KEY consistently in curl examples The page used $API_KEY in 5 curl examples but quickstart.mdx (and the rest of the docs) document RECOUP_API_KEY as the env var to set after signup. Rename all 5 occurrences for consistency, and add a one-line note in step 1 explaining how to set the env var after receiving the api_key from /agents/verify, so the variable used in subsequent examples isn't undefined. Caught by cubic-dev-ai on PR #172. Made-with: Cursor --- agents.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/agents.mdx b/agents.mdx index d2fbeed9..e04eaa2a 100644 --- a/agents.mdx +++ b/agents.mdx @@ -26,7 +26,7 @@ If your human has an API key, pass it via `x-api-key`. If not, generate one: -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. + Store the returned `api_key` (e.g. `export RECOUP_API_KEY=`) and pass it as `x-api-key` on every request. @@ -45,11 +45,11 @@ After getting a key, your next call should always be to check what the human has ```bash # List all artists available to this account curl "https://recoup-api.vercel.app/api/artists" \ - -H "x-api-key: $API_KEY" + -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: $API_KEY" + -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. @@ -91,16 +91,16 @@ The `RECOUP.md` file ties the folder to the platform — it contains YAML frontm ```bash # List the full file tree curl "https://recoup-api.vercel.app/api/sandboxes" \ - -H "x-api-key: $API_KEY" + -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: $API_KEY" + -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: $API_KEY" \ + -H "x-api-key: $RECOUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"path": "orgs/my-label/artists/drake/context", "files": [{"url": "https://...", "name": "audience.md"}]}' ``` From 80252911446342a731671595978026df18bcdd5c Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 28 Apr 2026 10:55:32 -0400 Subject: [PATCH 3/7] docs(agents): replace placeholder with copy-paste-safe form Bash interprets `` as input redirection from a file named "value", so the previous example failed with "no such file or directory" when copy-pasted. Use `your-api-key` instead, matching the convention already in cli.mdx. Caught by cubic-dev-ai on PR #172. Made-with: Cursor --- agents.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agents.mdx b/agents.mdx index e04eaa2a..be244317 100644 --- a/agents.mdx +++ b/agents.mdx @@ -26,7 +26,7 @@ If your human has an API key, pass it via `x-api-key`. If not, generate one: -H "Content-Type: application/json" \ -d '{"email": "user@example.com", "code": "123456"}' ``` - Store the returned `api_key` (e.g. `export RECOUP_API_KEY=`) and pass it as `x-api-key` on every request. + Store the returned `api_key` (e.g. `export RECOUP_API_KEY=your-api-key`) and pass it as `x-api-key` on every request. From 77925bf30a932130052b1cc4d7c372fd49dbfd4d Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 28 Apr 2026 14:06:44 -0400 Subject: [PATCH 4/7] docs(agents): add "Choose your path" decision tree + create-artist warning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Helps agents pick the right auth path BEFORE they authenticate, and warns them away from creating persistent records under throwaway accounts. agents.mdx — new "## 0. Choose your path" section: A decision-tree table mapping each scenario to the right auth path: - Research/content output, no persistent state → throwaway agent+...@recoupable.com signup → DON'T create artists - Has account, work with existing roster → sign in with real email → list /api/artists - Has account, add a new artist → sign in with real email → run /workflows/create-artist - No account but wants persistent state → sign in with real email → run /workflows/create-artist after auth Followed by an explicit "key distinction" callout: agent+ emails create isolated, unrecoverable accounts. Use them ONLY for one-shot work where losing the API key has no cost. For persistent records, use the user's real email. This sits BEFORE step 1 so agents make the choice up front instead of falling through to the default flow. workflows/create-artist.mdx — new at the top: Don't run this workflow under a throwaway agent+ account. Artist data is permanently isolated to that account and can't be recovered if the API key is lost. See /agents#0-choose-your-path for guidance. Why this matters: The signup endpoint takes three paths (verified against api/lib/agents/agentSignupHandler.ts): 1. Existing account → always sends verification code, returns api_key: null 2. Brand-new agent+ email → creates isolated account, returns key instantly. No recovery mechanism. 3. Brand-new normal email → sends verification code Path 2 is the throwaway path. Each unique agent+xyz creates a separate account; data created on one is unreachable from another. If the API key is lost, the data is permanently orphaned (the email recovery code goes to a Recoupable inbox nobody monitors). Without this guidance, a literal-minded agent following the docs could create artists under a throwaway account and silently produce data that can't be retrieved later. Made-with: Cursor --- agents.mdx | 15 ++++++++++++++- workflows/create-artist.mdx | 4 ++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/agents.mdx b/agents.mdx index be244317..337d113d 100644 --- a/agents.mdx +++ b/agents.mdx @@ -5,9 +5,22 @@ description: "The operating manual for AI agents using the Recoup API." This page is for AI agents. Follow these steps in order. +## 0. Choose your path + +Pick the scenario that matches what your human is doing **before** you authenticate. The choice determines whether you can persist artist data across sessions. + +| Scenario | Auth path | Then | +|----------|-----------|------| +| User wants research or content output and doesn't need persistent state | Throwaway [`agent+...@recoupable.com`](#step-1-fast-throwaway) signup | Use research and content endpoints. **Don't create artists** — they'll orphan when the API key is lost. | +| User has a Recoup account and wants you to act on their existing roster | Sign in with their real email | List [`/api/artists`](/api-reference/artists/list); work with the roster they already have | +| User has a Recoup account and wants to add a new artist to their roster | Sign in with their real email | Run the [Create a New Artist](/workflows/create-artist) workflow | +| User has no Recoup account yet but wants persistent state | Sign in with their real email | After auth, run [Create a New Artist](/workflows/create-artist) to start their roster | + +**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. + ## 1. Authenticate -If your human has an API key, pass it via `x-api-key`. If not, generate one: +If your human has an API key, pass it via `x-api-key`. If not, generate one based on the path you chose above: diff --git a/workflows/create-artist.mdx b/workflows/create-artist.mdx index a64d640f..8cadea60 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. From eace49d38fa90399444569a8e5d150a1405e1d88 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 28 Apr 2026 14:14:41 -0400 Subject: [PATCH 5/7] docs(agents): instruct agents to ASK before choosing auth path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an explicit "ask first" instruction with a verbatim question template. The previous "Choose your path" section gave the scenarios but assumed the agent could read the human's intent — which is unreliable. The new pattern: 1. ASK the human up front (verbatim question template provided) 2. Match their answer to the path table 3. Skip the question only when context makes it obvious (explicit demo intent, explicit email already given, or autonomous agent with no human in the loop) Why this matters: The previous text relied on the agent inferring whether the human wants persistence. Real-world prompts like "build me a content campaign" don't reliably indicate intent — half the users want account-based persistence, half are just trying a demo. If the agent silently picks throwaway and the user re-prompts later, their roster is orphaned and they didn't know to expect that. A 5-second clarifying question is cheaper than that surprise. The verbatim template surfaces the trade-off (persist vs one-shot) in language a human can actually answer, and gives the agent a ready-made script so it doesn't have to invent the question itself. The "skip the question" clause preserves the easy-demo path: a human who says "just try the platform" or already provides their email gets straight to work without an extra round-trip. --- agents.mdx | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/agents.mdx b/agents.mdx index 337d113d..e10069ca 100644 --- a/agents.mdx +++ b/agents.mdx @@ -7,17 +7,25 @@ This page is for AI agents. Follow these steps in order. ## 0. Choose your path -Pick the scenario that matches what your human is doing **before** you authenticate. The choice determines whether you can persist artist data across sessions. +**Always ask the human first** unless context makes the choice obvious. Agents are unreliable at guessing intent, and choosing wrong silently costs the user their work — they re-prompt later and find their roster missing. -| Scenario | Auth path | Then | -|----------|-----------|------| -| User wants research or content output and doesn't need persistent state | Throwaway [`agent+...@recoupable.com`](#step-1-fast-throwaway) signup | Use research and content endpoints. **Don't create artists** — they'll orphan when the API key is lost. | -| User has a Recoup account and wants you to act on their existing roster | Sign in with their real email | List [`/api/artists`](/api-reference/artists/list); work with the roster they already have | -| User has a Recoup account and wants to add a new artist to their roster | Sign in with their real email | Run the [Create a New Artist](/workflows/create-artist) workflow | -| User has no Recoup account yet but wants persistent state | Sign in with their real email | After auth, run [Create a New Artist](/workflows/create-artist) to start their roster | +Use this as your default opener (paraphrase as appropriate to context): + +> "Quick question before we start — are you just exploring Recoup, or do you want me to use your Recoup account so this work persists? If you have an account, share your email and I'll send a verification code. Otherwise I can spin up a temporary one for one-shot use." + +Once you have the answer, match the human's intent to the right path: + +| 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 | **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. +**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. + ## 1. Authenticate If your human has an API key, pass it via `x-api-key`. If not, generate one based on the path you chose above: From 9459f9e79640230ecf148824dc3f8d349f6a9c3e Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 28 Apr 2026 14:20:47 -0400 Subject: [PATCH 6/7] docs(agents): tighten the "ask first" instruction and question template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Editorial pass on the prose I added in the previous commit. Three issues to address: 1. Lead instruction was self-referential ("Agents are unreliable at guessing intent...") and used softer "Always ask... unless..." framing. Switched to a direct imperative ("Ask the human which path they want before authenticating.") with the consequence stated in concrete terms ("creates records under a throwaway account that can't be recovered if the API key is lost"). 2. Question template had three weaknesses: - "Quick question before we start" — fluff opener that agents reproduce verbatim, padding every interaction with the same wind-up phrase - "share your email and I'll send a verification code" — the agent doesn't send the code (the API does); small accuracy bug that agents would propagate - "spin up a temporary one for one-shot use" — colloquial jargon that doesn't surface the actual consequence Rewritten to be tighter, accurate, and to surface the trade-off in the question itself: "...I'll create a temporary account — but you won't be able to save artists, releases, or scheduled tasks under it." The human now has enough to make an informed choice in one round-trip instead of asking a follow-up. 3. "Use this as your default opener (paraphrase as appropriate to context)" let the agent paraphrase away the trade-off. Changed to "paraphrase if needed, but keep the trade-off explicit" which gates the paraphrasing on preserving the key information. Net change: 3 lines, same structure, tighter language, accurate description of who does what. --- agents.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/agents.mdx b/agents.mdx index e10069ca..51c659dc 100644 --- a/agents.mdx +++ b/agents.mdx @@ -7,11 +7,11 @@ This page is for AI agents. Follow these steps in order. ## 0. Choose your path -**Always ask the human first** unless context makes the choice obvious. Agents are unreliable at guessing intent, and choosing wrong silently costs the user their work — they re-prompt later and find their roster missing. +**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. -Use this as your default opener (paraphrase as appropriate to context): +Use this question — paraphrase if needed, but keep the trade-off explicit: -> "Quick question before we start — are you just exploring Recoup, or do you want me to use your Recoup account so this work persists? If you have an account, share your email and I'll send a verification code. Otherwise I can spin up a temporary one for one-shot use." +> "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." Once you have the answer, match the human's intent to the right path: From b333f328f246b1d6d6d6f3ec27c622c9130293e7 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 28 Apr 2026 14:45:26 -0400 Subject: [PATCH 7/7] =?UTF-8?q?docs:=20simplify=20entry-point=20pages=20?= =?UTF-8?q?=E2=80=94=20one=20job=20per=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The four onboarding pages (index, quickstart, agents, authentication) were each trying to be self-contained, which produced contradictions: - Three different "first call after auth" instructions: index.mdx -> GET /accounts and /organizations quickstart -> GET /research?q=Drake agents.mdx -> GET /artists and /organizations - Three different "agent loop" descriptions on three pages - "Filesystem" introduced as a Core Concept on the homepage but only explained on agents.mdx - The signup curl duplicated 4x across pages, drifting subtly - Throwaway vs real-email path mentioned on agents.mdx but invisible on index/quickstart, leaving readers with mismatched mental models Fix: give each page one job and link elsewhere for everything else. index.mdx — now a router, not a tutorial: - Removed the "How it works" 5-step agent loop (third version of the agent flow, conflicted with quickstart and agents) - Removed the "Get an API key" section with inline curl (now lives in quickstart, the natural home for that snippet) - Removed Filesystem from Core Concepts (it's an agent-specific implementation detail, not a top-level concept) - New "Get started" routing block links to Quickstart, Agents, and Authentication with one-sentence descriptions of each quickstart.mdx — now explicitly the demo path: - New at top: "Building an AI agent that acts on a user's behalf? See /agents instead — it covers throwaway-vs-account, the roster, and the persistent filesystem." - Page intro reframes as "5-minute hello-world" agents.mdx — now explicitly the production manual: - New at top: "Just trying the API yourself? See /quickstart for a 5-minute hello-world." - Frames itself as the operating manual for production agents authentication.mdx — now pure reference: - Trimmed "Create a key" section: removed the inline signup curl (links to quickstart#1-get-your-api-key instead) and condensed the dashboard option to one line - Other sections (use a key, org access, Bearer tokens, access control rules, errors, security) stay as reference material After this change, each page has exactly one job: index - homepage router (no operational steps) quickstart - 5-min demo flow, one canonical scenario agents - production agent operating manual authentication - pure auth reference The signup curl now lives in exactly two places (quickstart and agents.mdx), each appropriate to its page's role. Other pages link. Made-with: Cursor --- agents.mdx | 6 +++++- authentication.mdx | 21 +++------------------ index.mdx | 47 ++++------------------------------------------ quickstart.mdx | 6 ++++++ 4 files changed, 18 insertions(+), 62 deletions(-) diff --git a/agents.mdx b/agents.mdx index 51c659dc..e94d749c 100644 --- a/agents.mdx +++ b/agents.mdx @@ -3,7 +3,11 @@ title: "Agent Onboarding" description: "The operating manual for AI agents using the Recoup API." --- -This page is for AI agents. Follow these steps in order. +This page is for AI agents that act on a user's behalf. Follow the steps in order. + + +**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. + ## 0. Choose your path diff --git a/authentication.mdx b/authentication.mdx index ff5bde36..f856c36a 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -18,25 +18,10 @@ The [agent signup and verify](/agents) endpoints (`POST /api/agents/signup` and ## Create a key -### Sign up via API +Two ways to get a key: -```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 from your inbox -curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ - -H "Content-Type: application/json" \ - -d '{"email": "you@example.com", "code": "123456"}' -``` - -When an agent runs the same flow on behalf of a human, the agent passes the code the human reads back from their inbox. - -### From the dashboard - -Go to [chat.recoupable.com/keys](https://chat.recoupable.com/keys), sign in, and create a 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. Keys are shown once. They are stored as HMAC-SHA256 hashes and cannot be retrieved after creation. diff --git a/index.mdx b/index.mdx index df8ead8d..068376fe 100644 --- a/index.mdx +++ b/index.mdx @@ -18,51 +18,12 @@ Running a record label takes a full team. Research, content, marketing, distribu | **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 - -The shape of an agent loop on Recoup. - - - - Use the human's API key — that's how the agent inherits their roster, label, and history. If they don't have one, `POST /agents/signup` with their email, then pass the verification code from their inbox to `/agents/verify`. - - - `GET /accounts` and `/organizations` tell you what the human gave the agent access to. Pass `artist_account_id` or `organization_id` on subsequent calls to scope the work. - - - `/research/*` for outside-world data on any artist. `/artists/*` and `/songs/*` for what's already inside the label. The Filesystem holds the agent's persistent notes — brand voice, audience insights, prior decisions. - - - Your LLM reasons over the context. Recoup doesn't decide; it gives you the inputs and accepts the outputs. Call `/content/*` to make assets, `/tasks/*` to schedule recurring work, `/notifications/*` to message the human. - - - Write the new state back to the Filesystem. The next agent run picks up exactly where this one stopped. - - ---- - -## Get an API key - -Two calls. No dashboard. - -```bash -# 1. Trigger a verification code to the human's inbox -curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ - -H "Content-Type: application/json" \ - -d '{"email": "human@example.com"}' - -# 2. Ask the human for the code, then exchange it 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": "human@example.com", "code": "123456"}' | jq -r .api_key) -``` +## Get started - -The key is tied to the human's account, so the agent inherits everything they've already set up — artists, organizations, prior work. See the [Agents guide](/agents) for the full flow. - +- **[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. --- diff --git a/quickstart.mdx b/quickstart.mdx index 85a2a70a..f20d51af 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -3,6 +3,12 @@ title: "Quickstart" description: "API key in 2 calls. First request in minutes. No signup form, no dashboard." --- +A 5-minute hello-world. Get an API key, hit the research endpoint, optionally connect an MCP-compatible agent. + + +**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