docs: design overhaul + Skills tab + API doc merge

[recoupableorg]

Combines the design/narrative overhaul from feature/docs-design-overhaul (24 commits) with every API doc update shipped to main since the branches diverged, plus a homepage rewrite, new Skills tab, and brand cleanup.

What's in this PR

API doc merge (already accurate — nothing should regress)

• All 8 research PRs from main preserved (schema hardening, /research/track id-proxy, /research/curator Chartmetric contract, /research/track/playlists, error response alignment). research.json, accounts.json, releases.json are byte-identical to main.
• Artist surface rename integrated: /api/artist/socials → /api/artists/{id}/socials
• New endpoints surfaced in nav: artists/pin, artists/unpin, admins/agent-signups
• Deleted surfaces removed from nav: artist/segments, artist/socials (old), chat/segment, segment/fans

Home page

• Rewrote How it works as the actual agent loop (authenticate → find scope → read context → decide/act → persist) — removes ~80% overlap with the "What's in the API" cards
• Rewrote all 7 card descriptions for voice — killed overclaims ("the business infrastructure," "the engine that lets agents work while you sleep," "Everything about any artist from any source"); led each with verbs the endpoints actually support
• Added a Chat card (was missing from the grid despite having its own tab)
• Removed the test-key (agent+) pattern from all production paths: home snippet/tip, "For AI agents" footer, Step 1 caveat, quickstart.mdx headline demo, authentication.mdx "Instant (for agents)" subsection. Replaced with the honest 2-call signup+verify flow. agents.mdx retained as the one place agent+ is documented, with its existing warning that it creates a separate account.

Skills tab (new)

