Skip to content

docs: full overhaul — positioning, developer experience, and navigation #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sidneyswift wants to merge 13 commits into
base: main
Choose a base branch
from
Open

docs: full overhaul — positioning, developer experience, and navigation #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
40e8906
docs: full overhaul — positioning, developer experience, and navigation
sidneyswift Mar 30, 2026
241e3a3
docs: remove corny proof point from content creation card
sidneyswift Mar 30, 2026
c5d6855
docs: upgrade homepage with tabs, accordions, and stronger identity
sidneyswift Mar 30, 2026
a9adf99
docs: sharpen identity — deep context edge, "why not ChatGPT"
sidneyswift Mar 30, 2026
e53a0f3
docs: rewrite homepage — exciting, actionable, install-first
sidneyswift Mar 30, 2026
7c12a15
docs: replace ugly ASCII diagrams with Mintlify Steps components
sidneyswift Mar 30, 2026
52c7317
docs: rewrite for agents as primary audience
sidneyswift Mar 30, 2026
35a9b4a
docs: reposition as "The CLI for Music"
sidneyswift Mar 30, 2026
a243402
docs: headline to 'Music Industry Tools for AI Agents'
sidneyswift Mar 30, 2026
95f9e4b
docs: merge Get Started and Integrate into one nav group
sidneyswift Mar 30, 2026
ca33ffe
docs: add llms.txt — complete tool reference for AI agents
sidneyswift Mar 30, 2026
9594033
fix: hyphenate General-purpose per CodeRabbit review
sidneyswift Mar 30, 2026
0377546
remove llms.txt
sidneyswift Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 78 additions & 37 deletions api-reference/introduction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,67 +1,108 @@
---
title: 'Introduction'
description: 'API documentation for the Recoup platform - AI agents for the music industry'
title: 'API Reference'
description: 'Programmatic access to the Recoup platform — agents, artists, content, analytics, and tasks.'
---
Comment on lines 1 to 4
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

api-reference/introduction.mdx should be frontmatter-only, not a custom docs page.

