Docs: Split API reference into domain sub-routes

[recoup-coding-agent]

Summary

• Splits the monolithic "API reference" tab into 5 domain-specific navigation tabs
• Research: Artist research endpoints, artists, fans & segments, posts & comments, chat
• Releases: Songs & catalogs, tasks
• Content: Content creation, content agent, image generation, transcription, sandboxes
• Social Media: Spotify, Instagram, X (Twitter), social scraping, Apify, connectors
• Platform: Accounts, organizations, workspaces, subscriptions, admins, pulses, notifications
• All existing MDX page paths remain unchanged — only the navigation structure in docs.json is updated

Test plan

• Verify Mintlify deployment preview renders all 5 tabs correctly
• Confirm all existing API doc pages are accessible from the new navigation
• Check that no pages are missing from the navigation

🤖 Generated with Claude Code

---

Summary by cubic

Split the monolithic API reference into five tabs—Research, Releases, Content, Social Media, and Accounts—and refreshed the home page for faster onboarding and LLM navigation.

• Refactors
  • Merged api-reference/introduction into / with base URL/auth and OpenAPI link.
  • Updated base URL to https://recoup-api.vercel.app/api in the root page and Quickstart examples.
  • Renamed Guides tab to Quickstart.
  • Set Social Media default to Connectors list.
  • Moved Pulses to top of Accounts (Update first).
  • Moved Artists and Fans & Segments to Releases; moved Posts & Comments to Content; set Tasks third in Releases.
  • In Research, put Chat first with Stream first.
  • Updated the home page card to Accounts.

^{Written for commit f1a9dc6. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation
  • Reorganized documentation navigation with new top-level tabs: Research, Releases, Content, Social Media, and Platform.
  • Redistributed documentation groups across new tab structure for improved organization and discoverability.

[coderabbitai]

📝 Walkthrough

Walkthrough

The documentation navigation structure in docs.json has been reorganized from a single top-level "API reference" tab into five distinct tabs: "Research," "Releases," "Content," "Social Media," and "Platform," with page groups redistributed and renamed accordingly across the new tab hierarchy.

Changes

Cohort / File(s)	Summary
Documentation Navigation Restructuring docs.json	Reorganized top-level tabs from a single "API reference" to five tabs (Research, Releases, Content, Social Media, Platform). Redistributed and renamed page groups across new hierarchy; moved API documentation groups including songs/catalogs, accounts, organizations, social platforms, content creation, and notifications into their respective new tabs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: add Research API and CLI reference #85: Adds research pages and research group to docs.json; this PR restructures the overall navigation tabs and relocates the research content into the new hierarchy.

Suggested reviewers

• sweetmantech

Poem

🐰 Tabs reorganized with care,
Five new homes for docs everywhere!
Research, Releases, all in place,
Platform and Content find their space.
Navigation shines with polished grace! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: reorganizing the API reference documentation into domain-specific sub-routes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docs-sub-routes

---

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

[cubic-dev-ai]

No issues found across 1 file

[cubic-dev-ai]

3 issues found across 3 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:70">
P2: The text says "five main sections" but the CardGroup below shows six cards. Either update the count to "six" or merge Chat into the Research card to match.</violation>

<violation number="2" location="index.mdx:140">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**

The research quick reference is missing 2 of 30 endpoints: `instagram-posts` and `track`. An LLM relying on this section will not discover those endpoints. Add them to the list to match the actual `api-reference/research/` directory.</violation>
</file>

<file name="docs.json">

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

Broken indentation: the `{` opening the Research group lost all indentation when the preceding Overview group was removed. Every other group object in this file is indented with 10 spaces inside `"groups"` arrays. This is sloppy AI-generated formatting that harms readability.</violation>
</file>

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

[cubic-dev-ai]

P2: The text says "five main sections" but the CardGroup below shows six cards. Either update the count to "six" or merge Chat into the Research card to match.

Prompt for AI agents

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

<comment>The text says "five main sections" but the CardGroup below shows six cards. Either update the count to "six" or merge Chat into the Research card to match.</comment>

<file context>
@@ -24,79 +50,118 @@ This is where record labels, musicians, and managers start to build on Recoup AI
-## Key Capabilities
+## API Sections
+
+The API is organized into five main sections. Use these links to jump to the right area.
 
 <CardGroup cols={2}>
</file context>

Suggested change

	The API is organized into five main sections. Use these links to jump to the right area.
	The API is organized into six main sections. Use these links to jump to the right area.

[cubic-dev-ai]

P2: Custom agent: Flag AI Slop and Fabricated Changes

The research quick reference is missing 2 of 30 endpoints: instagram-posts and track. An LLM relying on this section will not discover those endpoints. Add them to the list to match the actual api-reference/research/ directory.

Prompt for AI agents

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

<comment>The research quick reference is missing 2 of 30 endpoints: `instagram-posts` and `track`. An LLM relying on this section will not discover those endpoints. Add them to the list to match the actual `api-reference/research/` directory.</comment>

<file context>
@@ -24,79 +50,118 @@ This is where record labels, musicians, and managers start to build on Recoup AI
+
+If you are an LLM navigating these docs, here is a summary of the endpoint structure:
+
+- **`/api/research/*`** — Artist research (search, lookup, profile, metrics, audience, cities, similar, urls, playlists, albums, tracks, career, insights, genres, festivals, web, deep, people, extract, enrich, milestones, venues, rank, charts, radio, discover, curator, playlist)
+- **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)
+- **`/api/chat/*`** — Chat (chats, artist, segment, messages, messages-copy, messages-trailing-delete, create, update, delete, generate, stream, compact)
</file context>