• Positioned last in the top nav
• Overview page (skills.mdx) covers concept, install, SKILL.md contract, contribution flow
• 10 per-skill pages under skills/ — each summarizes when the agent uses it, what it produces, which API endpoints it depends on, with source link to the canonical SKILL.md on recoupable/skills
• Sidebar groups the skills into Foundational / Research & analytics / Creative work (mirrors the API tab's sub-grouping pattern)
• No content duplication from the source repo — docs pages add docs-side context (endpoint cross-refs, when-to-use phrasing) the SKILL.md can't provide

Research tab nav

• Replaced the flat 26-page "Artist Research" group with main's sub-grouping: Artist discovery, Metrics & insights, Catalog, Playlists & curators, Charts & radio, Touring & live, Web intelligence

Brand

• Recoupable → Recoup (display name only — live URLs, GitHub org, npm package, email addresses, OpenAPI server URLs all untouched)
• New logos wired: wordmark-{light,dark}mode.svg in the header. Old dark.png / dark.svg / light.svg removed.
• Font system: Geist Pixel Square (heading, local woff2) + Geist Variable (body, local woff2). Removed Google Fonts dependency on Plus Jakarta Sans + Inter.
• fonts/ directory seeded with Geist / GeistMono / GeistPixel / InstrumentSerif / PlusJakartaSans — variable woff2 where available, ttf fallback for families without a variable woff2, no redundant weights

Verification

• docs.json parses as valid JSON
• 131 API .mdx files ↔ 131 API nav entries (0 orphans, 0 dead refs)
• 0 broken intra-doc links across all MDX
• All deleted surfaces from main are gone from disk and nav
• All new endpoints from main are present in nav and linked from relevant skill pages
• Full page render verified at http://localhost:3333, including every new skill sub-page

Not in this PR (flagged for follow-up if desired)

• Favicon still points at the legacy favicon.ico. The new icon-{light,dark}mode.svg files are staged but not wired.
• Mintlify "sequoia" theme limits font config to 2 slots (heading + body). Instrument Serif accent + GeistPixel variant styles were audited but can't be imported alongside the primary heading/body pair without leaving Mintlify. Noted for future architectural decision.

Made with Cursor

Summary by CodeRabbit

• Documentation
  • New Agent Onboarding (signup + verify), consolidated auth/access rules, sandbox-backed filesystem guide, decision guidance for common workflows, reorganized CLI, rewritten Quickstart, MCP Server guide, Content Agent Slack-bot reference, and many new Skills pages/playbooks.
• New Features
  • Added Skills hub and multiple skill playbooks (research, content-creation, release management, artist workspace, sandbox setup, songwriting, streaming growth, trend-to-song, chart-metric).
• Deprecation
  • POST /api/content/create marked deprecated; use individual content endpoints.
• Site Updates
  • Redesigned docs navigation, theme, and branding.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Reworks docs into an agent-first operating manual: adds a two-step agent signup/verify auth flow with x-api-key usage, introduces roster and sandbox filesystem guidance, adds a Skills system with multiple skill pages, deprecates the content pipeline endpoint, and updates CLI, MCP, landing page, and site navigation/branding.

Changes

Cohort / File(s)	Summary
Auth & Onboarding agents.mdx, authentication.mdx, index.mdx, quickstart.mdx	Adds two-step agent signup/verify flow and instructs sending api_key via x-api-key (or Bearer); consolidates access rules for account_id/organization_id/artist_account_id; replaces earlier single-call quickstart and key guidance; adds roster-check step.
Content API / OpenAPI api-reference/openapi/content.json	Marks POST /api/content/create (and some generation/transcribe endpoints) as legacy/deprecated and updates descriptions to point to per-primitive POST /api/content/* endpoints; standardizes description punctuation and array formatting.
Skills System (new pages) skills.mdx, skills/* (e.g. skills/artist-workspace.mdx, skills/getting-started.mdx, skills/content-creation.mdx, skills/*)	Introduces Skills concept and multiple skill playbooks with triggers, folder conventions, APIs used, and contribution guidance.
CLI docs cli.mdx	Reorganizes into a Commands section, shortens examples and flags, emphasizes terminal-first workflows, trims research subcommands, and points advanced content ops to REST primitives.
MCP & Content Agent mcp.mdx, content-agent.mdx	Reframes MCP as “MCP Server” with Bearer token examples (RECOUP_API_KEY/Privy), removes/condenses sandbox/tool schemas, adds a tool catalog; rewrites Content Agent as a Slack-bot reference and updates endpoints/architecture notes.
Site config & Branding docs.json	Swaps theme to Sequoia, adjusts typography/colors, reorganizes navigation (new top-level tabs/groups), updates logo/CTA/footer/socials and OpenGraph metadata.
Assets / License fonts/InstrumentSerif/OFL.txt	Adds SIL Open Font License text for Instrument Serif.
OpenAPI text tweaks & frontmatter api-reference/openapi/research.json, api-reference/image/generation.mdx, api-reference/transcribe/audio.mdx, api-reference/openapi/releases.json, api-reference/spotify/search.mdx, api-reference/research/search.mdx	Frontmatter title adjustments (legacy labeling), replaced “memory/memories” wording with “message/messages”, escaped/standardized em-dash characters and minor OpenAPI response/description reformatting.

Sequence Diagram(s)

sequenceDiagram
  participant Agent as Agent (client)
  participant Auth as Auth Service
  participant API as Recoup REST API
  participant FS as Sandbox Filesystem
  participant MCP as MCP Server

  Agent->>Auth: POST /api/agents/signup (email)
  Auth-->>Agent: 200 (sent 6-digit code)
  Agent->>Auth: POST /api/agents/verify (email, code)
  Auth-->>Agent: 200 (api_key)
  Agent->>API: GET /api/accounts or /api/roster (x-api-key)
  API-->>Agent: 200 (accounts, artists, orgs)
  Agent->>FS: GET /api/sandboxes (x-api-key)
  FS-->>Agent: 200 (sandbox list)
  Agent->>FS: POST /api/sandboxes/files (upload with x-api-key)
  Agent->>API: Calls (research/content/tasks) (x-api-key)
  API-->>MCP: Optional MCP interactions (Bearer or forwarded tooling calls)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• docs: Agent Signup & Verify endpoints #104: Overlaps agent onboarding and edits the same authentication/onboarding docs (agents.mdx, authentication.mdx, quickstart.mdx, index.mdx).
• feat: content V2 docs — malleable-first architecture, templates optional #100: Aligns with Content API V2 work and removal/deprecation of the pipeline POST /api/content/create.
• refactor: split openapi.json into 5 domain-specific specs #121: Modifies the same OpenAPI operation (POST /api/content/create) in api-reference/openapi/content.json.

Suggested reviewers

• sweetmantech

"🐰 I hopped through docs with nimble feet,
Signup then verify — keys kept neat,
Sandboxes stacked and skills in a row,
Agents now know where to dig and grow,
A tiny rabbit cheers: docs ready to go!"

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the three main changes: design overhaul, Skills tab addition, and API doc merge. It directly relates to the core changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docs-design-overhaul-combined

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 7

🧹 Nitpick comments (2)

skills/getting-started.mdx (1)

12-14: Clarify environment variable setup.

The description states this produces "A working RECOUP_API_KEY environment variable," but the referenced endpoints (POST /api/agents/signup and POST /api/agents/verify) return the API key in the response body, not as an environment variable. The skill would need to explicitly set the environment variable after receiving the key response. Consider rewording to: "A working API key (stored as RECOUP_API_KEY)" or "An API key from signup/verify, configured as RECOUP_API_KEY environment variable."

📝 Suggested rewording for clarity

 ## What it produces
 
-A working `RECOUP_API_KEY` environment variable, the chosen base URL (REST or MCP), and a verified first response.
+An API key from signup/verify (configured as `RECOUP_API_KEY` environment variable), the chosen base URL (REST or MCP), and a verified first response.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/getting-started.mdx` around lines 12 - 14, Update the sentence "A
working `RECOUP_API_KEY` environment variable, the chosen base URL (REST or
MCP), and a verified first response." in the getting-started content: clarify
that the signup/verify endpoints return an API key in the response and the user
must store it as an environment variable; replace the phrase with one of the
suggested rewordings such as "A working API key (stored as `RECOUP_API_KEY`),
the chosen base URL (REST or MCP), and a verified first response" or "An API key
from signup/verify, configured as the `RECOUP_API_KEY` environment variable" so
it correctly reflects that the key is returned by POST /api/agents/signup and
POST /api/agents/verify and must then be set as an env var.

authentication.mdx (1)

42-98: Minor: HMAC-SHA256 storage note is duplicated.

The "stored as HMAC-SHA256 hashes" fact appears both in the <Warning> at line 42 and again in the Security section at line 96. Consider keeping one authoritative mention (e.g., the Security section) and trimming the Warning to just the "shown once / cannot be retrieved" guidance.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@authentication.mdx` around lines 42 - 98, The HMAC-SHA256 storage note is
duplicated between the <Warning> block and the Security section; edit the
content so the Warning only states that keys are shown once and cannot be
retrieved (remove the "stored as HMAC-SHA256 hashes" phrase) and keep the
HMAC-SHA256 storage detail exclusively in the Security section; update the
<Warning> text near the "Keys are shown once" line and verify the Security
section still includes the full "Keys stored as HMAC-SHA256 hashes — never
plaintext" sentence.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@cli.mdx`:
- Around line 230-264: The "Content creation pipeline" CLI docs still promote
the deprecated monolithic command (examples showing "recoup content
create")—update the CLI docs section for "content" to warn users that POST
/api/content/create is deprecated and point them to the new individual
subcommands (e.g., "recoup generate-image", "recoup generate-video", "recoup
generate-caption", and the new "recoup content templates/validate/estimate"
flow); add a brief Note/Warning immediately under the section title referencing
those new subcommands and replace or augment the "Create" examples so they show
the recommended split commands or a forward-reference to where users can find
the new commands.

In `@content-agent.mdx`:
- Around line 44-54: The table's displayed endpoint paths (e.g., "POST
/api/content/image", "POST /api/content/video", "POST /api/content/caption",
"POST /api/content/transcribe", "PATCH /api/content", "POST
/api/content/upscale", "POST /api/content/analyze") should be updated to match
the canonical documented paths used in the linked references (use the exact
canonical endpoints from the API reference pages), and explicitly mark "POST
/api/content/create" as legacy; update the table cell text for each row to the
canonical path string used in the reference links and add a "(legacy)" note
beside "POST /api/content/create" so readers are not directed to the deprecated
pipeline.

In `@docs.json`:
- Around line 5-9: The docs color palette is inconsistent: colors.dark is set to
"#171717" but must match the achromatic brand primary "#0a0a0a"; update the
colors object so colors.dark equals colors.primary ("#0a0a0a") to keep the
palette consistent with the primary brand color, and ensure the theme
("sequoia") and any validation rules accept "#0a0a0a" as the correct primary
value (refer to colors.primary and colors.dark in the JSON).

In `@index.mdx`:
- Around line 130-136: The Content card currently links to a deprecated endpoint
via href="/api-reference/content/create"; update the Card component (the
instance with title="Content" and icon="sparkles") to point to a supported
endpoint such as "/api-reference/content/generate-image" (or another valid
supported path like "/api-reference/content/generate-video" or
"/api-reference/content/generate-caption") so the landing page directs users to
a non-deprecated API surface.

In `@mcp.mdx`:
- Around line 16-27: The snippet uses the undefined RECOUP_API_KEY in the
template literal passed to StreamableHTTPClientTransport; declare and initialize
RECOUP_API_KEY before creating transport (e.g., read from environment or set a
placeholder value) so the transport construction has a defined Authorization
value; update the top of the snippet near the import block so symbols
StreamableHTTPClientTransport, transport, and Client remain unchanged and the
client.connect call works when copied.

In `@skills/artist-workspace.mdx`:
- Around line 18-21: Replace the incorrect endpoint label `GET
/api/artist/profile` with the canonical `GET /api/artists/{id}` and update its
reference link so it points to the correct OpenAPI page for the artist profile
(use the same pattern as the other links, e.g., change the link target that
currently points to the profile page to the artists/{id} reference). Ensure the
visible text and the URL both use `GET /api/artists/{id}` so users are directed
to the correct API surface.

In `@skills/trend-to-song.mdx`:
- Line 14: Replace the user-facing typo "ship-window" in the sentence beginning
"A trend brief (what the moment is, why it's resonating, who's reacting)..."
with a clearer phrase such as "shipping window" (or "short window" if you prefer
concision) so the copy reads "...a tight shipping window before the moment
fades." Update that exact phrase in the skills/trend-to-song content.

---

Nitpick comments:
In `@authentication.mdx`:
- Around line 42-98: The HMAC-SHA256 storage note is duplicated between the
<Warning> block and the Security section; edit the content so the Warning only
states that keys are shown once and cannot be retrieved (remove the "stored as
HMAC-SHA256 hashes" phrase) and keep the HMAC-SHA256 storage detail exclusively
in the Security section; update the <Warning> text near the "Keys are shown
once" line and verify the Security section still includes the full "Keys stored
as HMAC-SHA256 hashes — never plaintext" sentence.

In `@skills/getting-started.mdx`:
- Around line 12-14: Update the sentence "A working `RECOUP_API_KEY` environment
variable, the chosen base URL (REST or MCP), and a verified first response." in
the getting-started content: clarify that the signup/verify endpoints return an
API key in the response and the user must store it as an environment variable;
replace the phrase with one of the suggested rewordings such as "A working API
key (stored as `RECOUP_API_KEY`), the chosen base URL (REST or MCP), and a
verified first response" or "An API key from signup/verify, configured as the
`RECOUP_API_KEY` environment variable" so it correctly reflects that the key is
returned by POST /api/agents/signup and POST /api/agents/verify and must then be
set as an env var.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 046b2141-5f46-4cd6-b3bf-94c4cdbc07d6

📥 Commits

Reviewing files that changed from the base of the PR and between 07ce55e and bcf3778.

⛔ Files ignored due to path filters (19)

• fonts/Geist/Geist-Variable.woff2 is excluded by !**/*.woff2
• fonts/Geist/Geist-VariableItalic.woff2 is excluded by !**/*.woff2
• fonts/GeistMono/GeistMono-Variable.woff2 is excluded by !**/*.woff2
• fonts/GeistMono/GeistMono-VariableItalic.woff2 is excluded by !**/*.woff2
• fonts/GeistPixel/GeistPixel-Circle.woff2 is excluded by !**/*.woff2
• fonts/GeistPixel/GeistPixel-Grid.woff2 is excluded by !**/*.woff2
• fonts/GeistPixel/GeistPixel-Line.woff2 is excluded by !**/*.woff2
• fonts/GeistPixel/GeistPixel-Square.woff2 is excluded by !**/*.woff2
• fonts/GeistPixel/GeistPixel-Triangle.woff2 is excluded by !**/*.woff2
• fonts/InstrumentSerif/InstrumentSerif-Italic.ttf is excluded by !**/*.ttf
• fonts/InstrumentSerif/InstrumentSerif-Regular.ttf is excluded by !**/*.ttf
• fonts/PlusJakartaSans/PlusJakartaSans-Variable.ttf is excluded by !**/*.ttf
• fonts/PlusJakartaSans/PlusJakartaSans-VariableItalic.ttf is excluded by !**/*.ttf
• logo/dark.png is excluded by !**/*.png
• logo/icon-darkmode.svg is excluded by !**/*.svg
• logo/icon-lightmode.svg is excluded by !**/*.svg
• logo/light.svg is excluded by !**/*.svg
• logo/wordmark-darkmode.svg is excluded by !**/*.svg
• logo/wordmark-lightmode.svg is excluded by !**/*.svg

📒 Files selected for processing (21)

• agents.mdx
• api-reference/openapi/content.json
• authentication.mdx
• cli.mdx
• content-agent.mdx
• docs.json
• fonts/InstrumentSerif/OFL.txt
• index.mdx
• mcp.mdx
• quickstart.mdx
• skills.mdx
• skills/artist-workspace.mdx
• skills/chart-metric.mdx
• skills/content-creation.mdx
• skills/getting-started.mdx
• skills/music-industry-research.mdx
• skills/release-management.mdx
• skills/setup-sandbox.mdx
• skills/song-writing.mdx
• skills/streaming-growth.mdx
• skills/trend-to-song.mdx

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Use the canonical artist profile endpoint in the endpoint list.

Line 20 still advertises GET /api/artist/profile, but the provided OpenAPI context identifies the artist profile surface as GET /api/artists/{id}. The current label can send users to the wrong API path.

📝 Proposed endpoint-label fix

 - [`GET /api/artists`](/api-reference/artists/list)
 - [`POST /api/artists`](/api-reference/artists/create)
-- [`GET /api/artist/profile`](/api-reference/artist/profile)
+- [`GET /api/artists/{id}`](/api-reference/artist/profile)
 - [`GET /api/artists/{id}/socials`](/api-reference/artists/socials)

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- [`GET /api/artists`](/api-reference/artists/list)
	- [`POST /api/artists`](/api-reference/artists/create)
	- [`GET /api/artist/profile`](/api-reference/artist/profile)
	- [`GET /api/artists/{id}/socials`](/api-reference/artists/socials)
	- [`GET /api/artists`](/api-reference/artists/list)
	- [`POST /api/artists`](/api-reference/artists/create)
	- [`GET /api/artists/{id}`](/api-reference/artist/profile)
	- [`GET /api/artists/{id}/socials`](/api-reference/artists/socials)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/artist-workspace.mdx` around lines 18 - 21, Replace the incorrect
endpoint label `GET /api/artist/profile` with the canonical `GET
/api/artists/{id}` and update its reference link so it points to the correct
OpenAPI page for the artist profile (use the same pattern as the other links,
e.g., change the link target that currently points to the profile page to the
artists/{id} reference). Ensure the visible text and the URL both use `GET
/api/artists/{id}` so users are directed to the correct API surface.

[cubic-dev-ai]

10 issues found across 40 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/artist-workspace.mdx">

<violation number="1" location="skills/artist-workspace.mdx:20">
P2: The endpoint path is documented incorrectly: `/api/artist/profile` should be `/api/artist-profile` to match the linked API reference and OpenAPI spec.</violation>
</file>

<file name="skills/content-creation.mdx">

<violation number="1" location="skills/content-creation.mdx:18">
P2: The endpoint paths shown in this list are inconsistent with the actual OpenAPI routes, which can mislead users into calling non-existent URLs.</violation>
</file>

<file name="agents.mdx">

<violation number="1" location="agents.mdx:104">
P2: The sandbox upload example uses an invalid request shape for `POST /api/sandboxes/files` (`files[].path` instead of required `files[].name` with optional top-level `path`), which will cause copied requests to fail validation.</violation>
</file>

<file name="index.mdx">

<violation number="1" location="index.mdx:133">
P2: Update the Content card to link to a supported endpoint (e.g., generate-image) instead of the deprecated /api/content/create surface.</violation>

<violation number="2" location="index.mdx:177">
P3: This card says agents get an API key “in one call,” but the page now documents a required two-call signup + verify flow.</violation>

<violation number="3" location="index.mdx:202">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

The new "complete endpoint map" is factually incorrect: it includes removed/nonexistent routes (for example `chat/segment`, `artist/segments`, `segment/fans`) and therefore documents API behavior that is not implemented.</violation>
</file>

<file name="authentication.mdx">

<violation number="1" location="authentication.mdx:81">
P2: The new access-control section omits `organization_id` authorization rules, which conflicts with other docs and can mislead integrators into incorrect scoping assumptions.</violation>
</file>

<file name="cli.mdx">

<violation number="1" location="cli.mdx:259">
P3: Flag the `recoup content create` example as legacy or direct users to the individual generate-image/video/caption subcommands so the CLI docs don’t push the deprecated pipeline.</violation>
</file>

<file name="docs.json">

<violation number="1" location="docs.json:432">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

Rule 2 violation: the PR claims the GitHub org URL is unchanged, but this diff changes GitHub links to a different org URL in docs.json. Update the links or correct the PR claim so behavior and documentation match.</violation>
</file>

<file name="skills/release-management.mdx">

<violation number="1" location="skills/release-management.mdx:19">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

This adds a non-existent API route (`GET /api/songs/songs`) in the endpoint list. Per the rule’s fabricated-reference clause, endpoint names must match real routes; use `GET /api/songs`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 11 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="index.mdx">

<violation number="1" location="index.mdx:209">
P2: The Accounts OpenAPI row incorrectly lists connectors; `/api/connectors` is in `social.json`, not `accounts.json`. This misroutes API consumers looking up connector schemas.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

skills/content-creation.mdx (1)

2-3: Use a human-readable page title in frontmatter

Line 2 uses a slug-style title (content-creation). Consider Content Creation for clearer nav/readability while keeping the filename slug unchanged.

As per coding guidelines: "Use clear, self-documenting titles and descriptions in documentation."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/content-creation.mdx` around lines 2 - 3, Update the frontmatter title
from the slug-style "content-creation" to a human-readable "Content Creation" so
the page nav and headings are clear; keep the filename as-is and only modify the
title field in the frontmatter (the title key in the existing diff) to the new
human-friendly string.

authentication.mdx (1)

13-15: Clarify that both signup and verify are unauthenticated.

The note says "Agent signup endpoints are unauthenticated", but only /agents/signup is named in the prose. Per accounts.json, both POST /api/agents/signup and POST /api/agents/verify have security: [] — worth making this explicit so readers don't wonder which header to send to /verify before they have a key.

📝 Suggested wording

-[Agent signup](/agents) endpoints are unauthenticated — they let agents get their first key without any credentials.
+The [agent signup and verify](/agents) endpoints are unauthenticated — they let agents get their first key without any credentials.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@authentication.mdx` around lines 13 - 15, The note only mentions the signup
endpoint as unauthenticated but both POST /api/agents/signup and POST
/api/agents/verify are unauthenticated per accounts.json; update the text in
authentication.mdx to explicitly state that both /agents/signup (POST
/api/agents/signup) and verify (POST /api/agents/verify) endpoints accept
requests without authentication so readers know not to send an API key or auth
header to /verify before obtaining one.

quickstart.mdx (1)

37-54: Make Python/JS samples consistent with the bash env-var pattern.

The bash block exports RECOUP_API_KEY, but the Python and JavaScript samples fall back to a literal "YOUR_API_KEY". Readers stepping through the CodeGroup top-to-bottom would expect the env var to carry through.

📝 Proposed tweak

 import requests
+import os
 
 response = requests.get(
     "https://recoup-api.vercel.app/api/research",
     params={"q": "Drake"},
-    headers={"x-api-key": "YOUR_API_KEY"}
+    headers={"x-api-key": os.environ["RECOUP_API_KEY"]}
 )
 print(response.json())

 const response = await fetch(
   "https://recoup-api.vercel.app/api/research?q=Drake",
-  { headers: { "x-api-key": "YOUR_API_KEY" } }
+  { headers: { "x-api-key": process.env.RECOUP_API_KEY } }
 );
 console.log(await response.json());

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@quickstart.mdx` around lines 37 - 54, Update the Python and JavaScript
examples to read the API key from the RECOUP_API_KEY environment variable
instead of the literal "YOUR_API_KEY": in the Python snippet import os and use
os.environ.get("RECOUP_API_KEY") (or os.getenv) when building the headers/params
for requests, and in the JavaScript snippet read process.env.RECOUP_API_KEY (or
a suitable env-access pattern for the shown runtime) when setting the
"x-api-key" header so the examples follow the same bash env-var pattern shown
earlier.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@index.mdx`:
- Around line 200-214: Update the OpenAPI spec links in the "For AI agents"
section of index.mdx to use root-relative paths instead of the hardcoded
developers.recoupable.com domain: change the Base URL line and each spec link
(e.g., the `openapi/research.json`, `openapi/content.json`,
`openapi/releases.json`, `openapi/accounts.json`, `openapi/social.json`
references) to `/api-reference/openapi/{domain}.json`, or alternatively replace
the hardcoded domain with the correct docs deployment domain if you confirm it
in the branding/config; ensure both the Base URL and the markdown link targets
are consistent.

---

Nitpick comments:
In `@authentication.mdx`:
- Around line 13-15: The note only mentions the signup endpoint as
unauthenticated but both POST /api/agents/signup and POST /api/agents/verify are
unauthenticated per accounts.json; update the text in authentication.mdx to
explicitly state that both /agents/signup (POST /api/agents/signup) and verify
(POST /api/agents/verify) endpoints accept requests without authentication so
readers know not to send an API key or auth header to /verify before obtaining
one.

In `@quickstart.mdx`:
- Around line 37-54: Update the Python and JavaScript examples to read the API
key from the RECOUP_API_KEY environment variable instead of the literal
"YOUR_API_KEY": in the Python snippet import os and use
os.environ.get("RECOUP_API_KEY") (or os.getenv) when building the headers/params
for requests, and in the JavaScript snippet read process.env.RECOUP_API_KEY (or
a suitable env-access pattern for the shown runtime) when setting the
"x-api-key" header so the examples follow the same bash env-var pattern shown
earlier.

In `@skills/content-creation.mdx`:
- Around line 2-3: Update the frontmatter title from the slug-style
"content-creation" to a human-readable "Content Creation" so the page nav and
headings are clear; keep the filename as-is and only modify the title field in
the frontmatter (the title key in the existing diff) to the new human-friendly
string.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 38e8355c-4c15-4372-8977-47a1e4976d86

📥 Commits

Reviewing files that changed from the base of the PR and between bcf3778 and 416fa08.

📒 Files selected for processing (13)

• agents.mdx
• api-reference/openapi/research.json
• authentication.mdx
• cli.mdx
• content-agent.mdx
• docs.json
• index.mdx
• mcp.mdx
• quickstart.mdx
• skills/artist-workspace.mdx
• skills/content-creation.mdx
• skills/release-management.mdx
• skills/trend-to-song.mdx

✅ Files skipped from review due to trivial changes (5)

• skills/artist-workspace.mdx
• skills/trend-to-song.mdx
• api-reference/openapi/research.json
• agents.mdx
• cli.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• content-agent.mdx

[cubic-dev-ai]

2 issues found across 6 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="mcp.mdx">

<violation number="1" location="mcp.mdx:39">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

`mcp.mdx` exceeds the rule’s 100-line limit and has become a multi-concern document instead of a small, focused page.</violation>

<violation number="2" location="mcp.mdx:78">
P3: Use the current brand name (`Recoup`) here for consistency with the rest of the docs.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

mcp.mdx exceeds the rule’s 100-line limit and has become a multi-concern document instead of a small, focused page.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At mcp.mdx, line 39:

<comment>`mcp.mdx` exceeds the rule’s 100-line limit and has become a multi-concern document instead of a small, focused page.</comment>

<file context>
@@ -30,27 +30,121 @@ await client.connect(transport);
 ---
 
-## Available tools
+## Tool catalog
+
+The server exposes 40+ tools organized by domain. Every tool returns structured JSON suitable for chaining into multi-step agent workflows.
</file context>

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

skills/content-creation.mdx (1)

29-29: ⚠️ Potential issue | 🟡 Minor

Remove stray trailing content token.

Line 29 contains a standalone 29, which will render as unintended page content.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/content-creation.mdx` at line 29, Remove the stray standalone token
"29" that appears as page content on line 29 of skills/content-creation.mdx;
locate the lone "29" text node and delete it (or move it into the intended
heading/metadata if it was meant to be part of a title or frontmatter) so it no
longer renders as unintended content.

🧹 Nitpick comments (2)

skills/content-creation.mdx (1)

6-10: Make “what/when” sections more scannable for operators.

Line 6 and Line 10 are dense run-on paragraphs; split into short bullets (trigger → actions → iteration loop) to improve scan speed.

As per coding guidelines "Keep documentation content concise and scannable".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/content-creation.mdx` around lines 6 - 10, Split the dense prose under
the opening description ("Turns the seven content primitives into finished
assets...") and the "## When to use it" section into short bullet lists to
improve scannability: create a "Trigger" bullet listing user intents that start
this flow (e.g., "create content", "make a video", "generate an image", "produce
a TikTok/Reel", "add captions", "iterate on existing content"), an "Actions"
bullet that maps to the primitives to run (generate, transcribe, edit, upscale,
analyze), and an "Iteration loop" bullet that shows follow-up steps (regenerate,
re-prompt, re-mux, try different audio/text, upscale). Update the paragraphs
referenced by the text beginning "Turns the seven content primitives..." and the
"## When to use it" block to use these bullets so operators can quickly scan
triggers → actions → iteration loop.

content-agent.mdx (1)

81-87: Optional: surface the legacy-endpoint nuance in the data flow.

Step 3 documents that the bot internally calls POST /api/content/create, which is the same endpoint marked deprecated in the Note above (lines 54–56) and in the OpenAPI spec. That's accurate to current behavior, but readers building agents from this page may be confused why the bot still calls the legacy pipeline. A one-liner here ("internal — to be migrated to individual endpoints") would close the loop, or alternatively a follow-up to migrate the bot itself.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content-agent.mdx` around lines 81 - 87, Add a one-line clarification after
step 3 of the Data flow explaining that the bot currently calls the legacy
internal endpoint POST /api/content/create (the deprecated pipeline) and that
this is intentional for now but is slated to be migrated to the newer individual
endpoints; reference the endpoint name POST /api/content/create and the mention
handler to make the connection explicit.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@mcp.mdx`:
- Around line 67-80: The section heading "Content — images, video, audio"
currently lists tools that don't belong there: `generate_txt_file` and
`create_knowledge_base` are file/utility actions, not media
generation/transcription, so either (A) move the `generate_txt_file` and
`create_knowledge_base` rows out of that table into the Utilities section
alongside `send_email`, `contact_team`, `get_local_time`, or (B) change the
heading to "Content — images, video, audio, files" to accurately reflect their
presence; update the table accordingly (remove rows if moving, or keep them and
update the heading if broadening) and ensure the Tools list elsewhere remains
consistent.

---

Outside diff comments:
In `@skills/content-creation.mdx`:
- Line 29: Remove the stray standalone token "29" that appears as page content
on line 29 of skills/content-creation.mdx; locate the lone "29" text node and
delete it (or move it into the intended heading/metadata if it was meant to be
part of a title or frontmatter) so it no longer renders as unintended content.

---

Nitpick comments:
In `@content-agent.mdx`:
- Around line 81-87: Add a one-line clarification after step 3 of the Data flow
explaining that the bot currently calls the legacy internal endpoint POST
/api/content/create (the deprecated pipeline) and that this is intentional for
now but is slated to be migrated to the newer individual endpoints; reference
the endpoint name POST /api/content/create and the mention handler to make the
connection explicit.

In `@skills/content-creation.mdx`:
- Around line 6-10: Split the dense prose under the opening description ("Turns
the seven content primitives into finished assets...") and the "## When to use
it" section into short bullet lists to improve scannability: create a "Trigger"
bullet listing user intents that start this flow (e.g., "create content", "make
a video", "generate an image", "produce a TikTok/Reel", "add captions", "iterate
on existing content"), an "Actions" bullet that maps to the primitives to run
(generate, transcribe, edit, upscale, analyze), and an "Iteration loop" bullet
that shows follow-up steps (regenerate, re-prompt, re-mux, try different
audio/text, upscale). Update the paragraphs referenced by the text beginning
"Turns the seven content primitives..." and the "## When to use it" block to use
these bullets so operators can quickly scan triggers → actions → iteration loop.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 99be9b9f-19e2-4125-b30d-3ff027e69317

📥 Commits

Reviewing files that changed from the base of the PR and between 416fa08 and 7645538.

📒 Files selected for processing (6)

• authentication.mdx
• content-agent.mdx
• index.mdx
• mcp.mdx
• quickstart.mdx
• skills/content-creation.mdx

✅ Files skipped from review due to trivial changes (1)

• index.mdx

[cubic-dev-ai]

2 issues found across 6 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="content-agent.mdx">

<violation number="1" location="content-agent.mdx:46">
P1: These endpoint paths were renamed in the table to routes that are not present in the API spec, so readers will call incorrect URLs.</violation>

<violation number="2" location="content-agent.mdx:52">
P1: The Analyze Video row lists `/api/content/analyze-video`, but the API spec defines `/api/content/analyze`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs.json`:
- Around line 243-252: Update the page titles for the two pairs of overlapping
docs so they clearly distinguish the different operations: change the
frontmatter/title of "api-reference/content/generate-image" and
"api-reference/image/generation" to something like "Generate Image (Content
API)" and "Generate Image (Image API)" respectively, and likewise change
"api-reference/content/transcribe-audio" and "api-reference/transcribe/audio" to
distinct titles such as "Transcribe Audio (Content API)" and "Transcribe Audio
(Transcribe API)"; locate and edit the title/frontmatter in each document to the
new disambiguated string so the nav shows the distinct labels.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: eb8e0a29-dfb5-454c-a2a4-19227ddba90d

