docs: agent-first onboarding overhaul #172
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,96 +1,172 @@ | ||
| --- | ||
| title: "Agent Onboarding" | ||
| description: "The operating manual for AI agents using the Recoup API." | ||
| --- | ||
|
|
||
| This page is for AI agents that act on a user's behalf. Follow the steps in order. | ||
|
|
||
| <Note> | ||
| **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. | ||
| </Note> | ||
|
|
||
| ## 0. Choose your path | ||
|
|
||
| **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 question — paraphrase if needed, but keep the trade-off explicit: | ||
|
|
||
| > "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: | ||
|
|
||
| | 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: | ||
|
|
||
| <Steps> | ||
| <Step title="Call signup with their email"> | ||
| ```bash | ||
| curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"email": "user@example.com"}' | ||
| ``` | ||
| </Step> | ||
| <Step title="Ask the human for the code"> | ||
| A 6-digit code was sent to their inbox. Ask them: *"Check your email for a verification code and share it with me."* | ||
| </Step> | ||
| <Step title="Call verify with the code"> | ||
| ```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. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| **After authenticating, immediately check the roster.** Don't wait for the human to tell you what to do. | ||
|
|
||
| <Warning> | ||
| `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. | ||
| </Warning> | ||
|
|
||
| --- | ||
|
|
||
| ## 2. Understand the roster | ||
|
|
||
| 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: $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`. | ||
|
Comment on lines
+75
to
+112
There was a problem hiding this comment. Fix the filesystem path contradiction. This section says there is no Suggested fix-orgs/{org-name}/artists/{artist-slug}/
+artists/{artist-slug}/🤖 Prompt for AI Agents |
||
|
|
||
| ### Accessing sandbox files | ||
|
|
||
| ```bash | ||
| # 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 '{"path": "orgs/my-label/artists/drake/context", "files": [{"url": "https://...", "name": "audience.md"}]}' | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## 4. Decide what to do | ||
|
|
||
| <Steps> | ||
| <Step title="Does the human have a roster?"> | ||
| 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`. | ||
| </Step> | ||
| <Step title="What kind of work?"> | ||
| **Research** — use the 30+ research endpoints. Pass `artist_account_id` to scope to a rostered artist, or search by name for any artist globally. | ||
|
|
||
| **Content** — generate images, videos, and captions with the content endpoints. Artist context from the filesystem makes output more on-brand. | ||
|
|
||
| **Manage** — plan and track releases by creating and updating `RELEASE.md` files in the artist's `releases/` directory. Add songs to catalogs, update artist context, and organize the roster. | ||
| </Step> | ||
| <Step title="Should you save the work?"> | ||
| 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. | ||
| </Step> | ||
| <Step title="Should this be recurring?"> | ||
| 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. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| --- | ||
|
|
||
| ## Base URL | ||
|
|
||
| ``` | ||
| https://recoup-api.vercel.app/api | ||
| ``` | ||
|
|
||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,115 +1,94 @@ | ||
| --- | ||
| title: "Authentication" | ||
| description: "API keys and Bearer tokens — how to authenticate every request to the Recoup API." | ||
| --- | ||
|
|
||
| **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`. | ||
|
|
||
| | Method | Header | Best for | | ||
| |--------|--------|----------| | ||
| | API Key | `x-api-key` | Servers, scripts, CLI, AI agents | | ||
| | Bearer Token | `Authorization: Bearer <jwt>` | Frontend apps via Privy | | ||
|
|
||
| <Note> | ||
| 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. | ||
| </Note> | ||
|
|
||
| --- | ||
|
|
||
| ## Create a key | ||
|
|
||
| Two ways to get 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. | ||
|
|
||
| <Warning> | ||
| Keys are shown once. They are stored as HMAC-SHA256 hashes and cannot be retrieved after creation. | ||
| </Warning> | ||
|
|
||
| --- | ||
|
|
||
| ## Use a key | ||
|
|
||
| ```bash | ||
| curl "https://recoup-api.vercel.app/api/research?q=Drake" \ | ||
| -H "x-api-key: YOUR_API_KEY" | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Organization access | ||
|
|
||
| If your account belongs to an organization, your key can access data for any account in that org by passing `account_id`: | ||
|
|
||
| - **No org** — key accesses its own data only | ||
| - **Org member** — key can pass `account_id` to access any member's data | ||
|
|
||
| --- | ||
|
|
||
| ## Bearer tokens (Privy) | ||
|
|
||
| For frontend apps with [Privy](https://privy.io) authentication: | ||
|
|
||
| ```bash | ||
| curl "https://recoup-api.vercel.app/api/tasks" \ | ||
| -H "Authorization: Bearer YOUR_PRIVY_JWT" | ||
| ``` | ||
|
|
||
| The API validates the JWT against Privy, extracts the user's email, and resolves it to a Recoup account. | ||
|
|
||
| --- | ||
|
|
||
| ## Access control | ||
|
|
||
| Scoping parameters follow the same organization-membership rule: | ||
|
|
||
| ``` | ||
| 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 | ||
| ``` | ||
|
|
||
| ## Errors | ||
|
|
||
| | Status | Cause | | ||
| |--------|-------| | ||
| | `401` | Missing/invalid credentials, or both headers | | ||
| | `403` | Valid credentials, insufficient access | | ||
|
|
||
| ## Security | ||
|
|
||
| - 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 |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.