This page currently mixes narrative sections/components inside api-reference/**, and it’s missing an openapi frontmatter entry. Please move narrative content to a non-API-reference guide page (or snippet-driven guide) and keep this file OpenAPI-driven only.

As per coding guidelines, API reference MDX pages should be frontmatter-only and include OpenAPI spec reference in frontmatter (openapi: 'METHOD /path').

Also applies to: 6-108

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/introduction.mdx` around lines 1 - 4, The
api-reference/introduction.mdx file contains narrative MDX content but should be
frontmatter-only and include an openapi entry; remove all body/narrative content
from that file and either move it into a new guide/snippet page (e.g., a
non-api-reference MDX guide) or into a separate docs component, then replace
api-reference/introduction.mdx with only YAML frontmatter including title,
description and an openapi field (e.g., openapi: 'METHOD /path') so the file is
OpenAPI-driven; ensure any links/refs updated where you moved the narrative
content.


## Welcome
The Recoup API is a REST API that gives you programmatic access to everything on the platform. Manage artists, create content, analyze audiences, run scheduled tasks, and integrate with Spotify, YouTube, Instagram, and more.

Welcome to the Recoup API documentation. Recoup is an AI agent platform for the music industry that provides artist analytics, fan segmentation, and AI-powered chat assistants. Build smarter song rollouts, create unforgettable fan experiences, and drive lasting artist growth.
## Base URL

<Card
title="View OpenAPI Specification"
icon="code"
href="https://github.com/sweetmantech/docs/blob/main/api-reference/openapi.json"
>
View the OpenAPI specification file on GitHub
</Card>
```
https://api.recoupable.com/api
```

## Base URL
## Authentication

All API requests should be made to:
All endpoints require an API key in the `x-api-key` header.

```bash
https://api.recoupable.com/api
curl -X GET "https://api.recoupable.com/api/artists" \
-H "x-api-key: YOUR_API_KEY"
```

## Authentication
Get your key from the [API Keys page](https://chat.recoupable.com/keys). Keys are shown once — store them securely.

All API endpoints are authenticated using an API key passed in the `x-api-key` header.
<Warning>
Do not commit API keys to version control or share them publicly.
</Warning>

### Getting Your API Key
## Response Format

1. Navigate to the [API Keys Management Page](https://chat.recoupable.com/keys)
2. Sign in with your account
3. Create a new API key and copy it immediately (it's only shown once)
All endpoints return JSON. Successful responses include a `status` field:

### Using Your API Key
```json
{
"status": "success",
"data": { ... }
}
```

Include your API key in the `x-api-key` header for all requests:
Error responses include a message:

```bash
curl -X GET "https://api.recoupable.com/api/artists?accountId=YOUR_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY"
```json
{
"status": "error",
"error": "Description of what went wrong"
}
```

<Warning>
Keep your API key secure. Do not share it publicly or commit it to version control.
</Warning>
## Rate Limits

## Next Steps
API requests are subject to rate limiting. If you hit a limit, the response will include a `429` status code. Back off and retry with exponential backoff.

## Other Integration Options

The REST API is one of three ways to integrate with Recoup:

| Method | Best For | Docs |
|--------|----------|------|
| **REST API** | Custom integrations, dashboards, automation | You're here |
| **MCP** | AI agents (Claude, Cursor, VS Code) | [MCP Guide](/mcp) |
| **CLI** | Terminal workflows, scripting, CI/CD | [CLI Guide](/cli) |

## Explore

<CardGroup cols={2}>
<Card
title="Quickstart"
icon="rocket"
href="/quickstart"
title="Chat"
icon="comments"
href="/api-reference/chat/chats"
>
Get started with your first API request
AI conversations with artist context.
</Card>
<Card
title="API Reference"
icon="book"
title="Artists"
icon="user"
href="/api-reference/artists/list"
>
Explore all available endpoints
Manage artist profiles and social accounts.
</Card>
<Card
title="Content"
icon="video"
href="/api-reference/content/create"
>
Generate and manage AI-powered content.
</Card>
<Card
title="Tasks"
icon="clock"
href="/api-reference/tasks/get"
>
Schedule and monitor background operations.
</Card>
<Card
title="Spotify"
icon="spotify"
href="/api-reference/spotify/search"
>
Search and analyze Spotify data.
</Card>
<Card
title="Sandboxes"
icon="box"
href="/api-reference/sandboxes/list"
>
Persistent agent execution environments.
</Card>
</CardGroup>
126 changes: 48 additions & 78 deletions authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,111 +1,81 @@
---
title: "Authentication"
description: "How authentication works in the Recoup API — API keys, access tokens, and organization access control."
description: "How to authenticate with the Recoup API, MCP server, and CLI."
---

## Overview
All Recoup services use API keys for authentication. One key works across the REST API, MCP server, and CLI.

Every request to the Recoup API must be authenticated using exactly one of two mechanisms:
## Get Your API Key

| Method | Header | Use case |
|--------|--------|----------|
| API Key | `x-api-key` | Server-to-server integrations |
| Access Token | `Authorization: Bearer <token>` | Frontend apps authenticated via Privy |

Providing both headers in the same request will result in a `401` error.

---

## API Keys

API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are **personal keys** — they are always tied to the account that created them.

### Creating an API Key

1. Navigate to [chat.recoupable.com/keys](https://chat.recoupable.com/keys)
2. Enter a descriptive name (e.g. `"Production Server"`)
3. Click **Create API Key**
1. Go to the [API Keys page](https://chat.recoupable.com/keys)
2. Sign in with your Recoup account
3. Click "Create API Key" and give it a name
4. Copy the key immediately — it's only shown once

<Warning>
Copy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation.
Store your API key securely. Do not commit it to version control, share it publicly, or include it in client-side code.
</Warning>

### Using an API Key
## Using Your Key

### REST API

Pass your key in the `x-api-key` header:

```bash
curl -X GET "https://api.recoupable.com/api/tasks" \
curl -X GET "https://api.recoupable.com/api/artists" \
-H "x-api-key: YOUR_API_KEY"
```

### Access to Organizations

If your account belongs to one or more organizations, your API key can access data across those organizations by passing an `account_id` parameter on supported endpoints. This lets you filter to any account within an organization your key has access to.

- **No org membership** — the key can only access its own account's data
- **Org member** — the key can pass `account_id` to filter to any account within that organization

<Info>
Org membership is determined by the account's [organizations](/api-reference/organizations/list). An account gains access to an org when it is added as a member.
</Info>

---
### MCP Server

Pass your key as a Bearer token in the `Authorization` header:

```json
{
"mcpServers": {
"recoup": {
"url": "https://recoup-api.vercel.app/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```

## Access Tokens (Privy)
### CLI

If you're building a frontend application that authenticates users via [Privy](https://privy.io), you can pass the user's Privy JWT as a Bearer token instead of an API key.
Set the `RECOUP_API_KEY` environment variable:

```bash
curl -X GET "https://api.recoupable.com/api/tasks" \
-H "Authorization: Bearer YOUR_PRIVY_JWT"
export RECOUP_API_KEY=your-api-key
recoup whoami
```

The API validates the token against Privy, extracts the user's email, and resolves it to the corresponding Recoup account. Bearer tokens always authenticate as a personal account — they cannot act on behalf of an organization.
## Key Types

---
### Personal Keys

## How We Verify Access on API Calls
Personal API keys are tied to your account. They can access:

Every authenticated request goes through `validateAuthContext`, which enforces the following access rules:
- Your own data (artists, chats, tasks)
- Data from any organization you belong to (using `account_id` filtering)

### API Key or Bearer Token
### Organization Access

By default, requests access the key owner's own account. When `account_id` is provided:
If your account belongs to an organization, your personal key can access data for other accounts in the same org by passing the `account_id` parameter.

```bash
curl -X GET "https://api.recoupable.com/api/tasks?account_id=OTHER_ACCOUNT_ID" \
-H "x-api-key: YOUR_API_KEY"
```
Request includes account_id override?
├── Same as key owner → Allowed (self-access)
├── Key owner is a member of an org that contains account_id → Allowed
└── No matching org membership → 403 Forbidden
```

Membership is verified by checking the key owner's [organizations](/api-reference/organizations/list) for a record linking the account to the target account's organization.

<Note>
The Recoup internal admin organization has universal access to all accounts.
</Note>
## Admin Authentication

### Organization Access via `organization_id`

Some endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either:

- A **member** of the organization, or
- The **organization account itself**

---
Admin endpoints (`/api/admins/*`) require a Bearer token from Privy authentication, not an API key. These are used by the internal admin dashboard.

## Error Responses

| Status | Cause |
|--------|-------|
| `401` | Missing or invalid credentials, or both `x-api-key` and `Authorization` headers provided |
| `403` | Valid credentials but insufficient access to the requested `account_id` or `organization_id` |

---

## Security Notes

- API keys are **never stored in plaintext** — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database
- **Never include `account_id` in your API key creation request** — the account is always derived from your authenticated credentials
- Rotate keys immediately if compromised via the [API Keys Management Page](https://chat.recoupable.com/keys)
```bash
curl -X GET "https://api.recoupable.com/api/admins/privy" \
-H "Authorization: Bearer PRIVY_ACCESS_TOKEN"
```
Loading