📥 Commits

Reviewing files that changed from the base of the PR and between 7645538 and 4ecc1ce.

📒 Files selected for processing (1)

• docs.json

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check that the four pages exist and inspect their frontmatter + referenced OpenAPI operations
# to determine whether they are distinct endpoints or duplicates.
for p in \
  api-reference/content/generate-image \
  api-reference/content/transcribe-audio \
  api-reference/image/generation \
  api-reference/transcribe/audio; do
  echo "===== ${p}.mdx ====="
  f=$(fd -t f -p "${p}.mdx")
  if [ -z "$f" ]; then
    echo "MISSING"
  else
    head -n 20 "$f"
    echo "..."
    rg -nP '^(openapi|api):' "$f" || true
  fi
done

echo
echo "===== Confirm 131 .mdx ↔ 131 nav entries ====="
echo "Total api-reference/**/*.mdx on disk:"
fd -t f -e mdx . api-reference | wc -l
echo "Total api-reference/* nav entries in docs.json:"
rg -oP '"api-reference/[^"]+"' docs.json | sort -u | wc -l

Repository: recoupable/docs

Length of output: 1131

---

Disambiguate titles for the separate image generation and audio transcription endpoints.

The navigation includes distinct endpoints for image generation and audio transcription:

• api-reference/content/generate-image (POST /api/content/image) and api-reference/image/generation (GET /api/image/generate) both have the title "Generate Image"
• api-reference/content/transcribe-audio (POST /api/content/transcribe) and api-reference/transcribe/audio (POST /api/transcribe) both have the title "Transcribe Audio"