Suggested change

	- **`/api/research/*`** — Artist research (search, lookup, profile, metrics, audience, cities, similar, urls, playlists, albums, tracks, career, insights, genres, festivals, web, deep, people, extract, enrich, milestones, venues, rank, charts, radio, discover, curator, playlist)
	- **`/api/research/*`** — Artist research (search, lookup, profile, metrics, audience, cities, similar, urls, playlists, albums, track, tracks, career, insights, genres, festivals, web, deep, people, extract, enrich, milestones, venues, rank, charts, radio, discover, curator, playlist, instagram-posts)

[cubic-dev-ai]

2 issues found across 2 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:21">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

The base URL changed from the production domain (`api.recoupable.com`) to a Vercel deployment URL (`recoup-api.vercel.app`), but `authentication.mdx` and the majority of `openapi.json` endpoints still reference `api.recoupable.com`. This creates contradictory documentation — users following the homepage will hit a different host than users following the authentication guide. Either all docs should be updated consistently, or this change should be reverted to match the rest of the documentation.</violation>
</file>

<file name="quickstart.mdx">

<violation number="1" location="quickstart.mdx:11">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

The API base URL is silently changed from `api.recoupable.com` to `recoup-api.vercel.app` (a Vercel deployment URL), but the PR description claims only navigation structure was updated. This leaves the docs inconsistent — `authentication.mdx` still references `api.recoupable.com`, and many endpoint-level servers in `openapi.json` do as well. If this URL migration is intentional, it should be called out in the PR description and applied consistently; if not, this is an unintended change.</violation>
</file>

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

[cubic-dev-ai]

P1: Custom agent: Flag AI Slop and Fabricated Changes

The base URL changed from the production domain (api.recoupable.com) to a Vercel deployment URL (recoup-api.vercel.app), but authentication.mdx and the majority of openapi.json endpoints still reference api.recoupable.com. This creates contradictory documentation — users following the homepage will hit a different host than users following the authentication guide. Either all docs should be updated consistently, or this change should be reverted to match the rest of the documentation.

Prompt for AI agents

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

<comment>The base URL changed from the production domain (`api.recoupable.com`) to a Vercel deployment URL (`recoup-api.vercel.app`), but `authentication.mdx` and the majority of `openapi.json` endpoints still reference `api.recoupable.com`. This creates contradictory documentation — users following the homepage will hit a different host than users following the authentication guide. Either all docs should be updated consistently, or this change should be reverted to match the rest of the documentation.</comment>

<file context>
@@ -18,7 +18,7 @@ This is where record labels, musicians, and managers start to build on Recoup AI
 
 ```bash
-https://api.recoupable.com/api
+https://recoup-api.vercel.app/api

</file context>

</details>

<a href="https://www.cubic.dev/action/fix/violation/2e297e96-cdf5-4701-adcd-4c8a52df1987" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://cubic.dev/buttons/fix-with-cubic-light.svg">
    <img alt="Fix with Cubic" src="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
  </picture>
</a>

[cubic-dev-ai]

P1: Custom agent: Flag AI Slop and Fabricated Changes

The API base URL is silently changed from api.recoupable.com to recoup-api.vercel.app (a Vercel deployment URL), but the PR description claims only navigation structure was updated. This leaves the docs inconsistent — authentication.mdx still references api.recoupable.com, and many endpoint-level servers in openapi.json do as well. If this URL migration is intentional, it should be called out in the PR description and applied consistently; if not, this is an unintended change.

Prompt for AI agents

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

<comment>The API base URL is silently changed from `api.recoupable.com` to `recoup-api.vercel.app` (a Vercel deployment URL), but the PR description claims only navigation structure was updated. This leaves the docs inconsistent — `authentication.mdx` still references `api.recoupable.com`, and many endpoint-level servers in `openapi.json` do as well. If this URL migration is intentional, it should be called out in the PR description and applied consistently; if not, this is an unintended change.</comment>

<file context>
@@ -8,7 +8,7 @@ description: "Get your API key and make your first request to the Recoup API."
 
 ```bash
-https://api.recoupable.com/api
+https://recoup-api.vercel.app/api

</file context>

</details>

<a href="https://www.cubic.dev/action/fix/violation/35af5fdd-bd50-4e61-b93e-edaa2401aa04" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://cubic.dev/buttons/fix-with-cubic-light.svg">
    <img alt="Fix with Cubic" src="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
  </picture>
</a>

[sweetmantech]

Suggested change

	Use the Recoup API to build your record label. Access artist analytics, fan segmentation, AI-powered chat, content creation, and task automation to power your music business.
	Use the Recoup API to build your record label. Generate content, Access artist analytics, Manage your catalogs, AI-powered chat, and task automation to power your music business.

[sweetmantech]

KISS principle

Suggested change

	AI-powered conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.
	Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.

[sweetmantech]

KISS

Suggested change

	AI content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.
	Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.

[sweetmantech]

Move this item first in the list as it's likely the first endpoint they need to hit.