Since these reference different operations, their titles should differentiate them (e.g., "Generate Image (Content)" vs. "Generate Image (Image)", or similar) so readers can pick the correct one.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs.json` around lines 243 - 252, Update the page titles for the two pairs
of overlapping docs so they clearly distinguish the different operations: change
the frontmatter/title of "api-reference/content/generate-image" and
"api-reference/image/generation" to something like "Generate Image (Content
API)" and "Generate Image (Image API)" respectively, and likewise change
"api-reference/content/transcribe-audio" and "api-reference/transcribe/audio" to
distinct titles such as "Transcribe Audio (Content API)" and "Transcribe Audio
(Transcribe API)"; locate and edit the title/frontmatter in each document to the
new disambiguated string so the nav shows the distinct labels.

[cubic-dev-ai]

3 issues found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/image/generation.mdx">

<violation number="1" location="api-reference/image/generation.mdx:6">
P2: API reference pages in this repo are required to be frontmatter-only, but this change adds a `<Note>` body block to an `api-reference/` MDX file.</violation>
</file>

<file name="api-reference/transcribe/audio.mdx">

<violation number="1" location="api-reference/transcribe/audio.mdx:6">
P2: API reference pages in this repo must remain frontmatter-only; this added `<Note>` block should be removed and any endpoint guidance kept in OpenAPI/source docs to avoid drift.</violation>
</file>

<file name="api-reference/content/create.mdx">

<violation number="1" location="api-reference/content/create.mdx:6">
P2: `api-reference` endpoint pages are required to be frontmatter-only; adding a `<Note>` block here breaks the repository’s API-doc structure convention. Move this legacy guidance into the OpenAPI operation description instead.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 6 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/content.json">

<violation number="1" location="api-reference/openapi/content.json:619">
P2: `POST /api/content/create` description now documents `run_id`, but the endpoint response schema and response description use `runIds` (array). Keep the field name consistent to avoid client integration errors.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: POST /api/content/create description now documents run_id, but the endpoint response schema and response description use runIds (array). Keep the field name consistent to avoid client integration errors.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/content.json, line 619:

<comment>`POST /api/content/create` description now documents `run_id`, but the endpoint response schema and response description use `runIds` (array). Keep the field name consistent to avoid client integration errors.</comment>

<file context>
@@ -616,7 +616,7 @@
       "post": {
         "deprecated": true,
-        "description": "This pipeline endpoint is being phased out. Use the individual content endpoints (`generate-image`, `generate-video`, `generate-caption`, etc.) directly. Triggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).",
+        "description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `{run_id}` for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).",
         "security": [
           {
</file context>

Suggested change

"description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `{run_id}` for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).",

"description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` \u2014 an array of run IDs. Poll each via [`GET /api/tasks/runs`](/api-reference/tasks/runs).",

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

mcp.mdx (1)

159-161: Align terminology with authentication.mdx.

authentication.mdx uses "Org member" and "No org" to describe key scope; this Note introduces new terms ("Org-scoped keys", "Personal API keys") that aren't defined elsewhere. Either reuse the existing terminology or define these terms once in authentication.mdx and reference them here, to keep the model consistent across pages.

📝 Proposed wording aligned with authentication.mdx

 <Note>
-**Org-scoped keys** can target any account in their organization by passing `account_id` on tools that accept it. Personal API keys can only operate on their own data.
+Keys belonging to an **org member** can target any account in their organization by passing `account_id` on tools that accept it. Keys with **no org** can only operate on their own data. See [Authentication › Organization access](/authentication#organization-access).
 </Note>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@mcp.mdx` around lines 159 - 161, Update the Note to use the same terminology
as authentication.mdx: either replace "Org-scoped keys" with "Org member" and
"Personal API keys" with "No org", or add canonical definitions for "Org-scoped
keys" and "Personal API keys" in authentication.mdx and reference them here;
ensure the Note references the defined terms and explains that org-scoped keys
can target any account in their organization by passing account_id while
personal keys operate only on their own data.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@api-reference/openapi/content.json`:
- Line 1345: The "description" string listing video generation "mode" options
incorrectly implies a text-only "prompt" mode; change that entry to make clear
that image_url is always required (e.g., "prompt — create a video from text plus
a required image (image_url)"), and update the mirrored table in
content-agent.mdx to match; target the "description" field's modes list and the
"prompt" row in content-agent.mdx so both docs consistently state that image_url
is mandatory.
- Around line 618-619: The operation description for POST /api/content/create
currently states it returns `{run_id}` but the 202 response and the
ContentCreateResponse schema return `runIds` (an array); update the operation
description text to match the schema by replacing references to `run_id` with
`runIds` and describing that the endpoint returns an array of run IDs (or
conversely, if intended shape is a single run_id, change the 202 response and
ContentCreateResponse schema to `run_id` instead) so the description and the
ContentCreateResponse/202 response block are consistent; locate the text in the
POST /api/content/create operation and the ContentCreateResponse schema to make
the matching change.

In `@mcp.mdx`:
- Around line 14-24: Update authentication.mdx to clarify the MCP endpoint
(/mcp) is an exception to the REST API auth rules: explicitly state that API
keys intended for server/script use should be sent to the MCP endpoint as
Authorization: Bearer <API_KEY> (as shown in mcp.mdx and quickstart.mdx) rather
than x-api-key, and add a short callout mentioning that Privy JWTs still use
Bearer and sending both headers may cause a 401; reference the MCP path and the
header names (x-api-key and Authorization) so readers know this MCP-specific
auth pattern differs from the REST API guidance.

---

Nitpick comments:
In `@mcp.mdx`:
- Around line 159-161: Update the Note to use the same terminology as
authentication.mdx: either replace "Org-scoped keys" with "Org member" and
"Personal API keys" with "No org", or add canonical definitions for "Org-scoped
keys" and "Personal API keys" in authentication.mdx and reference them here;
ensure the Note references the defined terms and explains that org-scoped keys
can target any account in their organization by passing account_id while
personal keys operate only on their own data.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5fdaaee2-1798-44d6-b069-2e84e9684101

📥 Commits

Reviewing files that changed from the base of the PR and between 4ecc1ce and 45ec620.

📒 Files selected for processing (10)

• api-reference/image/generation.mdx
• api-reference/openapi/content.json
• api-reference/openapi/releases.json
• api-reference/research/search.mdx
• api-reference/spotify/search.mdx
• api-reference/transcribe/audio.mdx
• content-agent.mdx
• docs.json
• mcp.mdx
• skills/trend-to-song.mdx

✅ Files skipped from review due to trivial changes (5)

• api-reference/research/search.mdx
• api-reference/transcribe/audio.mdx
• api-reference/spotify/search.mdx
• api-reference/image/generation.mdx
• skills/trend-to-song.mdx

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Keep the legacy pipeline response shape consistent.

The operation description still says POST /api/content/create returns {run_id}, but the 202 response and ContentCreateResponse schema now document runIds as an array. That contradiction will leak straight into the generated reference and push clients toward parsing the wrong payload.

🛠️ Suggested doc fix

-        "description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `{run_id}` for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).",
+        "description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers background work that generates short-form video. Returns `runIds` — an array of run IDs — for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).",

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi/content.json` around lines 618 - 619, The operation
description for POST /api/content/create currently states it returns `{run_id}`
but the 202 response and the ContentCreateResponse schema return `runIds` (an
array); update the operation description text to match the schema by replacing
references to `run_id` with `runIds` and describing that the endpoint returns an
array of run IDs (or conversely, if intended shape is a single run_id, change
the 202 response and ContentCreateResponse schema to `run_id` instead) so the
description and the ContentCreateResponse/202 response block are consistent;
locate the text in the POST /api/content/create operation and the
ContentCreateResponse schema to make the matching change.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Don't describe a text-only prompt mode if image_url is still mandatory.

These two descriptions now disagree with the request contract: the mode list still says prompt mode creates a video from text alone, while Line 2703 explicitly says text-only prompt mode is unsupported and the schema still requires image_url. As written, readers will try prompt-only requests and hit validation errors. Please reword the mode description to make it clear that image_url is always required, and update the mirrored table in content-agent.mdx in the same sweep.

🛠️ Suggested doc fix

-        "description": "Generate a video. Set `mode` to control what kind of video you get:\n\n- `prompt` — create a video from a text description\n- `animate` — animate a still image\n- `reference` — use an image as a style/subject reference (not the first frame)\n- `extend` — continue an existing video\n- `first-last` — generate a video that transitions between two images\n- `lipsync` — sync face movement to an audio clip\n\nIf `mode` is omitted, it's inferred from the inputs you provide.",
+        "description": "Generate a video. `image_url` is always required. Set `mode` to control how that input is used:\n\n- `prompt` — animate the input image using the supplied prompt\n- `animate` — animate a still image\n- `reference` — use an image as a style/subject reference (not the first frame)\n- `extend` — continue an existing video\n- `first-last` — generate a video that transitions between two images\n- `lipsync` — sync face movement to an audio clip\n\nIf `mode` is omitted, it's inferred from the inputs you provide.",

Also applies to: 2703-2703

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi/content.json` at line 1345, The "description" string
listing video generation "mode" options incorrectly implies a text-only "prompt"
mode; change that entry to make clear that image_url is always required (e.g.,
"prompt — create a video from text plus a required image (image_url)"), and
update the mirrored table in content-agent.mdx to match; target the
"description" field's modes list and the "prompt" row in content-agent.mdx so
both docs consistently state that image_url is mandatory.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

❓ Verification inconclusive

Script executed:

#!/bin/bash
# Confirm how the rest of the docs describe MCP auth and whether x-api-key vs Bearer
# is documented anywhere as an MCP-specific exception.
rg -nP -C2 '\b(x-api-key|Authorization:\s*Bearer|Bearer\s*\$\{?RECOUP_API_KEY)' --type=md --type=mdx
rg -nP -C3 '/mcp\b|MCP\b' authentication.mdx quickstart.mdx 2>/dev/null

Repository: recoupable/docs

---

Repository: recoupable/docs
Exit code: 0

stdout:

quickstart.mdx-82-
quickstart.mdx-83-## 4. Connect your AI agent
quickstart.mdx-84-
quickstart.mdx:85:If you're using Claude, ChatGPT, Cursor, or any MCP-compatible tool, connect directly:
quickstart.mdx-86-
quickstart.mdx-87-```
quickstart.mdx:88:https://recoup-api.vercel.app/mcp
quickstart.mdx-89-```
quickstart.mdx-90-
quickstart.mdx:91:Pass your API key as a Bearer token. Your agent gets access to all 40+ endpoints. See the [MCP guide](/mcp) for setup.
quickstart.mdx-92-
quickstart.mdx-93----
quickstart.mdx-94-

stderr:

unrecognized file type: mdx

---

Script executed:

# Search for authentication.mdx and examine its content
fd -t f authentication.mdx

Repository: recoupable/docs

---

Repository: recoupable/docs
Exit code: 0

stdout:

authentication.mdx

---

Script executed:

# Read the authentication.mdx file to understand the scope
cat authentication.mdx

Repository: recoupable/docs

---

Repository: recoupable/docs
Exit code: 0

stdout:

---
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

### 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"}'
```

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.

<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

---

Script executed:

# Search for MCP mentions and auth header patterns across all documentation
rg -i 'mcp|x-api-key|bearer.*recoup|authorization.*bearer' --type-add 'mdx:*.mdx' -t mdx -C 3

Repository: recoupable/docs

---

Repository: recoupable/docs
Exit code: 0

stdout:

workflows/create-artist.mdx-
workflows/create-artist.mdx-## Prerequisites
workflows/create-artist.mdx-
workflows/create-artist.mdx:- `$RECOUP_ACCESS_TOKEN` — Bearer token for `recoup-api.vercel.app`
workflows/create-artist.mdx-- `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes)
workflows/create-artist.mdx-- An artist name to create (e.g. `ARTIST_NAME="The Weeknd"`)
workflows/create-artist.mdx-
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-ARTIST_RESPONSE=$(curl -sS -X POST "https://recoup-api.vercel.app/api/artists" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  -H "Content-Type: application/json" \
workflows/create-artist.mdx-  -d "$(jq -n --arg name "$ARTIST_NAME" --arg org "$RECOUP_ORG_ID" \
workflows/create-artist.mdx-        '{name: $name, organization_id: $org}')")
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-SPOTIFY=$(curl -sS -G "https://recoup-api.vercel.app/api/spotify/search" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  --data-urlencode "q=$ARTIST_NAME" \
workflows/create-artist.mdx-  --data-urlencode "type=artist" \
workflows/create-artist.mdx-  --data-urlencode "limit=10")
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-curl -sS -X PATCH "https://recoup-api.vercel.app/api/artists/$ARTIST_ID" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  -H "Content-Type: application/json" \
workflows/create-artist.mdx-  -d "$(jq -n --arg image "$SPOTIFY_IMAGE_URL" --arg url "$SPOTIFY_PROFILE_URL" \
workflows/create-artist.mdx-        '{image: $image, profileUrls: {SPOTIFY: $url}}')"
workflows/create-artist.mdx-```
workflows/create-artist.mdx-
workflows/create-artist.mdx:This single endpoint replaces what the chat tool chain runs as four separate MCP calls (`update_account_info` ×2, `update_artist_socials` ×2). Add `label` to the body once you discover one in the structured research (step 4 — comes back from `/api/research/profile`). See [Update Artist](/api-reference/artists/update) for the full body schema.
workflows/create-artist.mdx-
workflows/create-artist.mdx-**After this step:** tick `- [ ] 3.` → `- [x] 3.`.
workflows/create-artist.mdx-
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-LOOKUP=$(curl -sS -G "https://recoup-api.vercel.app/api/research/lookup" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  --data-urlencode "spotifyId=$SPOTIFY_ARTIST_ID")
workflows/create-artist.mdx-
workflows/create-artist.mdx-CM_ARTIST_ID=$(echo "$LOOKUP" | jq -r '.artist.id // empty')
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-PROFILE=$(curl -sS -G "https://recoup-api.vercel.app/api/research/profile" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  --data-urlencode "id=$CM_ARTIST_ID")
workflows/create-artist.mdx-```
workflows/create-artist.mdx-
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-CAREER=$(curl -sS -G "https://recoup-api.vercel.app/api/research/career" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  --data-urlencode "id=$CM_ARTIST_ID")
workflows/create-artist.mdx-```
workflows/create-artist.mdx-
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-PLAYLISTS=$(curl -sS -G "https://recoup-api.vercel.app/api/research/playlists" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  --data-urlencode "id=$CM_ARTIST_ID")
workflows/create-artist.mdx-```
workflows/create-artist.mdx-
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-RESEARCH_WEB=$(curl -sS -X POST "https://recoup-api.vercel.app/api/research/web" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  -H "Content-Type: application/json" \
workflows/create-artist.mdx-  -d "$(jq -n --arg name "$ARTIST_NAME" \
workflows/create-artist.mdx-        '{query: ($name + " biography press recent collaborations")}')")
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-TOP_TRACKS=$(curl -sS -G "https://recoup-api.vercel.app/api/spotify/artist/topTracks" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  --data-urlencode "id=$SPOTIFY_ARTIST_ID")
workflows/create-artist.mdx-
workflows/create-artist.mdx-ALBUMS=$(curl -sS -G "https://recoup-api.vercel.app/api/spotify/artist/albums" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  --data-urlencode "id=$SPOTIFY_ARTIST_ID")
workflows/create-artist.mdx-
workflows/create-artist.mdx-# For each notable album, drill in (ALBUM_ID from $ALBUMS):
workflows/create-artist.mdx-ALBUM_DETAIL=$(curl -sS -G "https://recoup-api.vercel.app/api/spotify/album" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  --data-urlencode "id=$ALBUM_ID")
workflows/create-artist.mdx-```
workflows/create-artist.mdx-
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-SOCIALS_SEARCH=$(curl -sS -X POST "https://recoup-api.vercel.app/api/research/web" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  -H "Content-Type: application/json" \
workflows/create-artist.mdx-  -d "$(jq -n --arg name "$ARTIST_NAME" \
workflows/create-artist.mdx-        '{query: ($name + " official instagram tiktok twitter youtube")}')")
--
workflows/create-artist.mdx-
workflows/create-artist.mdx-```bash
workflows/create-artist.mdx-curl -sS -X PATCH "https://recoup-api.vercel.app/api/artists/$ARTIST_ID" \
workflows/create-artist.mdx:  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
workflows/create-artist.mdx-  -H "Content-Type: application/json" \
workflows/create-artist.mdx-  -d '{
workflows/create-artist.mdx-    "profileUrls": {
--
quickstart.mdx-
quickstart.mdx-```bash cURL
quickstart.mdx-curl "https://recoup-api.vercel.app/api/research?q=Drake" \
quickstart.mdx:  -H "x-api-key: $RECOUP_API_KEY"
quickstart.mdx-```
quickstart.mdx-
quickstart.mdx-```python Python
--
quickstart.mdx-response = requests.get(
quickstart.mdx-    "https://recoup-api.vercel.app/api/research",
quickstart.mdx-    params={"q": "Drake"},
quickstart.mdx:    headers={"x-api-key": os.environ["RECOUP_API_KEY"]},
quickstart.mdx-)
quickstart.mdx-print(response.json())
quickstart.mdx-```
--
quickstart.mdx-```javascript JavaScript
quickstart.mdx-const response = await fetch(
quickstart.mdx-  "https://recoup-api.vercel.app/api/research?q=Drake",
quickstart.mdx:  { headers: { "x-api-key": process.env.RECOUP_API_KEY } },
quickstart.mdx-);
quickstart.mdx-console.log(await response.json());
quickstart.mdx-```
--
quickstart.mdx-```bash
quickstart.mdx-# Streaming metrics (Spotify, Instagram, TikTok, YouTube, and 10 more)
quickstart.mdx-curl "https://recoup-api.vercel.app/api/research/metrics?artist=Drake&source=spotify" \
quickstart.mdx:  -H "x-api-key: $RECOUP_API_KEY"
quickstart.mdx-
quickstart.mdx-# Audience demographics (age, gender, geography)
quickstart.mdx-curl "https://recoup-api.vercel.app/api/research/audience?artist=Drake" \
quickstart.mdx:  -H "x-api-key: $RECOUP_API_KEY"
quickstart.mdx-
quickstart.mdx-# Editorial playlist placements
quickstart.mdx-curl "https://recoup-api.vercel.app/api/research/playlists?artist=Drake&editorial=true" \
quickstart.mdx:  -H "x-api-key: $RECOUP_API_KEY"
quickstart.mdx-```
quickstart.mdx-
quickstart.mdx-See the [Research tab](/api-reference/research/search) for all 30+ research endpoints.
--
quickstart.mdx-
quickstart.mdx-## 4. Connect your AI agent
quickstart.mdx-
quickstart.mdx:If you're using Claude, ChatGPT, Cursor, or any MCP-compatible tool, connect directly:
quickstart.mdx-
quickstart.mdx-```
quickstart.mdx:https://recoup-api.vercel.app/mcp
quickstart.mdx-```
quickstart.mdx-
quickstart.mdx:Pass your API key as a Bearer token. Your agent gets access to all 40+ endpoints. See the [MCP guide](/mcp) for setup.
quickstart.mdx-
quickstart.mdx----
quickstart.mdx-
--
index.mdx----
index.mdx-
index.mdx-<Info>
index.mdx:**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`)
index.mdx-</Info>
index.mdx-
index.mdx-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.
--
index.mdx-    icon="code"
index.mdx-    href="/quickstart"
index.mdx-  >
index.mdx:    Standard HTTP endpoints. Pass your API key in `x-api-key` and call any of the 40+ endpoints.
index.mdx-  </Card>
index.mdx-  <Card
index.mdx:    title="MCP Server"
index.mdx-    icon="cpu"
index.mdx:    href="/mcp"
index.mdx-  >
index.mdx:    Connect Claude, ChatGPT, Cursor, or any MCP-compatible agent directly. One URL.
index.mdx-  </Card>
index.mdx-  <Card
index.mdx-    title="CLI"
--
index.mdx-https://recoup-api.vercel.app/api
index.mdx-```
index.mdx-
index.mdx:All endpoints require `x-api-key` header authentication unless noted.
index.mdx-
index.mdx----
index.mdx-
--
index.mdx-| Accounts (agents, accounts, organizations, sandboxes, subscriptions, admins) | [`openapi/accounts.json`](/api-reference/openapi/accounts.json) |
index.mdx-| Social (Spotify, Instagram, X, social scraping, connectors) | [`openapi/social.json`](/api-reference/openapi/social.json) |
index.mdx-
index.mdx:Authentication: `x-api-key` header (or `Authorization: Bearer <token>` 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).
index.mdx-
index.mdx-For a guided entry point by category, use the top navigation — every endpoint has its own reference page.
--
mcp.mdx----
mcp.mdx:title: "MCP Server"
mcp.mdx-description: "Connect any AI agent to Recoup via the Model Context Protocol — Claude, ChatGPT, Cursor, and 40+ Recoup tools natively."
mcp.mdx----
mcp.mdx-
mcp.mdx:Recoup exposes an [MCP](https://modelcontextprotocol.io/) server so any AI agent can use Recoup tools natively. Claude, ChatGPT, Cursor, Windsurf, and any MCP-compatible agent can research artists across Spotify and the open web, generate images and videos, manage catalogs, schedule tasks, and more — without writing API calls.
mcp.mdx-
mcp.mdx-```
mcp.mdx:https://recoup-api.vercel.app/mcp
mcp.mdx-```
mcp.mdx-
mcp.mdx-## Setup
--
mcp.mdx-const RECOUP_API_KEY = process.env.RECOUP_API_KEY;
mcp.mdx-
mcp.mdx-const transport = new StreamableHTTPClientTransport(
mcp.mdx:  new URL("https://recoup-api.vercel.app/mcp"),
mcp.mdx:  { requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } },
mcp.mdx-);
mcp.mdx-
mcp.mdx-const client = new Client({ name: "my-agent", version: "1.0.0" });
--
mcp.mdx-console.log(result.content);
mcp.mdx-```
mcp.mdx-
mcp.mdx:Each tool's input schema is published over the MCP protocol, so your agent gets typed parameter help automatically.
mcp.mdx-
mcp.mdx-<Note>
mcp.mdx-**Org-scoped keys** can target any account in their organization by passing `account_id` on tools that accept it. Personal API keys can only operate on their own data.
--
agents.mdx-
agents.mdx-## 1. Authenticate
agents.mdx-
agents.mdx:If your human has an API key, pass it via `x-api-key`. If not, generate one:
agents.mdx-
agents.mdx-<Steps>
agents.mdx-  <Step title="Call signup with their email">
--
agents.mdx-      -H "Content-Type: application/json" \
agents.mdx-      -d '{"email": "user@example.com", "code": "123456"}'
agents.mdx-    ```
agents.mdx:    Store the returned `api_key`. Pass it as `x-api-key` on every request.
agents.mdx-  </Step>
agents.mdx-</Steps>
agents.mdx-
--
agents.mdx-```bash
agents.mdx-# List all artists available to this account
agents.mdx-curl "https://recoup-api.vercel.app/api/artists" \
agents.mdx:  -H "x-api-key: $API_KEY"
agents.mdx-
agents.mdx-# List organizations (labels/teams) the account belongs to
agents.mdx-curl "https://recoup-api.vercel.app/api/organizations" \
agents.mdx:  -H "x-api-key: $API_KEY"
agents.mdx-```
agents.mdx-
agents.mdx-**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.
--
agents.mdx-```bash
agents.mdx-# List the full file tree
agents.mdx-curl "https://recoup-api.vercel.app/api/sandboxes" \
agents.mdx:  -H "x-api-key: $API_KEY"
agents.mdx-
agents.mdx-# Read a specific file
agents.mdx-curl "https://recoup-api.vercel.app/api/sandboxes/file?path=orgs/my-label/artists/drake/context/artist.md" \
agents.mdx:  -H "x-api-key: $API_KEY"
agents.mdx-
agents.mdx-# Upload files to the repo
agents.mdx-# path is top-level (target directory); each file needs url + name
agents.mdx-curl -X POST "https://recoup-api.vercel.app/api/sandboxes/files" \
agents.mdx:  -H "x-api-key: $API_KEY" \
agents.mdx-  -H "Content-Type: application/json" \
agents.mdx-  -d '{"path": "orgs/my-label/artists/drake/context", "files": [{"url": "https://...", "name": "audience.md"}]}'
agents.mdx-```
--
agents.mdx-https://recoup-api.vercel.app/api
agents.mdx-```
agents.mdx-
agents.mdx: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.
--
authentication.mdx----
authentication.mdx-title: "Authentication"
authentication.mdx:description: "API keys and Bearer tokens — how to authenticate every request to the Recoup API."
authentication.mdx----
authentication.mdx-
authentication.mdx-**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`.
authentication.mdx-
authentication.mdx-| Method | Header | Best for |
authentication.mdx-|--------|--------|----------|
authentication.mdx:| API Key | `x-api-key` | Servers, scripts, CLI, AI agents |
authentication.mdx:| Bearer Token | `Authorization: Bearer <jwt>` | Frontend apps via Privy |
authentication.mdx-
authentication.mdx-<Note>
authentication.mdx-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.
--
authentication.mdx-
authentication.mdx-```bash
authentication.mdx-curl "https://recoup-api.vercel.app/api/research?q=Drake" \
authentication.mdx:  -H "x-api-key: YOUR_API_KEY"
authentication.mdx-```
authentication.mdx-
authentication.mdx----
--
authentication.mdx-
authentication.mdx-```bash
authentication.mdx-curl "https://recoup-api.vercel.app/api/tasks" \
authentication.mdx:  -H "Authorization: Bearer YOUR_PRIVY_JWT"
authentication.mdx-```
authentication.mdx-
authentication.mdx-The API validates the JWT against Privy, extracts the user's email, and resolves it to a Recoup account.
--
skills/getting-started.mdx----
skills/getting-started.mdx-title: "getting-started"
skills/getting-started.mdx:description: "Set up Recoup from scratch — get an API key, verify it, and make the first call via REST or MCP."
skills/getting-started.mdx----
skills/getting-started.mdx-
skills/getting-started.mdx:The agent's bootstrap. Walks through getting an API key, picking REST or MCP, and confirming the key works before any other skill runs.
skills/getting-started.mdx-
skills/getting-started.mdx-## When to use it
skills/getting-started.mdx-
--
skills/getting-started.mdx-
skills/getting-started.mdx-## What it produces
skills/getting-started.mdx-
skills/getting-started.mdx:A working `RECOUP_API_KEY` environment variable, the chosen base URL (REST or MCP), and a verified first response.
skills/getting-started.mdx-
skills/getting-started.mdx-## Endpoints it uses
skills/getting-started.mdx-

---

Clarify MCP endpoint authentication in authentication.mdx — it contradicts the documented auth model for REST API.

authentication.mdx states API keys use the x-api-key header (for "Servers, scripts, CLI, AI agents"), and Bearer tokens are reserved for Privy JWTs only ("providing both returns 401"). However, quickstart.mdx line 91 and the Setup snippet here both consistently pass API keys via Authorization: Bearer ${RECOUP_API_KEY} for the MCP endpoint.

Either add a note in authentication.mdx explaining that the MCP endpoint (/mcp) uses Bearer tokens for API keys (unlike the REST API), or add a callout in mcp.mdx stating this is an MCP-specific auth pattern that differs from REST API rules. Currently, readers following authentication.mdx will attempt x-api-key on the MCP endpoint.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@mcp.mdx` around lines 14 - 24, Update authentication.mdx to clarify the MCP
endpoint (/mcp) is an exception to the REST API auth rules: explicitly state
that API keys intended for server/script use should be sent to the MCP endpoint
as Authorization: Bearer <API_KEY> (as shown in mcp.mdx and quickstart.mdx)
rather than x-api-key, and add a short callout mentioning that Privy JWTs still
use Bearer and sending both headers may cause a 401; reference the MCP path and
the header names (x-api-key and Authorization) so readers know this MCP-specific
auth pattern differs from the REST API guidance.

[recoupableorg]

Closing in favor of a stack of focused PRs that split this combined change into single-responsibility units. Each is independently reviewable and revertible:

• docs: brand and theme refresh #168 — feat/docs-brand — brand & theme refresh (visual only)
• docs: CLI page accuracy pass #169 — feat/docs-cli — CLI page accuracy pass
• docs: MCP tool catalog rewrite #170 — feat/docs-mcp — MCP tool catalog rewrite (43 tools)
• docs: content & OpenAPI cleanup #171 — feat/docs-content-cleanup — content & OpenAPI hygiene
• docs: agent-first onboarding overhaul #172 — feat/docs-onboarding — agent-first onboarding overhaul
• docs: introduce Skills system #173 — feat/docs-skills — Skills system (10 playbooks)
• docs: navigation restructure #174 — feat/docs-nav — navigation restructure (depends on docs: agent-first onboarding overhaul #172, docs: introduce Skills system #173)

Each PR branches off origin/main directly. PRs #168–#173 are independent and can land in any order. PR #174 depends on #172 and #173 (their pages must exist for the new nav entries to resolve).

The original feat/docs-design-overhaul-combined branch is preserved as a backup but no longer being shipped.