From dc6ed52f36992f2867ecb34367a6da9faabb93e4 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Sun, 25 Oct 2026 16:40:19 -0500 Subject: [PATCH 1/2] Port Workflow trailing-delete reference from Marketing Brings over Marketing c3fc77f, 4d06a2d and d4111d3, written after the docs-site port point (Marketing 40bc362): the bounded DELETE /api/chats/{id}/messages/trailing reference, its shared fixtures and producer test, the Files contributor note, and the inventory pin to the merged api #1157 (e217c79). manifest.json and llms-full.txt are regenerated with pnpm docs:build rather than copied. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 1 + DOCUMENTATION-POLICY.md | 50 ++- content/docs/contracts/example-cases.json | 332 +++++++++++++++++- .../docs/contracts/operation-inventory.json | 4 +- content/docs/manifest.json | 2 +- .../api-reference/openapi/research.json | 113 +++++- content/docs/source/llms-full.txt | 129 ++++++- scripts/build_published_docs_record.py | 8 + scripts/build_response_contracts.py | 10 +- scripts/test_chat_trailing_contracts.py | 38 ++ 10 files changed, 653 insertions(+), 34 deletions(-) create mode 100644 scripts/test_chat_trailing_contracts.py diff --git a/AGENTS.md b/AGENTS.md index 7cc4f12..f9f5745 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,6 +51,7 @@ python3 scripts/refresh-contract-inventory.py --api \nKeep your API key secure. Do not share it publicly or commit it to version control.\n\n\n## Get Started\n\n\n \n Verify your email and obtain a separate REST API key.\n \n \n Get your API key and make your first request in minutes.\n \n \n Install and use the Recoup CLI to interact with the platform from your terminal.\n \n \n Connect Claude to Recoup through MCP OAuth, then add optional workflow skills.\n \n \n Connect Recoup to AI assistants via the Model Context Protocol.\n \n\n\n## API Sections\n\nThe API includes these major sections. Use these links to jump to the right area.\n\n\n \n Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements.\n \n \n Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.\n \n \n Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.\n \n \n Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.\n \n \n Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.\n \n \n Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools.\n \n \n Hosted listening pages, embeddable players, event reporting and fan connections.\n \n\n\n## Agents\n\n\n \n Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.\n \n \n API key authentication, account-scoped access, and organization-level permissions.\n \n\n\n## Quick Reference for LLMs\n\nIf you are an LLM navigating these docs, here is a summary of the endpoint structure:\n\n- **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile)\n- **`/api/research/*`** — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits.\n- **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)\n- **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact)\n- **Songs and catalogs** — Read songs with `/api/songs`; import songs into an accessible catalog with `/api/catalogs/songs`. Analysis, catalog management and catalog-song reads/deletes have their own references. [Standalone song creation is not available](/api-reference/songs/create).\n- **`/api/tasks/*`** — Task automation (get, create, update, delete, runs)\n- **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album)\n- **`/api/instagram/*`** — Instagram (comments, profiles)\n- **`/api/x/*`** — X/Twitter (search, trends)\n- **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect)\n- **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist)\n- **`/api/organizations/*`** — Organizations (list, create, add-artist)\n- **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload)\n- **`/api/players/*`** — Release Players (list, create, update, activity and fans)\n- **`/api/content-agent/*`** — Content agent webhooks (webhook, callback)\n- **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required\n\nBase URL: `https://api.recoupable.dev/api`\n\n[OpenAPI Specification](https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi)\n\n## Need Help?\n\n\n Reach out to our team at agent@recoupable.dev for assistance with the Recoup API.\n\n","headings":[{"title":"Connect your account","id":"connect-your-account"},{"title":"What is Recoup?","id":"what-is-recoup"},{"title":"Platform base URL","id":"platform-base-url"},{"title":"Authentication","id":"authentication"},{"title":"Get Started","id":"get-started"},{"title":"API Sections","id":"api-sections"},{"title":"Agents","id":"agents"},{"title":"Quick Reference for LLMs","id":"quick-reference-for-llms"},{"title":"Need Help?","id":"need-help"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n }, {Card, CardGroup, Warning} = _components;\n if (!Card) _missingMdxReference(\"Card\", true);\n if (!CardGroup) _missingMdxReference(\"CardGroup\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"These guides cover the authenticated music-platform API. For anonymous search,\\nreading, and website tools, use the separate \", _jsx(_components.a, {\n href: \"/public-website-api\",\n children: \"public website API\"\n }), \"\\nand its \", _jsx(_components.a, {\n href: \"https://recoupable.dev/openapi.json\",\n children: \"OpenAPI specification\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"connect-your-account\",\n children: \"Connect your account\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For an AI host, start with \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \": sign in to your real account,\\napprove the intended scope and verify access with a read. For REST integrations,\\ncreate an API key in your \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"account settings\"\n }), \", or\\nfollow the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"verified email/PIN flow\"\n }), \". Keep credentials in a secret facility.\\nAn empty roster can be valid; do not create a disposable account to recover access.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-is-recoup\",\n children: \"What is Recoup?\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"platform-base-url\",\n children: \"Platform base URL\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Platform API requests should be made to:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"https://api.recoupable.dev/api\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication\",\n children: \"Authentication\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Most API endpoints are authenticated using an API key passed in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header. The only exceptions are the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"agent onboarding\"\n }), \" endpoints — \", _jsx(_components.a, {\n href: \"/api-reference/agents/signup\",\n children: _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/agents/verify\",\n children: _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n })\n }), \" — which are intentionally unauthenticated so agents can obtain their first API key.\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys Management Page\"\n })]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Sign in with your account\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Create a new API key and copy it immediately (it's only shown once)\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/artists?accountId=YOUR_ACCOUNT_ID\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Keep your API key secure. Do not share it publicly or commit it to version control.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"get-started\",\n children: \"Get Started\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Agent Signup\",\n icon: \"user-plus\",\n href: \"/agents\",\n children: _jsx(_components.p, {\n children: \"Verify your email and obtain a separate REST API key.\"\n })\n }), _jsx(Card, {\n title: \"Quickstart\",\n icon: \"rocket\",\n href: \"/quickstart\",\n children: _jsx(_components.p, {\n children: \"Get your API key and make your first request in minutes.\"\n })\n }), _jsx(Card, {\n title: \"CLI\",\n icon: \"terminal\",\n href: \"/cli\",\n children: _jsx(_components.p, {\n children: \"Install and use the Recoup CLI to interact with the platform from your terminal.\"\n })\n }), _jsx(Card, {\n title: \"Claude\",\n icon: \"sparkles\",\n href: \"/claude\",\n children: _jsx(_components.p, {\n children: \"Connect Claude to Recoup through MCP OAuth, then add optional workflow skills.\"\n })\n }), _jsx(Card, {\n title: \"MCP Server\",\n icon: \"plug\",\n href: \"/mcp\",\n children: _jsx(_components.p, {\n children: \"Connect Recoup to AI assistants via the Model Context Protocol.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"api-sections\",\n children: \"API Sections\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The API includes these major sections. Use these links to jump to the right area.\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Research\",\n icon: \"magnifying-glass-chart\",\n href: \"/api-reference/research/search\",\n children: _jsx(_components.p, {\n children: \"Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements.\"\n })\n }), _jsx(Card, {\n title: \"Content Creation\",\n icon: \"wand-magic-sparkles\",\n href: \"/api-reference/content/create\",\n children: _jsx(_components.p, {\n children: \"Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.\"\n })\n }), _jsx(Card, {\n title: \"Chat\",\n icon: \"comments\",\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.p, {\n children: \"Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.\"\n })\n }), _jsx(Card, {\n title: \"Social Media\",\n icon: \"share-nodes\",\n href: \"/api-reference/connectors/list\",\n children: _jsx(_components.p, {\n children: \"Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.\"\n })\n }), _jsx(Card, {\n title: \"Releases\",\n icon: \"music\",\n href: \"/api-reference/songs/songs\",\n children: _jsx(_components.p, {\n children: \"Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.\"\n })\n }), _jsx(Card, {\n title: \"Accounts\",\n icon: \"building\",\n href: \"/api-reference/pulses/update\",\n children: _jsx(_components.p, {\n children: \"Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools.\"\n })\n }), _jsx(Card, {\n title: \"Release Players\",\n icon: \"play\",\n href: \"/essentials/release-player\",\n children: _jsx(_components.p, {\n children: \"Hosted listening pages, embeddable players, event reporting and fan connections.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"agents\",\n children: \"Agents\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Content Agent\",\n icon: \"robot\",\n href: \"/content-agent\",\n children: _jsx(_components.p, {\n children: \"Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.\"\n })\n }), _jsx(Card, {\n title: \"Authentication\",\n icon: \"key\",\n href: \"/authentication\",\n children: _jsx(_components.p, {\n children: \"API key authentication, account-scoped access, and organization-level permissions.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"quick-reference-for-llms\",\n children: \"Quick Reference for LLMs\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you are an LLM navigating these docs, here is a summary of the endpoint structure:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/artists/*\"\n })\n }), \" — Artist management (list, create, socials, socials-scrape, profile)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/research/*\"\n })\n }), \" — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/content/*\"\n })\n }), \" — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/chat/*\"\n })\n }), \" — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Songs and catalogs\"\n }), \" — Read songs with \", _jsx(_components.code, {\n children: \"/api/songs\"\n }), \"; import songs into an accessible catalog with \", _jsx(_components.code, {\n children: \"/api/catalogs/songs\"\n }), \". Analysis, catalog management and catalog-song reads/deletes have their own references. \", _jsx(_components.a, {\n href: \"/api-reference/songs/create\",\n children: \"Standalone song creation is not available\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/tasks/*\"\n })\n }), \" — Task automation (get, create, update, delete, runs)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/spotify/*\"\n })\n }), \" — Spotify (search, artist, artist-albums, artist-top-tracks, album)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/instagram/*\"\n })\n }), \" — Instagram (comments, profiles)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/x/*\"\n })\n }), \" — X/Twitter (search, trends)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/connectors/*\"\n })\n }), \" — OAuth connectors (list, authorize, disconnect)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/accounts/*\"\n })\n }), \" — Accounts (get, id, create, update, add-artist)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/organizations/*\"\n })\n }), \" — Organizations (list, create, add-artist)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/sandboxes/*\"\n })\n }), \" — Sandboxes (list, create, snapshot, delete, setup, file, upload)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/players/*\"\n })\n }), \" — Release Players (list, create, update, activity and fans)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/content-agent/*\"\n })\n }), \" — Content agent webhooks (webhook, callback)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/agents/*\"\n })\n }), \" — Agent onboarding (signup, verify) — no auth required\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Base URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/api\"\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi\",\n children: \"OpenAPI Specification\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"need-help\",\n children: \"Need Help?\"\n }), \"\\n\", _jsx(Card, {\n title: \"Contact Support\",\n icon: \"envelope\",\n href: \"mailto:agent@recoupable.dev\",\n children: _jsxs(_components.p, {\n children: [\"Reach out to our team at \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \" for assistance with the Recoup API.\"]\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Recoup API Documentation Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints. Quickstart Getting started These guides cover the authenticated music-platform API. For anonymous search, reading, and website tools, use the separate [public website API](/public-website-api) and its [OpenAPI specification](https://recoupable.dev/openapi.json). ## Connect your account For an AI host, start with [MCP OAuth](/mcp-oauth): sign in to your real account, approve the intended scope and verify access with a read. For REST integrations, create an API key in your [account settings](https://chat.recoupable.dev/keys), or follow the [verified email/PIN flow](/agents). Keep credentials in a secret facility. An empty roster can be valid; do not create a disposable account to recover access. ## What is Recoup? Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools. This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. ## Platform base URL Platform API requests should be made to: ## Authentication Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key. 1. Navigate to the [API Keys Management Page](https://chat.recoupable.dev/keys) 2. Sign in with your account 3. Create a new API key and copy it immediately (it's only shown once) Keep your API key secure. Do not share it publicly or commit it to version control. ## Get Started Verify your email and obtain a separate REST API key. Get your API key and make your first request in minutes. Install and use the Recoup CLI to interact with the platform from your terminal. Connect Claude to Recoup through MCP OAuth, then add optional workflow skills. Connect Recoup to AI assistants via the Model Context Protocol. ## API Sections The API includes these major sections. Use these links to jump to the right area. Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements. Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs. Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history. Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors. Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation. Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools. Hosted listening pages, embeddable players, event reporting and fan connections. ## Agents Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically. API key authentication, account-scoped access, and organization-level permissions. ## Quick Reference for LLMs If you are an LLM navigating these docs, here is a summary of the endpoint structure: - **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile) - **`/api/research/*`** — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits. - **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate) - **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact) - **Songs and catalogs** — Read songs with `/api/songs`; import songs into an accessible catalog with `/api/catalogs/songs`. Analysis, catalog management and catalog-song reads/deletes have their own references. [Standalone song creation is not available](/api-reference/songs/create). - **`/api/tasks/*`** — Task automation (get, create, update, delete, runs) - **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album) - **`/api/instagram/*`** — Instagram (comments, profiles) - **`/api/x/*`** — X/Twitter (search, trends) - **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect) - **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist) - **`/api/organizations/*`** — Organizations (list, create, add-artist) - **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload) - **`/api/players/*`** — Release Players (list, create, update, activity and fans) - **`/api/content-agent/*`** — Content agent webhooks (webhook, callback) - **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required Base URL: `https://api.recoupable.dev/api` [OpenAPI Specification](https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi) ## Need Help? Reach out to our team at agent@recoupable.dev for assistance with the Recoup API. "},{"slug":"quickstart","title":"Quickstart","description":"Connect your real account and make your first authenticated request.","category":"Quickstart","group":"Getting started","source":"quickstart.mdx","body":"## Connect first\n\nUse [MCP OAuth](/mcp-oauth) for a supported AI host. For the REST examples below,\ncreate a personal API key in [account settings](https://chat.recoupable.dev/keys)\nor follow the [Agents email verification guide](/agents). Store the key as\n`RECOUP_API_KEY` through your secret facility or an approved environment file.\nNever paste credentials into agent instructions or create a disposable account\nto access an existing customer's data.\n\nVerify the REST credential before continuing:\n\n```bash\ncurl --fail-with-body -sS -H \"x-api-key: $RECOUP_API_KEY\" \\\n https://api.recoupable.dev/api/accounts/id\n```\n\n## Base URL\n\nFor a language client, use the [Recoup SDK guide](/sdks). It includes the\npublished Go package, Python source installation, and the Node CLI.\n\nAll API requests should be made to:\n\n```bash\nhttps://api.recoupable.dev/api\n```\n\n## Your First Request\n\nOnce you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks:\n\n\n\n```bash cURL\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n```python Python\nimport requests\n\nheaders = {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\"\n}\n\nresponse = requests.get(\n \"https://api.recoupable.dev/api/tasks\",\n headers=headers\n)\nprint(response.json())\n```\n\n```javascript JavaScript\nconst response = await fetch(\"https://api.recoupable.dev/api/tasks\", {\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\",\n },\n});\nconst data = await response.json();\nconsole.log(data);\n```\n\n```typescript TypeScript\ninterface Task {\n id: string;\n title: string;\n prompt: string;\n schedule: string;\n account_id: string;\n artist_account_id: string;\n enabled: boolean;\n}\n\ninterface TasksResponse {\n status: \"success\" | \"error\";\n tasks: Task[];\n}\n\nconst response = await fetch(\"https://api.recoupable.dev/api/tasks\", {\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\",\n },\n});\nconst data: TasksResponse = await response.json();\nconsole.log(data.tasks);\n```\n\n\n\n**Example Response:**\n\n```json\n{\n \"status\": \"success\",\n \"tasks\": [\n {\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"title\": \"Daily Fan Report\",\n \"prompt\": \"Generate a summary of new fans from the past 24 hours\",\n \"schedule\": \"0 9 * * *\",\n \"account_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"artist_account_id\": \"987fcdeb-51a2-3b4c-d5e6-789012345678\",\n \"enabled\": true\n }\n ]\n}\n```\n\n\nFor full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get).\n\n\n## Prefer the dashboard?\n\nIf you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:\n\n1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.dev/keys)\n2. Sign in with your account\n3. Enter a descriptive name (e.g. \"Production Server\")\n4. Click **Create API Key**\n\n\nCopy and securely store your API key immediately — it will only be shown once.\n\n\n## Next Steps\n\nWith your API key ready, you can now:\n\n\n \n Fetch artists' social accounts and follower counts.\n \n \n Access fan data across all connected social platforms.\n \n \n Build AI-powered conversations with artist context.\n \n \n Schedule and automate recurring tasks.\n \n\n\n## Support\n\nIf you need help or have questions about the API, please contact our support team at [agent@recoupable.dev](mailto:agent@recoupable.dev).\n","headings":[{"title":"Connect first","id":"connect-first"},{"title":"Base URL","id":"base-url"},{"title":"Your First Request","id":"your-first-request"},{"title":"Prefer the dashboard?","id":"prefer-the-dashboard"},{"title":"Next Steps","id":"next-steps"},{"title":"Support","id":"support"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ...props.components\n }, {Card, CardGroup, CodeGroup, Info, Warning} = _components;\n if (!Card) _missingMdxReference(\"Card\", true);\n if (!CardGroup) _missingMdxReference(\"CardGroup\", true);\n if (!CodeGroup) _missingMdxReference(\"CodeGroup\", true);\n if (!Info) _missingMdxReference(\"Info\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"connect-first\",\n children: \"Connect first\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for a supported AI host. For the REST examples below,\\ncreate a personal API key in \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"account settings\"\n }), \"\\nor follow the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents email verification guide\"\n }), \". Store the key as\\n\", _jsx(_components.code, {\n children: \"RECOUP_API_KEY\"\n }), \" through your secret facility or an approved environment file.\\nNever paste credentials into agent instructions or create a disposable account\\nto access an existing customer's data.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Verify the REST credential before continuing:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl --fail-with-body -sS -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n https://api.recoupable.dev/api/accounts/id\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"base-url\",\n children: \"Base URL\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a language client, use the \", _jsx(_components.a, {\n href: \"/sdks\",\n children: \"Recoup SDK guide\"\n }), \". It includes the\\npublished Go package, Python source installation, and the Node CLI.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"All API requests should be made to:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"https://api.recoupable.dev/api\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"your-first-request\",\n children: \"Your First Request\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once you have an API key, include it in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header on every request. Here's a simple call that retrieves your scheduled tasks:\"]\n }), \"\\n\", _jsxs(CodeGroup, {\n children: [_jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-python\",\n children: \"import requests\\n\\nheaders = {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\"\\n}\\n\\nresponse = requests.get(\\n \\\"https://api.recoupable.dev/api/tasks\\\",\\n headers=headers\\n)\\nprint(response.json())\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-javascript\",\n children: \"const response = await fetch(\\\"https://api.recoupable.dev/api/tasks\\\", {\\n headers: {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\",\\n },\\n});\\nconst data = await response.json();\\nconsole.log(data);\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-typescript\",\n children: \"interface Task {\\n id: string;\\n title: string;\\n prompt: string;\\n schedule: string;\\n account_id: string;\\n artist_account_id: string;\\n enabled: boolean;\\n}\\n\\ninterface TasksResponse {\\n status: \\\"success\\\" | \\\"error\\\";\\n tasks: Task[];\\n}\\n\\nconst response = await fetch(\\\"https://api.recoupable.dev/api/tasks\\\", {\\n headers: {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\",\\n },\\n});\\nconst data: TasksResponse = await response.json();\\nconsole.log(data.tasks);\\n\"\n })\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"Example Response:\"\n })\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"status\\\": \\\"success\\\",\\n \\\"tasks\\\": [\\n {\\n \\\"id\\\": \\\"550e8400-e29b-41d4-a716-446655440000\\\",\\n \\\"title\\\": \\\"Daily Fan Report\\\",\\n \\\"prompt\\\": \\\"Generate a summary of new fans from the past 24 hours\\\",\\n \\\"schedule\\\": \\\"0 9 * * *\\\",\\n \\\"account_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\\n \\\"artist_account_id\\\": \\\"987fcdeb-51a2-3b4c-d5e6-789012345678\\\",\\n \\\"enabled\\\": true\\n }\\n ]\\n}\\n\"\n })\n }), \"\\n\", _jsx(Info, {\n children: _jsxs(_components.p, {\n children: [\"For full documentation on the Tasks API including filtering options, see the \", _jsx(_components.a, {\n href: \"/api-reference/tasks/get\",\n children: \"Tasks API Reference\"\n }), \".\"]\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"prefer-the-dashboard\",\n children: \"Prefer the dashboard?\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"Recoup API Keys Management Page\"\n })]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Sign in with your account\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Enter a descriptive name (e.g. \\\"Production Server\\\")\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Click \", _jsx(_components.strong, {\n children: \"Create API Key\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Copy and securely store your API key immediately — it will only be shown once.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"next-steps\",\n children: \"Next Steps\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"With your API key ready, you can now:\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Artist Data\",\n icon: \"user\",\n href: \"/api-reference/artists/socials\",\n children: _jsx(_components.p, {\n children: \"Fetch artists' social accounts and follower counts.\"\n })\n }), _jsx(Card, {\n title: \"Fan Analytics\",\n icon: \"users\",\n href: \"/api-reference/fans/get\",\n children: _jsx(_components.p, {\n children: \"Access fan data across all connected social platforms.\"\n })\n }), _jsx(Card, {\n title: \"Chat API\",\n icon: \"comments\",\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.p, {\n children: \"Build AI-powered conversations with artist context.\"\n })\n }), _jsx(Card, {\n title: \"Task Management\",\n icon: \"list-check\",\n href: \"/api-reference/tasks/get\",\n children: _jsx(_components.p, {\n children: \"Schedule and automate recurring tasks.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"support\",\n children: \"Support\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you need help or have questions about the API, please contact our support team at \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Quickstart Connect your real account and make your first authenticated request. Quickstart Getting started ## Connect first Use [MCP OAuth](/mcp-oauth) for a supported AI host. For the REST examples below, create a personal API key in [account settings](https://chat.recoupable.dev/keys) or follow the [Agents email verification guide](/agents). Store the key as `RECOUP_API_KEY` through your secret facility or an approved environment file. Never paste credentials into agent instructions or create a disposable account to access an existing customer's data. Verify the REST credential before continuing: ## Base URL For a language client, use the [Recoup SDK guide](/sdks). It includes the published Go package, Python source installation, and the Node CLI. All API requests should be made to: ## Your First Request Once you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks: **Example Response:** For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). ## Prefer the dashboard? If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint: 1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.dev/keys) 2. Sign in with your account 3. Enter a descriptive name (e.g. \"Production Server\") 4. Click **Create API Key** Copy and securely store your API key immediately — it will only be shown once. ## Next Steps With your API key ready, you can now: Fetch artists' social accounts and follower counts. Access fan data across all connected social platforms. Build AI-powered conversations with artist context. Schedule and automate recurring tasks. ## Support If you need help or have questions about the API, please contact our support team at [agent@recoupable.dev](mailto:agent@recoupable.dev). "},{"slug":"sdks","title":"Recoup SDKs: Go and Python clients for the music API","description":"Install the official Recoup Python SDK from PyPI, the Go SDK from its module registry, and the Node CLI from npm. Includes authentication, response handling, and package links.","category":"Quickstart","group":"Getting started","source":"sdks.mdx","body":"Use the official Recoup clients to call the platform's JSON API from your application.\nBoth SDKs support an API key or an existing Bearer token, bounded responses,\nstructured HTTP errors, and an account-identity helper. Their licenses are MIT.\n\n## Packages\n\n| Language | Package | Availability |\n| --- | --- | --- |\n| Go 1.23+ | [github.com/recoupable/marketing/sdk/go](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) | Version `v0.1.0` is published and indexed. |\n| Python 3.10+ | [recoupable on PyPI](https://pypi.org/project/recoupable/0.1.0/) | Version `0.1.0` is published. |\n| Node.js CLI | [@recoupable/cli on npm](https://www.npmjs.com/package/@recoupable/cli) | The terminal client is published. See the [CLI guide](/cli) for supported commands. |\n\nThe Go and Python SDKs handle JSON endpoints. They do not implement streaming,\nmultipart uploads, OAuth login, automatic pagination, or generated methods for\nevery endpoint. Use each endpoint's reference to check its availability, required\npermissions, request shape, and response type. A package installation does not\ngrant account access.\n\n## Go\n\nInstall the published version:\n\n```sh\ngo get github.com/recoupable/marketing/sdk/go@v0.1.0\n```\n\nRead an existing API key from your application's secret environment:\n\n```go\npackage main\n\nimport (\n \"context\"\n \"log\"\n \"os\"\n\n recoupable \"github.com/recoupable/marketing/sdk/go\"\n)\n\nfunc main() {\n client, err := recoupable.New(recoupable.Options{\n APIKey: os.Getenv(\"RECOUP_API_KEY\"),\n })\n if err != nil { log.Fatal(err) }\n account, err := client.GetAccountID(context.Background())\n if err != nil { log.Fatal(err) }\n log.Print(account.AccountID)\n}\n```\n\nUse `Options{AccessToken: ...}` for an existing Bearer token. The generic\n`Request(ctx, method, path, query, body, out)` method supports other documented\nJSON endpoints. Pass query parameters as `url.Values` and an unencoded `/api/` path.\nSee the [Go package reference](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0)\nfor method signatures and error types.\n\n## Python\n\nInstall the published version:\n\n```sh\npython -m pip install recoupable==0.1.0\n```\n\n```python\nimport os\nfrom recoupable import Client\n\nclient = Client(api_key=os.environ[\"RECOUP_API_KEY\"])\naccount = client.get_account_id()\nprint(account[\"accountId\"])\n```\n\nUse `Client(access_token=...)` for an existing Bearer token. The generic\n`request(method, path, query=..., body=...)` method returns decoded JSON or `None`\nfor an empty successful response. Read the [Python client reference](https://github.com/recoupable/marketing/tree/main/sdk/python)\nfor configuration and error handling.\n\n## Authentication and response handling\n\nSupply exactly one credential. Create a key in [Recoup account settings](https://chat.recoupable.dev/keys),\nor follow the [authentication guide](/authentication) for supported access methods.\nThe default API origin is `https://api.recoupable.dev`. A custom HTTPS origin is\nan explicit destination for your credential. Redirects are not followed.\n\nBoth clients cap responses at 16 MiB by default and accept empty successful\nresponses. Python uses a 30-second timeout per blocking socket operation; Go\nuses a 30-second total request deadline and supports earlier context deadlines.\nThese limits are configurable.\n\nHTTP errors retain their status and headers, including `Retry-After`; oversized\nerror bodies are truncated. Inspect the error's fields when deciding what to do.\nError messages omit credentials and response bodies. Treat a response body as\npotentially private if you log it.\n\nThe SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent\nrequest on a reused connection. A transport failure can occur after a write has\ncompleted; check the operation's outcome before repeating it.\n","headings":[{"title":"Packages","id":"packages"},{"title":"Go","id":"go"},{"title":"Python","id":"python"},{"title":"Authentication and response handling","id":"authentication-and-response-handling"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Use the official Recoup clients to call the platform's JSON API from your application.\\nBoth SDKs support an API key or an existing Bearer token, bounded responses,\\nstructured HTTP errors, and an account-identity helper. Their licenses are MIT.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"packages\",\n children: \"Packages\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Language\"\n }), _jsx(_components.th, {\n children: \"Package\"\n }), _jsx(_components.th, {\n children: \"Availability\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Go 1.23+\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0\",\n children: \"github.com/recoupable/marketing/sdk/go\"\n })\n }), _jsxs(_components.td, {\n children: [\"Version \", _jsx(_components.code, {\n children: \"v0.1.0\"\n }), \" is published and indexed.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Python 3.10+\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://pypi.org/project/recoupable/0.1.0/\",\n children: \"recoupable on PyPI\"\n })\n }), _jsxs(_components.td, {\n children: [\"Version \", _jsx(_components.code, {\n children: \"0.1.0\"\n }), \" is published.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Node.js CLI\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://www.npmjs.com/package/@recoupable/cli\",\n children: \"@recoupable/cli on npm\"\n })\n }), _jsxs(_components.td, {\n children: [\"The terminal client is published. See the \", _jsx(_components.a, {\n href: \"/cli\",\n children: \"CLI guide\"\n }), \" for supported commands.\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The Go and Python SDKs handle JSON endpoints. They do not implement streaming,\\nmultipart uploads, OAuth login, automatic pagination, or generated methods for\\nevery endpoint. Use each endpoint's reference to check its availability, required\\npermissions, request shape, and response type. A package installation does not\\ngrant account access.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"go\",\n children: \"Go\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Install the published version:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-sh\",\n children: \"go get github.com/recoupable/marketing/sdk/go@v0.1.0\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Read an existing API key from your application's secret environment:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-go\",\n children: \"package main\\n\\nimport (\\n \\\"context\\\"\\n \\\"log\\\"\\n \\\"os\\\"\\n\\n recoupable \\\"github.com/recoupable/marketing/sdk/go\\\"\\n)\\n\\nfunc main() {\\n client, err := recoupable.New(recoupable.Options{\\n APIKey: os.Getenv(\\\"RECOUP_API_KEY\\\"),\\n })\\n if err != nil { log.Fatal(err) }\\n account, err := client.GetAccountID(context.Background())\\n if err != nil { log.Fatal(err) }\\n log.Print(account.AccountID)\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"Options{AccessToken: ...}\"\n }), \" for an existing Bearer token. The generic\\n\", _jsx(_components.code, {\n children: \"Request(ctx, method, path, query, body, out)\"\n }), \" method supports other documented\\nJSON endpoints. Pass query parameters as \", _jsx(_components.code, {\n children: \"url.Values\"\n }), \" and an unencoded \", _jsx(_components.code, {\n children: \"/api/\"\n }), \" path.\\nSee the \", _jsx(_components.a, {\n href: \"https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0\",\n children: \"Go package reference\"\n }), \"\\nfor method signatures and error types.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"python\",\n children: \"Python\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Install the published version:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-sh\",\n children: \"python -m pip install recoupable==0.1.0\\n\"\n })\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-python\",\n children: \"import os\\nfrom recoupable import Client\\n\\nclient = Client(api_key=os.environ[\\\"RECOUP_API_KEY\\\"])\\naccount = client.get_account_id()\\nprint(account[\\\"accountId\\\"])\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"Client(access_token=...)\"\n }), \" for an existing Bearer token. The generic\\n\", _jsx(_components.code, {\n children: \"request(method, path, query=..., body=...)\"\n }), \" method returns decoded JSON or \", _jsx(_components.code, {\n children: \"None\"\n }), \"\\nfor an empty successful response. Read the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketing/tree/main/sdk/python\",\n children: \"Python client reference\"\n }), \"\\nfor configuration and error handling.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication-and-response-handling\",\n children: \"Authentication and response handling\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Supply exactly one credential. Create a key in \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"Recoup account settings\"\n }), \",\\nor follow the \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"authentication guide\"\n }), \" for supported access methods.\\nThe default API origin is \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \". A custom HTTPS origin is\\nan explicit destination for your credential. Redirects are not followed.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Both clients cap responses at 16 MiB by default and accept empty successful\\nresponses. Python uses a 30-second timeout per blocking socket operation; Go\\nuses a 30-second total request deadline and supports earlier context deadlines.\\nThese limits are configurable.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP errors retain their status and headers, including \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \"; oversized\\nerror bodies are truncated. Inspect the error's fields when deciding what to do.\\nError messages omit credentials and response bodies. Treat a response body as\\npotentially private if you log it.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent\\nrequest on a reused connection. A transport failure can occur after a write has\\ncompleted; check the operation's outcome before repeating it.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Recoup SDKs: Go and Python clients for the music API Install the official Recoup Python SDK from PyPI, the Go SDK from its module registry, and the Node CLI from npm. Includes authentication, response handling, and package links. Quickstart Getting started Use the official Recoup clients to call the platform's JSON API from your application. Both SDKs support an API key or an existing Bearer token, bounded responses, structured HTTP errors, and an account-identity helper. Their licenses are MIT. ## Packages | Language | Package | Availability | | --- | --- | --- | | Go 1.23+ | [github.com/recoupable/marketing/sdk/go](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) | Version `v0.1.0` is published and indexed. | | Python 3.10+ | [recoupable on PyPI](https://pypi.org/project/recoupable/0.1.0/) | Version `0.1.0` is published. | | Node.js CLI | [@recoupable/cli on npm](https://www.npmjs.com/package/@recoupable/cli) | The terminal client is published. See the [CLI guide](/cli) for supported commands. | The Go and Python SDKs handle JSON endpoints. They do not implement streaming, multipart uploads, OAuth login, automatic pagination, or generated methods for every endpoint. Use each endpoint's reference to check its availability, required permissions, request shape, and response type. A package installation does not grant account access. ## Go Install the published version: Read an existing API key from your application's secret environment: Use `Options{AccessToken: ...}` for an existing Bearer token. The generic `Request(ctx, method, path, query, body, out)` method supports other documented JSON endpoints. Pass query parameters as `url.Values` and an unencoded `/api/` path. See the [Go package reference](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) for method signatures and error types. ## Python Install the published version: Use `Client(access_token=...)` for an existing Bearer token. The generic `request(method, path, query=..., body=...)` method returns decoded JSON or `None` for an empty successful response. Read the [Python client reference](https://github.com/recoupable/marketing/tree/main/sdk/python) for configuration and error handling. ## Authentication and response handling Supply exactly one credential. Create a key in [Recoup account settings](https://chat.recoupable.dev/keys), or follow the [authentication guide](/authentication) for supported access methods. The default API origin is `https://api.recoupable.dev`. A custom HTTPS origin is an explicit destination for your credential. Redirects are not followed. Both clients cap responses at 16 MiB by default and accept empty successful responses. Python uses a 30-second timeout per blocking socket operation; Go uses a 30-second total request deadline and supports earlier context deadlines. These limits are configurable. HTTP errors retain their status and headers, including `Retry-After`; oversized error bodies are truncated. Inspect the error's fields when deciding what to do. Error messages omit credentials and response bodies. Treat a response body as potentially private if you log it. The SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent request on a reused connection. A transport failure can occur after a write has completed; check the operation's outcome before repeating it. "},{"slug":"public-website-api","title":"Recoup public website API","description":"Search and read public Recoup content, use bounded website tools, and batch independent operations without an account.","category":"Quickstart","group":"Getting started","source":"public-website-api.mdx","body":"The public website API searches and reads published Recoup pages, calculates\nworkflow scenarios from supplied inputs, and prepares unsubmitted project briefs.\nIt is free and requires no account, API key, or payment method.\n\nMusic-platform operations use the separate authenticated\n[platform API](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot\nread account data, manage artists, publish content, or send an inquiry.\n\n## Specification and first request\n\nThe [website OpenAPI specification](https://recoupable.dev/openapi.json) defines\nevery HTTP operation, its input and response schemas, and typed errors.\nThe [API catalog](https://recoupable.dev/.well-known/api-catalog) links this\nspecification alongside the platform specifications.\n\n```bash\ncurl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'\n```\n\nThe response contains `results`, `total`, and `nextCursor`. An empty result list\nis a successful search. Use a returned content ID with\n`GET /agent-api/v1/read?id=CONTENT_ID`; continue at the returned `nextOffset`\nuntil it is null. The reader accepts registry IDs, never arbitrary private URLs.\n\nUse `GET /agent-api/v1/markdown?path=/blog` for a complete public page as Markdown.\nThe [website agent guide](https://recoupable.dev/agents.md) explains all five tools,\npagination, draft behavior, and the browser interface.\n\n## Batch independent operations\n\n`POST https://recoupable.dev/agent-api/v1/batch` accepts one to ten operations.\n\n```bash\ncurl 'https://recoupable.dev/agent-api/v1/batch' \\\n -H 'Content-Type: application/json' \\\n --data '{\"operations\":[{\"name\":\"search_recoup\",\"arguments\":{\"query\":\"royalty\",\"limit\":1}},{\"name\":\"read_recoup_page\",\"arguments\":{\"id\":\"page:/services\",\"maxLength\":500}}]}'\n```\n\nThe `results` array preserves input order. Each entry has its own `status` and\n`result` or `error`. An individual failure does not cancel successful reads.\nThe batch is not a transaction. Its entire request body must fit within 16 KB.\nDraft operations return `submitted: false`; nothing is sent or saved as a lead.\n\n## Hosted quotas and errors\n\nHTTP and MCP website tools share a limit of 120 requests per 60-second fixed\nwindow, per IP address and serving region. A batch counts as one request.\n`RateLimit-Limit` and `RateLimit-Policy` describe that enforced policy on live\nresponses. Regional counters are not a global account allowance.\n\nOn HTTP 429, wait the `Retry-After` duration before retrying. HTTP 503 means the\nrequest could not be completed; retry later. JSON tool endpoints return structured\nerrors with a code, message, and recovery guidance for invalid arguments or missing content.\nLocal development does not enforce the hosted quota.\n\n## Versioning and deprecation\n\nWebsite HTTP operations use `/agent-api/v1`. Additive response fields are\ncompatible; clients should ignore fields they do not recognize. Incompatible\nchanges require a new major URL version.\n\nNo v1 deprecation or sunset is scheduled. A future retirement will be announced\nin the [agent guide](https://recoupable.dev/agents.md) with a migration guide and\n`Deprecation`, `Sunset`, and `Link` response headers when dates are known.\nThis policy applies to the public website API.\n\n## MCP connection\n\nConnect to `https://recoupable.dev/mcp` over Streamable HTTP without credentials.\nThe [public manifest](https://recoupable.dev/.well-known/mcp.json) identifies\nthe server. Its five tools share the website HTTP capabilities and hosted quota.\nTo use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead.\n","headings":[{"title":"Specification and first request","id":"specification-and-first-request"},{"title":"Batch independent operations","id":"batch-independent-operations"},{"title":"Hosted quotas and errors","id":"hosted-quotas-and-errors"},{"title":"Versioning and deprecation","id":"versioning-and-deprecation"},{"title":"MCP connection","id":"mcp-connection"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"The public website API searches and reads published Recoup pages, calculates\\nworkflow scenarios from supplied inputs, and prepares unsubmitted project briefs.\\nIt is free and requires no account, API key, or payment method.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Music-platform operations use the separate authenticated\\n\", _jsx(_components.a, {\n href: \"/quickstart\",\n children: \"platform API\"\n }), \" and \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"platform MCP\"\n }), \". Website tools cannot\\nread account data, manage artists, publish content, or send an inquiry.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"specification-and-first-request\",\n children: \"Specification and first request\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"https://recoupable.dev/openapi.json\",\n children: \"website OpenAPI specification\"\n }), \" defines\\nevery HTTP operation, its input and response schemas, and typed errors.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/.well-known/api-catalog\",\n children: \"API catalog\"\n }), \" links this\\nspecification alongside the platform specifications.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response contains \", _jsx(_components.code, {\n children: \"results\"\n }), \", \", _jsx(_components.code, {\n children: \"total\"\n }), \", and \", _jsx(_components.code, {\n children: \"nextCursor\"\n }), \". An empty result list\\nis a successful search. Use a returned content ID with\\n\", _jsx(_components.code, {\n children: \"GET /agent-api/v1/read?id=CONTENT_ID\"\n }), \"; continue at the returned \", _jsx(_components.code, {\n children: \"nextOffset\"\n }), \"\\nuntil it is null. The reader accepts registry IDs, never arbitrary private URLs.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"GET /agent-api/v1/markdown?path=/blog\"\n }), \" for a complete public page as Markdown.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/agents.md\",\n children: \"website agent guide\"\n }), \" explains all five tools,\\npagination, draft behavior, and the browser interface.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"batch-independent-operations\",\n children: \"Batch independent operations\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST https://recoupable.dev/agent-api/v1/batch\"\n }), \" accepts one to ten operations.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl 'https://recoupable.dev/agent-api/v1/batch' \\\\\\n -H 'Content-Type: application/json' \\\\\\n --data '{\\\"operations\\\":[{\\\"name\\\":\\\"search_recoup\\\",\\\"arguments\\\":{\\\"query\\\":\\\"royalty\\\",\\\"limit\\\":1}},{\\\"name\\\":\\\"read_recoup_page\\\",\\\"arguments\\\":{\\\"id\\\":\\\"page:/services\\\",\\\"maxLength\\\":500}}]}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.code, {\n children: \"results\"\n }), \" array preserves input order. Each entry has its own \", _jsx(_components.code, {\n children: \"status\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"result\"\n }), \" or \", _jsx(_components.code, {\n children: \"error\"\n }), \". An individual failure does not cancel successful reads.\\nThe batch is not a transaction. Its entire request body must fit within 16 KB.\\nDraft operations return \", _jsx(_components.code, {\n children: \"submitted: false\"\n }), \"; nothing is sent or saved as a lead.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hosted-quotas-and-errors\",\n children: \"Hosted quotas and errors\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP and MCP website tools share a limit of 120 requests per 60-second fixed\\nwindow, per IP address and serving region. A batch counts as one request.\\n\", _jsx(_components.code, {\n children: \"RateLimit-Limit\"\n }), \" and \", _jsx(_components.code, {\n children: \"RateLimit-Policy\"\n }), \" describe that enforced policy on live\\nresponses. Regional counters are not a global account allowance.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"On HTTP 429, wait the \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" duration before retrying. HTTP 503 means the\\nrequest could not be completed; retry later. JSON tool endpoints return structured\\nerrors with a code, message, and recovery guidance for invalid arguments or missing content.\\nLocal development does not enforce the hosted quota.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"versioning-and-deprecation\",\n children: \"Versioning and deprecation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Website HTTP operations use \", _jsx(_components.code, {\n children: \"/agent-api/v1\"\n }), \". Additive response fields are\\ncompatible; clients should ignore fields they do not recognize. Incompatible\\nchanges require a new major URL version.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"No v1 deprecation or sunset is scheduled. A future retirement will be announced\\nin the \", _jsx(_components.a, {\n href: \"https://recoupable.dev/agents.md\",\n children: \"agent guide\"\n }), \" with a migration guide and\\n\", _jsx(_components.code, {\n children: \"Deprecation\"\n }), \", \", _jsx(_components.code, {\n children: \"Sunset\"\n }), \", and \", _jsx(_components.code, {\n children: \"Link\"\n }), \" response headers when dates are known.\\nThis policy applies to the public website API.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"mcp-connection\",\n children: \"MCP connection\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connect to \", _jsx(_components.code, {\n children: \"https://recoupable.dev/mcp\"\n }), \" over Streamable HTTP without credentials.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/.well-known/mcp.json\",\n children: \"public manifest\"\n }), \" identifies\\nthe server. Its five tools share the website HTTP capabilities and hosted quota.\\nTo use your music-platform account, follow \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" instead.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Recoup public website API Search and read public Recoup content, use bounded website tools, and batch independent operations without an account. Quickstart Getting started The public website API searches and reads published Recoup pages, calculates workflow scenarios from supplied inputs, and prepares unsubmitted project briefs. It is free and requires no account, API key, or payment method. Music-platform operations use the separate authenticated [platform API](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot read account data, manage artists, publish content, or send an inquiry. ## Specification and first request The [website OpenAPI specification](https://recoupable.dev/openapi.json) defines every HTTP operation, its input and response schemas, and typed errors. The [API catalog](https://recoupable.dev/.well-known/api-catalog) links this specification alongside the platform specifications. The response contains `results`, `total`, and `nextCursor`. An empty result list is a successful search. Use a returned content ID with `GET /agent-api/v1/read?id=CONTENT_ID`; continue at the returned `nextOffset` until it is null. The reader accepts registry IDs, never arbitrary private URLs. Use `GET /agent-api/v1/markdown?path=/blog` for a complete public page as Markdown. The [website agent guide](https://recoupable.dev/agents.md) explains all five tools, pagination, draft behavior, and the browser interface. ## Batch independent operations `POST https://recoupable.dev/agent-api/v1/batch` accepts one to ten operations. The `results` array preserves input order. Each entry has its own `status` and `result` or `error`. An individual failure does not cancel successful reads. The batch is not a transaction. Its entire request body must fit within 16 KB. Draft operations return `submitted: false`; nothing is sent or saved as a lead. ## Hosted quotas and errors HTTP and MCP website tools share a limit of 120 requests per 60-second fixed window, per IP address and serving region. A batch counts as one request. `RateLimit-Limit` and `RateLimit-Policy` describe that enforced policy on live responses. Regional counters are not a global account allowance. On HTTP 429, wait the `Retry-After` duration before retrying. HTTP 503 means the request could not be completed; retry later. JSON tool endpoints return structured errors with a code, message, and recovery guidance for invalid arguments or missing content. Local development does not enforce the hosted quota. ## Versioning and deprecation Website HTTP operations use `/agent-api/v1`. Additive response fields are compatible; clients should ignore fields they do not recognize. Incompatible changes require a new major URL version. No v1 deprecation or sunset is scheduled. A future retirement will be announced in the [agent guide](https://recoupable.dev/agents.md) with a migration guide and `Deprecation`, `Sunset`, and `Link` response headers when dates are known. This policy applies to the public website API. ## MCP connection Connect to `https://recoupable.dev/mcp` over Streamable HTTP without credentials. The [public manifest](https://recoupable.dev/.well-known/mcp.json) identifies the server. Its five tools share the website HTTP capabilities and hosted quota. To use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead. "},{"slug":"cli","title":"CLI","description":"Install the Recoup CLI and interact with the platform from your terminal.","category":"Quickstart","group":"Getting started","source":"cli.mdx","body":"The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.\n\n\n**The CLI is in beta.** The reference below follows the v0.1.15 source command set. Check `recoup --version` and `--help` for the package installed in your environment. For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up.\n\n**Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.\n\n\n## Install\n\n```bash\nnpm install -g @recoupable/cli\n```\n\n## Authenticate\n\nSet your API key as an environment variable:\n\n```bash\nexport RECOUP_API_KEY=your-api-key\n```\n\nVerify it works:\n\n```bash\nrecoup whoami\n```\n\n\nGet an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) for instant key generation.\n\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `RECOUP_API_KEY` | Yes | — | Your Recoup API key |\n| `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override; set `https://api.recoupable.dev` to use the canonical API domain |\n\nAll commands support `--json` for machine-readable output and `--help` for usage info.\n\n---\n\n## Commands\n\n### whoami\n\nShow the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id).\n\n```bash\nrecoup whoami\nrecoup whoami --json\n```\n\n### orgs\n\nList organizations. See [`GET /api/organizations`](/api-reference/organizations/list).\n\n```bash\nrecoup orgs list\nrecoup orgs list --account \n```\n\n### artists\n\nList artists. See [`GET /api/artists`](/api-reference/artists/list).\n\n```bash\nrecoup artists list\nrecoup artists list --org \nrecoup artists list --account \n```\n\n### emails\n\nSend an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create).\n\n```bash\nrecoup emails --subject \"Pulse Report\" --text \"Here's your weekly summary.\"\nrecoup emails --subject \"Update\" --html \"

Report

Details here.

\"\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--subject ` | No | Email subject line; defaults from the body when omitted |\n| `--text ` | No | Plain text or Markdown body |\n| `--html ` | No | Raw HTML body (takes precedence over `--text`) |\n| `--cc ` | No | CC recipient (repeatable) |\n| `--chat-id ` | No | Chat ID for a chat link in the email footer |\n| `--account ` | No | Send to a specific account (org keys only) |\n\n### chats\n\nManage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create).\n\n```bash\nrecoup chats list\nrecoup chats create --name \"My Topic\"\nrecoup chats create --name \"My Topic\" --artist \n```\n\n### sandboxes\n\nManage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create).\n\n```bash\nrecoup sandboxes list\nrecoup sandboxes create\nrecoup sandboxes create --command \"ls -la\"\n```\n\n### tasks\n\nCheck background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs).\n\n```bash\nrecoup tasks status --run \n```\n\n### songs\n\nRun AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets).\n\n```bash\nrecoup songs presets\nrecoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3\nrecoup songs analyze --prompt \"Describe the production style\" --audio https://example.com/track.mp3\n```\n\nExactly one of `--preset` or `--prompt` is required, together with `--audio`. The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API.\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. |\n| `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. |\n| `--audio ` | Yes | Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported. |\n| `--max-tokens ` | No | Max tokens to generate (default 512). |\n\n---\n\n## content\n\nContent creation pipeline — generate AI-powered social videos for artists.\n\n### List templates\n\n```bash\nrecoup content templates\n```\n\n### Validate an artist\n\nCheck that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate).\n\n```bash\nrecoup content validate --artist \n```\n\n### Estimate cost\n\nPreview estimated cost and duration before kicking off the pipeline. See [`GET /api/content/estimate`](/api-reference/content/estimate).\n\n```bash\nrecoup content estimate\nrecoup content estimate --lipsync --batch 2 --compare\n```\n\n### Create content\n\nRun the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create).\n\n```bash\nrecoup content create --artist \nrecoup content create --artist --template --lipsync --upscale\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--artist ` | Yes | Artist account ID |\n| `--template ` | No | Template name (default: random) |\n| `--lipsync` | No | Enable lipsync mode |\n| `--upscale` | No | Enable upscaling |\n| `--caption-length ` | No | Max caption length in characters |\n\n\nFor finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands.\n\n","headings":[{"title":"Install","id":"install"},{"title":"Authenticate","id":"authenticate"},{"title":"Configuration","id":"configuration"},{"title":"Commands","id":"commands"},{"title":"content","id":"content"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n }, {Note, Tip} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Tip) _missingMdxReference(\"Tip\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"The Recoup CLI (\", _jsx(_components.code, {\n children: \"@recoupable/cli\"\n }), \") wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.\"]\n }), \"\\n\", _jsxs(Note, {\n children: [_jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"The CLI is in beta.\"\n }), \" The reference below follows the v0.1.15 source command set. Check \", _jsx(_components.code, {\n children: \"recoup --version\"\n }), \" and \", _jsx(_components.code, {\n children: \"--help\"\n }), \" for the package installed in your environment. For research workflows and most content operations, call the \", _jsx(_components.a, {\n href: \"/api-reference\",\n children: \"REST API\"\n }), \" directly — the CLI is gradually catching up.\"]\n }), _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Agents:\"\n }), \" if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.\"]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"install\",\n children: \"Install\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"npm install -g @recoupable/cli\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authenticate\",\n children: \"Authenticate\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Set your API key as an environment variable:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"export RECOUP_API_KEY=your-api-key\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Verify it works:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup whoami\\n\"\n })\n }), \"\\n\", _jsx(Tip, {\n children: _jsxs(_components.p, {\n children: [\"Get an API key from the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys page\"\n }), \" or use the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"agent signup\"\n }), \" for instant key generation.\"]\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"configuration\",\n children: \"Configuration\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Variable\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Default\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"RECOUP_API_KEY\"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"—\"\n }), _jsx(_components.td, {\n children: \"Your Recoup API key\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"RECOUP_API_URL\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"https://recoup-api.vercel.app\"\n })\n }), _jsxs(_components.td, {\n children: [\"API base URL override; set \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \" to use the canonical API domain\"]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"All commands support \", _jsx(_components.code, {\n children: \"--json\"\n }), \" for machine-readable output and \", _jsx(_components.code, {\n children: \"--help\"\n }), \" for usage info.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"commands\",\n children: \"Commands\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"whoami\",\n children: \"whoami\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Show the authenticated account. See \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup whoami\\nrecoup whoami --json\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"orgs\",\n children: \"orgs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"List organizations. See \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/organizations\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup orgs list\\nrecoup orgs list --account \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"artists\",\n children: \"artists\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"List artists. See \", _jsx(_components.a, {\n href: \"/api-reference/artists/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/artists\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup artists list\\nrecoup artists list --org \\nrecoup artists list --account \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"emails\",\n children: \"emails\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send an email to the authenticated account. See \", _jsx(_components.a, {\n href: \"/api-reference/emails/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/emails\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup emails --subject \\\"Pulse Report\\\" --text \\\"Here's your weekly summary.\\\"\\nrecoup emails --subject \\\"Update\\\" --html \\\"

Report

Details here.

\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--subject \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Email subject line; defaults from the body when omitted\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--text \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Plain text or Markdown body\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--html \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsxs(_components.td, {\n children: [\"Raw HTML body (takes precedence over \", _jsx(_components.code, {\n children: \"--text\"\n }), \")\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--cc \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"CC recipient (repeatable)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--chat-id \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Chat ID for a chat link in the email footer\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--account \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Send to a specific account (org keys only)\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"chats\",\n children: \"chats\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Manage chats. See \", _jsx(_components.a, {\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.code, {\n children: \"GET /api/chats\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/chat/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/chats\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup chats list\\nrecoup chats create --name \\\"My Topic\\\"\\nrecoup chats create --name \\\"My Topic\\\" --artist \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"sandboxes\",\n children: \"sandboxes\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Manage sandboxes. See \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/sandboxes\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup sandboxes list\\nrecoup sandboxes create\\nrecoup sandboxes create --command \\\"ls -la\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"tasks\",\n children: \"tasks\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Check background task status. See \", _jsx(_components.a, {\n href: \"/api-reference/tasks/runs\",\n children: _jsx(_components.code, {\n children: \"GET /api/tasks/runs\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup tasks status --run \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"songs\",\n children: \"songs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Run AI music analysis. See \", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze-presets\",\n children: _jsx(_components.code, {\n children: \"GET /api/songs/analyze/presets\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup songs presets\\nrecoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3\\nrecoup songs analyze --prompt \\\"Describe the production style\\\" --audio https://example.com/track.mp3\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Exactly one of \", _jsx(_components.code, {\n children: \"--preset\"\n }), \" or \", _jsx(_components.code, {\n children: \"--prompt\"\n }), \" is required, together with \", _jsx(_components.code, {\n children: \"--audio\"\n }), \". The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--preset \"\n })\n }), _jsx(_components.td, {\n children: \"Conditional\"\n }), _jsxs(_components.td, {\n children: [\"Curated analysis preset. Required when \", _jsx(_components.code, {\n children: \"--prompt\"\n }), \" is omitted.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--prompt \"\n })\n }), _jsx(_components.td, {\n children: \"Conditional\"\n }), _jsxs(_components.td, {\n children: [\"Custom text prompt. Required when \", _jsx(_components.code, {\n children: \"--preset\"\n }), \" is omitted.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--audio \"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--max-tokens \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Max tokens to generate (default 512).\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"content\",\n children: \"content\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Content creation pipeline — generate AI-powered social videos for artists.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"list-templates\",\n children: \"List templates\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content templates\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"validate-an-artist\",\n children: \"Validate an artist\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Check that an artist has the required assets before creating content. See \", _jsx(_components.a, {\n href: \"/api-reference/content/validate\",\n children: _jsx(_components.code, {\n children: \"GET /api/content/validate\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content validate --artist \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"estimate-cost\",\n children: \"Estimate cost\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Preview estimated cost and duration before kicking off the pipeline. See \", _jsx(_components.a, {\n href: \"/api-reference/content/estimate\",\n children: _jsx(_components.code, {\n children: \"GET /api/content/estimate\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content estimate\\nrecoup content estimate --lipsync --batch 2 --compare\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"create-content\",\n children: \"Create content\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Run the full content-creation pipeline for an artist. See \", _jsx(_components.a, {\n href: \"/api-reference/content/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/content/create\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content create --artist \\nrecoup content create --artist --template --lipsync --upscale\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--artist \"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Artist account ID\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--template \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Template name (default: random)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--lipsync\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Enable lipsync mode\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--upscale\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Enable upscaling\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--caption-length \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Max caption length in characters\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(Tip, {\n children: _jsxs(_components.p, {\n children: [\"For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the \", _jsx(_components.a, {\n href: \"/api-reference/content/generate-image\",\n children: \"content REST endpoints\"\n }), \" directly. Those primitives aren't yet exposed as individual CLI subcommands.\"]\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"CLI Install the Recoup CLI and interact with the platform from your terminal. Quickstart Getting started The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments. **The CLI is in beta.** The reference below follows the v0.1.15 source command set. Check `recoup --version` and `--help` for the package installed in your environment. For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up. **Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command. ## Install ## Authenticate Set your API key as an environment variable: Verify it works: Get an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) for instant key generation. ## Configuration | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `RECOUP_API_KEY` | Yes | — | Your Recoup API key | | `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override; set `https://api.recoupable.dev` to use the canonical API domain | All commands support `--json` for machine-readable output and `--help` for usage info. --- ## Commands ### whoami Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id). ### orgs List organizations. See [`GET /api/organizations`](/api-reference/organizations/list). ### artists List artists. See [`GET /api/artists`](/api-reference/artists/list). ### emails Send an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create). | Flag | Required | Description | |------|----------|-------------| | `--subject ` | No | Email subject line; defaults from the body when omitted | | `--text ` | No | Plain text or Markdown body | | `--html ` | No | Raw HTML body (takes precedence over `--text`) | | `--cc ` | No | CC recipient (repeatable) | | `--chat-id ` | No | Chat ID for a chat link in the email footer | | `--account ` | No | Send to a specific account (org keys only) | ### chats Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create). ### sandboxes Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create). ### tasks Check background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs). ### songs Run AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets). Exactly one of `--preset` or `--prompt` is required, together with `--audio`. The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API. | Flag | Required | Description | |------|----------|-------------| | `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. | | `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. | | `--audio ` | Yes | Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported. | | `--max-tokens ` | No | Max tokens to generate (default 512). | --- ## content Content creation pipeline — generate AI-powered social videos for artists. ### List templates ### Validate an artist Check that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate). ### Estimate cost Preview estimated cost and duration before kicking off the pipeline. See [`GET /api/content/estimate`](/api-reference/content/estimate). ### Create content Run the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create). | Flag | Required | Description | |------|----------|-------------| | `--artist ` | Yes | Artist account ID | | `--template ` | No | Template name (default: random) | | `--lipsync` | No | Enable lipsync mode | | `--upscale` | No | Enable upscaling | | `--caption-length ` | No | Max caption length in characters | For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands. "},{"slug":"claude","title":"Claude","description":"Connect Claude to Recoup and install optional workflow instructions.","category":"Quickstart","group":"Getting started","source":"claude.mdx","body":"Add `https://api.recoupable.dev/mcp` in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See [MCP OAuth](/mcp-oauth) for the dated client verification record and troubleshooting.\n\nAfter connecting, refresh tools and call the discovered `list_artists` tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account.\n\nFor workflow instructions, install the consolidated Recoup package from the [Recoup marketplace](https://github.com/recoupable/marketplace), using the manifest/package name shown there. Skills-only installation with `npx skills add recoupable/skills` does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed.\n\nMCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access.\n\nStart a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow.\n","headings":[],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Add \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for the dated client verification record and troubleshooting.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"After connecting, refresh tools and call the discovered \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For workflow instructions, install the consolidated Recoup package from the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketplace\",\n children: \"Recoup marketplace\"\n }), \", using the manifest/package name shown there. Skills-only installation with \", _jsx(_components.code, {\n children: \"npx skills add recoupable/skills\"\n }), \" does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"MCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Start a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Claude Connect Claude to Recoup and install optional workflow instructions. Quickstart Getting started Add `https://api.recoupable.dev/mcp` in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See [MCP OAuth](/mcp-oauth) for the dated client verification record and troubleshooting. After connecting, refresh tools and call the discovered `list_artists` tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account. For workflow instructions, install the consolidated Recoup package from the [Recoup marketplace](https://github.com/recoupable/marketplace), using the manifest/package name shown there. Skills-only installation with `npx skills add recoupable/skills` does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed. MCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access. Start a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow. "},{"slug":"mcp","title":"MCP","description":"Connect an agent to Recoup through OAuth and discover its authorized tools.","category":"Quickstart","group":"Getting started","source":"mcp.mdx","body":"Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](/mcp-oauth).\n\nUse `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result.\n\n`mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.\n\nSandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](/api-reference/sandboxes/create) with a separate authorized credential when required.\n\nFor an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.\n\n## Context results\n\nThe [Context reference](/api-reference/context/operate) pairs each supported action\nwith its success status, response model and synthetic request/result examples.\nUse the status declared for that action: `ingest` returns 202, while the specific\ncatalog, artist, release and text ingestion actions return 200. A 202 verification\nreceipt means queued after existing readiness checks, not completed work.\nHTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt;\ndelegated OAuth omits it. The examples do not verify hosted access or enable collection.\n\n## Plan a catalog lookup\n\nA catalog manager with an existing catalog Context request can plan a lookup for\nits current expanded recording members. Standard MCP uses `context` with\n`action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research`\nwith the same input fields and no `action`. Discover the tool in the connected\nclient before use; this source mapping does not prove hosted availability.\n\nChoose `recording_candidates`, `recording_work_candidates` or `platform_metadata`.\nThese plan possible recording matches, linked works or platform track information.\nThe response preserves the existing module values and node IDs, returns each node\nblocked and has `collectionPermitted: false`. It does not fetch data, verify rights,\nstart collection or grant spending permission. The [Context reference](/api-reference/context/operate)\nlists all accepted compatibility values, required IDs, page cursors and the complete response.\n\n## Continue a catalog case\n\nThe source contract adds `save_catalog_case`, `read_catalog_case` and\n`list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the\ntools in the connected host before using them. They also use the `context` tool\nwith the corresponding `action`. The catalog-case database and API release must\nbe deployed before this source contract is available.\n\nA case keeps versioned sources, assessments, findings, proposed actions, attempts\nand outcomes for the authorized workspace. No artist or ingestion request is\nrequired. The stored snapshot is `customer_assertion` evidence and always returns\n`external_actions: unsupported`: saving a record does not submit a registration,\nsend a claim, confirm a provider decision or verify a bank receipt.\n\nFor a new case, save with `expected_revision: 0` and `snapshot.revision: 0`.\nFor subsequent saves, use the current revision. Supply a unique idempotency key\nfor each new save. After an uncertain response, retry the unchanged payload with\nthe same key and expected revision.\nReads can withhold withdrawn evidence and its dependent records; explicitly\nreassemble a partial snapshot before another save. The [Context reference](/api-reference/context/operate)\ndefines the complete bounded schema, historical-source rules, revision conflicts,\nresponse fields and list pagination.\n\n## Check an application proposal\n\nThe pending standard MCP tool `validate_application_registration` checks an\nauthorized workspace's proposed name, environment, exact origins and return URLs.\nIt returns `persisted: false` and `origins_verified: false`; it does not register\nan application, prove domain ownership or issue application credentials.\nDelegated OAuth excludes this tool, including grants with `mcp:tools`. Discover\nit in a standard connection before use. See the [proposal preflight reference](/api-reference/applications/validate-registration)\nfor inputs, normal authentication effects and the limits of a successful result.\n\n## Release Packs\n\nWhen deployed and exposed by the current grant, the pack catalog includes\n`prepare_release_pack`, `get_release_pack`, `estimate_release_pack`,\n`generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and\n`export_release_pack`. These use the same account ownership, brief revisions,\ncomplete quotes and budget limits as REST. No existing artist or GitHub workspace\nis required. Use returned schemas and identifiers; preparation does not authorize\npaid generation. See [Release Packs](/release-packs) for first use and upload limits.\n","headings":[{"title":"Context results","id":"context-results"},{"title":"Plan a catalog lookup","id":"plan-a-catalog-lookup"},{"title":"Continue a catalog case","id":"continue-a-catalog-case"},{"title":"Check an application proposal","id":"check-an-application-proposal"},{"title":"Release Packs","id":"release-packs"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Connect your host to \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"OAuth setup guide\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"tools/list\"\n }), \" after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" and call it with its returned schema to verify access. An empty roster is a valid result.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sandbox command tools previously shown on this page are absent from the current registry. Do not call \", _jsx(_components.code, {\n children: \"prompt_sandbox\"\n }), \", \", _jsx(_components.code, {\n children: \"run_sandbox_command\"\n }), \", or infer that every REST endpoint is exposed as MCP. Use documented \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/create\",\n children: \"REST sandbox operations\"\n }), \" with a separate authorized credential when required.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For an API-key MCP connection, configure \", _jsx(_components.code, {\n children: \"Authorization: Bearer YOUR_RECOUP_API_KEY\"\n }), \" in the client's secret settings. The \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header is for \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"REST requests\"\n }), \". Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"context-results\",\n children: \"Context results\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \" pairs each supported action\\nwith its success status, response model and synthetic request/result examples.\\nUse the status declared for that action: \", _jsx(_components.code, {\n children: \"ingest\"\n }), \" returns 202, while the specific\\ncatalog, artist, release and text ingestion actions return 200. A 202 verification\\nreceipt means queued after existing readiness checks, not completed work.\\nHTTP/standard MCP \", _jsx(_components.code, {\n children: \"read\"\n }), \" may include a metadata-only \", _jsx(_components.code, {\n children: \"material_evidence\"\n }), \" receipt;\\ndelegated OAuth omits it. The examples do not verify hosted access or enable collection.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"plan-a-catalog-lookup\",\n children: \"Plan a catalog lookup\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A catalog manager with an existing catalog Context request can plan a lookup for\\nits current expanded recording members. Standard MCP uses \", _jsx(_components.code, {\n children: \"context\"\n }), \" with\\n\", _jsx(_components.code, {\n children: \"action: plan_catalog_members\"\n }), \"; delegated OAuth uses \", _jsx(_components.code, {\n children: \"plan_music_catalog_research\"\n }), \"\\nwith the same input fields and no \", _jsx(_components.code, {\n children: \"action\"\n }), \". Discover the tool in the connected\\nclient before use; this source mapping does not prove hosted availability.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Choose \", _jsx(_components.code, {\n children: \"recording_candidates\"\n }), \", \", _jsx(_components.code, {\n children: \"recording_work_candidates\"\n }), \" or \", _jsx(_components.code, {\n children: \"platform_metadata\"\n }), \".\\nThese plan possible recording matches, linked works or platform track information.\\nThe response preserves the existing module values and node IDs, returns each node\\nblocked and has \", _jsx(_components.code, {\n children: \"collectionPermitted: false\"\n }), \". It does not fetch data, verify rights,\\nstart collection or grant spending permission. The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \"\\nlists all accepted compatibility values, required IDs, page cursors and the complete response.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"continue-a-catalog-case\",\n children: \"Continue a catalog case\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The source contract adds \", _jsx(_components.code, {\n children: \"save_catalog_case\"\n }), \", \", _jsx(_components.code, {\n children: \"read_catalog_case\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"list_catalog_cases\"\n }), \" to standard MCP; delegated OAuth excludes them. Discover the\\ntools in the connected host before using them. They also use the \", _jsx(_components.code, {\n children: \"context\"\n }), \" tool\\nwith the corresponding \", _jsx(_components.code, {\n children: \"action\"\n }), \". The catalog-case database and API release must\\nbe deployed before this source contract is available.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A case keeps versioned sources, assessments, findings, proposed actions, attempts\\nand outcomes for the authorized workspace. No artist or ingestion request is\\nrequired. The stored snapshot is \", _jsx(_components.code, {\n children: \"customer_assertion\"\n }), \" evidence and always returns\\n\", _jsx(_components.code, {\n children: \"external_actions: unsupported\"\n }), \": saving a record does not submit a registration,\\nsend a claim, confirm a provider decision or verify a bank receipt.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a new case, save with \", _jsx(_components.code, {\n children: \"expected_revision: 0\"\n }), \" and \", _jsx(_components.code, {\n children: \"snapshot.revision: 0\"\n }), \".\\nFor subsequent saves, use the current revision. Supply a unique idempotency key\\nfor each new save. After an uncertain response, retry the unchanged payload with\\nthe same key and expected revision.\\nReads can withhold withdrawn evidence and its dependent records; explicitly\\nreassemble a partial snapshot before another save. The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \"\\ndefines the complete bounded schema, historical-source rules, revision conflicts,\\nresponse fields and list pagination.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"check-an-application-proposal\",\n children: \"Check an application proposal\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The pending standard MCP tool \", _jsx(_components.code, {\n children: \"validate_application_registration\"\n }), \" checks an\\nauthorized workspace's proposed name, environment, exact origins and return URLs.\\nIt returns \", _jsx(_components.code, {\n children: \"persisted: false\"\n }), \" and \", _jsx(_components.code, {\n children: \"origins_verified: false\"\n }), \"; it does not register\\nan application, prove domain ownership or issue application credentials.\\nDelegated OAuth excludes this tool, including grants with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \". Discover\\nit in a standard connection before use. See the \", _jsx(_components.a, {\n href: \"/api-reference/applications/validate-registration\",\n children: \"proposal preflight reference\"\n }), \"\\nfor inputs, normal authentication effects and the limits of a successful result.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"release-packs\",\n children: \"Release Packs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"When deployed and exposed by the current grant, the pack catalog includes\\n\", _jsx(_components.code, {\n children: \"prepare_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"get_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"estimate_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"generate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"retry_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"upload_release_pack_asset\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"export_release_pack\"\n }), \". These use the same account ownership, brief revisions,\\ncomplete quotes and budget limits as REST. No existing artist or GitHub workspace\\nis required. Use returned schemas and identifiers; preparation does not authorize\\npaid generation. See \", _jsx(_components.a, {\n href: \"/release-packs\",\n children: \"Release Packs\"\n }), \" for first use and upload limits.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"MCP Connect an agent to Recoup through OAuth and discover its authorized tools. Quickstart Getting started Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](/mcp-oauth). Use `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result. `mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access. Sandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](/api-reference/sandboxes/create) with a separate authorized credential when required. For an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST. ## Context results The [Context reference](/api-reference/context/operate) pairs each supported action with its success status, response model and synthetic request/result examples. Use the status declared for that action: `ingest` returns 202, while the specific catalog, artist, release and text ingestion actions return 200. A 202 verification receipt means queued after existing readiness checks, not completed work. HTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt; delegated OAuth omits it. The examples do not verify hosted access or enable collection. ## Plan a catalog lookup A catalog manager with an existing catalog Context request can plan a lookup for its current expanded recording members. Standard MCP uses `context` with `action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research` with the same input fields and no `action`. Discover the tool in the connected client before use; this source mapping does not prove hosted availability. Choose `recording_candidates`, `recording_work_candidates` or `platform_metadata`. These plan possible recording matches, linked works or platform track information. The response preserves the existing module values and node IDs, returns each node blocked and has `collectionPermitted: false`. It does not fetch data, verify rights, start collection or grant spending permission. The [Context reference](/api-reference/context/operate) lists all accepted compatibility values, required IDs, page cursors and the complete response. ## Continue a catalog case The source contract adds `save_catalog_case`, `read_catalog_case` and `list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the tools in the connected host before using them. They also use the `context` tool with the corresponding `action`. The catalog-case database and API release must be deployed before this source contract is available. A case keeps versioned sources, assessments, findings, proposed actions, attempts and outcomes for the authorized workspace. No artist or ingestion request is required. The stored snapshot is `customer_assertion` evidence and always returns `external_actions: unsupported`: saving a record does not submit a registration, send a claim, confirm a provider decision or verify a bank receipt. For a new case, save with `expected_revision: 0` and `snapshot.revision: 0`. For subsequent saves, use the current revision. Supply a unique idempotency key for each new save. After an uncertain response, retry the unchanged payload with the same key and expected revision. Reads can withhold withdrawn evidence and its dependent records; explicitly reassemble a partial snapshot before another save. The [Context reference](/api-reference/context/operate) defines the complete bounded schema, historical-source rules, revision conflicts, response fields and list pagination. ## Check an application proposal The pending standard MCP tool `validate_application_registration` checks an authorized workspace's proposed name, environment, exact origins and return URLs. It returns `persisted: false` and `origins_verified: false`; it does not register an application, prove domain ownership or issue application credentials. Delegated OAuth excludes this tool, including grants with `mcp:tools`. Discover it in a standard connection before use. See the [proposal preflight reference](/api-reference/applications/validate-registration) for inputs, normal authentication effects and the limits of a successful result. ## Release Packs When deployed and exposed by the current grant, the pack catalog includes `prepare_release_pack`, `get_release_pack`, `estimate_release_pack`, `generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and `export_release_pack`. These use the same account ownership, brief revisions, complete quotes and budget limits as REST. No existing artist or GitHub workspace is required. Use returned schemas and identifiers; preparation does not authorize paid generation. See [Release Packs](/release-packs) for first use and upload limits. "},{"slug":"mcp-oauth","title":"Connect an agent","description":"Connect an MCP client to Recoup with OAuth and account-authorized tools.","category":"Quickstart","group":"Getting started","source":"mcp-oauth.mdx","body":"Use this URL in your agent's remote MCP settings:\n\n```text\nhttps://api.recoupable.dev/mcp\n```\n\nSelect **OAuth**. Recoup supports [published client metadata (CIMD)](/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.\n\n## What your agent can do\n\nRequest **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.\n\nThe consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.\n\n| Permission | Access |\n| --- | --- |\n| `mcp:tools` | Full business-tool catalog across accessible workspaces |\n| `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` |\n| `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` |\n\nExisting limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience.\n\nOAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.\n\nEmail uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.\n\nThe platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.\n\nNew connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately.\n\nConnections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.\n\n## Claude\n\n1. Open **Customize → Connectors → Add custom connector**.\n2. Name it **Recoup** and enter the MCP URL above.\n3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR.\n4. Connect, sign in to Recoup, and select **Allow access**.\n5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.\n\nClaude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.\n\nClaude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).\n\n## ChatGPT\n\nIn the interface tested on October 7, 2026:\n\n1. Open **Plugins → Add → Add custom MCP server**.\n2. Enter **Recoup**, the MCP URL, and **OAuth**.\n3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access.\n4. Create the plugin, connect it, and complete Recoup consent.\n5. Start a chat with Recoup enabled and request an artist list.\n\nChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).\n\n## Codex\n\n```bash\ncodex mcp add recoup --url https://api.recoupable.dev/mcp\ncodex mcp login recoup --scopes mcp:tools\n```\n\nComplete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp).\n\n## Cursor\n\nAdd a remote server to your project's `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"recoup\": {\n \"url\": \"https://api.recoupable.dev/mcp\"\n }\n }\n}\n```\n\nOpen Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions.\n\n## Other agents and callbacks\n\nUse a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:\n\n- Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp`\n- Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth`\n- Resource: `https://api.recoupable.dev/mcp`\n\nRegister the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration.\n\nA generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.\n\n### Additional client setup paths\n\nThe following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.\n\n| Client | Setup and callback guidance |\n| --- | --- |\n| [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. |\n| [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. |\n| [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. |\n| [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost:/oauth/callback` unless configured otherwise. |\n| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. |\n| [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. |\n| [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. |\n| [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. |\n\nDocumented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.\n\n## Disconnect\n\nOpen [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.\n\n## Troubleshooting\n\n| Symptom | What to do |\n| --- | --- |\n| Custom connector option missing | Check your client's plan and workspace-admin permissions. |\n| Published identity / CIMD unavailable or fails | Check the [metadata requirements](/mcp-cimd), or choose automatic registration / DCR if your client offers it. |\n| Connection request expired | Restart Connect from the client; do not reuse an old consent URL. |\n| Wrong Recoup account | Use Switch before approving. |\n| Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. |\n| Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. |\n| Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. |\n| `401` after disconnect | Expected: reconnect and approve a new grant. |\n| `429` | Respect `Retry-After`; avoid repeated registration attempts. |\n| `503` | Retry later; do not weaken authentication or callback checks. |\n| Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. |\n\nFor clients without OAuth, [API-key authentication](/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.\n\nFor help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys.\n\nFull OAuth MCP calls currently share account-level limits of 120 calls per minute\nand 30 calls per tool per minute across connected clients. See the\n[pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts).\nThe `compact_chats` MCP tool accepts up to 50 chats per call under the\n[pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts);\nthis is an MCP limit, not a claimed REST request limit.\n","headings":[{"title":"What your agent can do","id":"what-your-agent-can-do"},{"title":"Claude","id":"claude"},{"title":"ChatGPT","id":"chatgpt"},{"title":"Codex","id":"codex"},{"title":"Cursor","id":"cursor"},{"title":"Other agents and callbacks","id":"other-agents-and-callbacks"},{"title":"Disconnect","id":"disconnect"},{"title":"Troubleshooting","id":"troubleshooting"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Use this URL in your agent's remote MCP settings:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-text\",\n children: \"https://api.recoupable.dev/mcp\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Select \", _jsx(_components.strong, {\n children: \"OAuth\"\n }), \". Recoup supports \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"published client metadata (CIMD)\"\n }), \" and \", _jsx(_components.strong, {\n children: \"automatic registration\"\n }), \" (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-your-agent-can-do\",\n children: \"What your agent can do\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Request \", _jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"mcp:tools\"\n })\n }), \" for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Permission\"\n }), _jsx(_components.th, {\n children: \"Access\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:tools\"\n })\n }), _jsx(_components.td, {\n children: \"Full business-tool catalog across accessible workspaces\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:read\"\n })\n }), _jsxs(_components.td, {\n children: [\"Original personal-only \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \", \", _jsx(_components.code, {\n children: \"get_artist_socials\"\n }), \", \", _jsx(_components.code, {\n children: \"get_chats\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:write\"\n })\n }), _jsxs(_components.td, {\n children: [\"Original personal-only \", _jsx(_components.code, {\n children: \"create_new_artist\"\n }), \", \", _jsx(_components.code, {\n children: \"update_account_info\"\n })]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Existing limited grants do \", _jsx(_components.strong, {\n children: \"not\"\n }), \" expand automatically. Reconnect with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \", review the broader permission, and refresh your client's tool catalog. Clients requesting the \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" + \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" pair keep the five-tool experience.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"OAuth never exposes \", _jsx(_components.code, {\n children: \"get_api_key\"\n }), \": it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. \", _jsx(_components.code, {\n children: \"create_knowledge_base\"\n }), \" and \", _jsx(_components.code, {\n children: \"generate_txt_file\"\n }), \" publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound \", _jsx(_components.code, {\n children: \"id\"\n }), \"; pass that entire value as \", _jsx(_components.code, {\n children: \"video_id\"\n }), \" to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/oauth/connections\",\n children: \"Connected agents\"\n }), \" to revoke its access and refresh tokens immediately.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"claude\",\n children: \"Claude\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Open \", _jsx(_components.strong, {\n children: \"Customize → Connectors → Add custom connector\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Name it \", _jsx(_components.strong, {\n children: \"Recoup\"\n }), \" and enter the MCP URL above.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Choose \", _jsx(_components.strong, {\n children: \"Sign in now\"\n }), \". \", _jsx(_components.strong, {\n children: \"Register automatically\"\n }), \" uses DCR; \", _jsx(_components.strong, {\n children: \"published identity\"\n }), \" uses CIMD. The production client tests below used DCR.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Connect, sign in to Recoup, and select \", _jsx(_components.strong, {\n children: \"Allow access\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See \", _jsx(_components.a, {\n href: \"https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp\",\n children: \"Claude's remote connector guide\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"chatgpt\",\n children: \"ChatGPT\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"In the interface tested on October 7, 2026:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Open \", _jsx(_components.strong, {\n children: \"Plugins → Add → Add custom MCP server\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Enter \", _jsx(_components.strong, {\n children: \"Recoup\"\n }), \", the MCP URL, and \", _jsx(_components.strong, {\n children: \"OAuth\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Under advanced OAuth settings, confirm \", _jsx(_components.strong, {\n children: \"Dynamic Client Registration (DCR)\"\n }), \" and request \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for full access.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Create the plugin, connect it, and complete Recoup consent.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Start a chat with Recoup enabled and request an artist list.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see \", _jsx(_components.a, {\n href: \"https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt\",\n children: \"OpenAI's MCP setup documentation\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"codex\",\n children: \"Codex\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"codex mcp add recoup --url https://api.recoupable.dev/mcp\\ncodex mcp login recoup --scopes mcp:tools\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See \", _jsx(_components.a, {\n href: \"https://developers.openai.com/codex/mcp\",\n children: \"Codex MCP configuration\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"cursor\",\n children: \"Cursor\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Add a remote server to your project's \", _jsx(_components.code, {\n children: \".cursor/mcp.json\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"mcpServers\\\": {\\n \\\"recoup\\\": {\\n \\\"url\\\": \\\"https://api.recoupable.dev/mcp\\\"\\n }\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See \", _jsx(_components.a, {\n href: \"https://cursor.com/docs/mcp\",\n children: \"Cursor's MCP guide\"\n }), \" for the current setup and workspace restrictions.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"other-agents-and-callbacks\",\n children: \"Other agents and callbacks\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Resource metadata: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Authorization-server metadata: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Resource: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute \", _jsx(_components.code, {\n children: \"localhost\"\n }), \" for \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \" or edit a callback after registration.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"CIMD requirements and verification status\"\n }), \". Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"additional-client-setup-paths\",\n children: \"Additional client setup paths\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The following paths were reviewed in official client documentation on October 7, 2026. \", _jsx(_components.strong, {\n children: \"They have not been tested end to end against Recoup.\"\n }), \" Use automatic registration and request \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for full access, or \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" / \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Client\"\n }), _jsx(_components.th, {\n children: \"Setup and callback guidance\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors\",\n children: \"Perplexity\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are \", _jsx(_components.code, {\n children: \"https://www.perplexity.ai/rest/connections/oauth_callback\"\n }), \" and, for enterprise, \", _jsx(_components.code, {\n children: \"https://enterprise.perplexity.ai/rest/connections/oauth_callback\"\n }), \".\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://code.claude.com/docs/en/mcp\",\n children: \"Claude Code\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add Recoup as an HTTP server and authenticate through \", _jsx(_components.code, {\n children: \"/mcp\"\n }), \" inside Claude Code. Automatic registration uses a localhost callback; \", _jsx(_components.code, {\n children: \"--callback-port\"\n }), \" can fix its port when required.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization\",\n children: \"VS Code\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add an HTTP server in \", _jsx(_components.code, {\n children: \".vscode/mcp.json\"\n }), \". OAuth supports DCR; documented callbacks include \", _jsx(_components.code, {\n children: \"http://127.0.0.1:33418\"\n }), \" and \", _jsx(_components.code, {\n children: \"https://vscode.dev/redirect\"\n }), \". Preserve the callback supplied by your VS Code surface.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://geminicli.com/docs/tools/mcp-server/\",\n children: \"Gemini CLI\"\n })\n }), _jsxs(_components.td, {\n children: [\"Configure the MCP URL as \", _jsx(_components.code, {\n children: \"httpUrl\"\n }), \" and authenticate with \", _jsx(_components.code, {\n children: \"/mcp auth recoup\"\n }), \" inside the Gemini CLI chat. DCR uses \", _jsx(_components.code, {\n children: \"http://localhost:/oauth/callback\"\n }), \" unless configured otherwise.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://opencode.ai/docs/mcp-servers/\",\n children: \"OpenCode\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add a remote MCP server and run \", _jsx(_components.code, {\n children: \"opencode mcp auth recoup\"\n }), \". OAuth supports automatic registration. Let the client supply its callback.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://kiro.dev/docs/mcp/configuration/\",\n children: \"Kiro\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add the remote MCP URL and use DCR. Set \", _jsx(_components.code, {\n children: \"oauth.oauthScopes\"\n }), \" to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://docs.n8n.io/integrations/builtin/credentials/mcp/\",\n children: \"n8n\"\n })\n }), _jsxs(_components.td, {\n children: [\"Create an MCP OAuth credential with \", _jsx(_components.strong, {\n children: \"Use Dynamic Client Registration\"\n }), \" enabled. Use the exact callback shown by your n8n instance.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent\",\n children: \"Copilot Studio\"\n })\n }), _jsx(_components.td, {\n children: \"Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio.\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"disconnect\",\n children: \"Disconnect\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Open \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/oauth/connections\",\n children: \"Connected agents\"\n }), \" and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"troubleshooting\",\n children: \"Troubleshooting\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Symptom\"\n }), _jsx(_components.th, {\n children: \"What to do\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Custom connector option missing\"\n }), _jsx(_components.td, {\n children: \"Check your client's plan and workspace-admin permissions.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Published identity / CIMD unavailable or fails\"\n }), _jsxs(_components.td, {\n children: [\"Check the \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"metadata requirements\"\n }), \", or choose automatic registration / DCR if your client offers it.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Connection request expired\"\n }), _jsx(_components.td, {\n children: \"Restart Connect from the client; do not reuse an old consent URL.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Wrong Recoup account\"\n }), _jsx(_components.td, {\n children: \"Use Switch before approving.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Still seeing only five tools\"\n }), _jsxs(_components.td, {\n children: [\"Reconnect requesting \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \", approve full access, then refresh the client tool catalog.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Connected but no tool access\"\n }), _jsx(_components.td, {\n children: \"Check selected scopes, individual tool approvals, and whether the grant expired or was revoked.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Organization artist missing\"\n }), _jsxs(_components.td, {\n children: [\"Reconnect with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" and verify your organization membership.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"401\"\n }), \" after disconnect\"]\n }), _jsx(_components.td, {\n children: \"Expected: reconnect and approve a new grant.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"429\"\n })\n }), _jsxs(_components.td, {\n children: [\"Respect \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \"; avoid repeated registration attempts.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"503\"\n })\n }), _jsx(_components.td, {\n children: \"Retry later; do not weaken authentication or callback checks.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Write timed out\"\n }), _jsx(_components.td, {\n children: \"Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate.\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For clients without OAuth, \", _jsx(_components.a, {\n href: \"/mcp\",\n children: \"API-key authentication\"\n }), \" remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For help, contact \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \". Include the client name, time, and error text; never include tokens, passwords, or API keys.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Full OAuth MCP calls currently share account-level limits of 120 calls per minute\\nand 30 calls per tool per minute across connected clients. See the\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts\",\n children: \"pinned rate-limit implementation\"\n }), \".\\nThe \", _jsx(_components.code, {\n children: \"compact_chats\"\n }), \" MCP tool accepts up to 50 chats per call under the\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts\",\n children: \"pinned MCP guard\"\n }), \";\\nthis is an MCP limit, not a claimed REST request limit.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Connect an agent Connect an MCP client to Recoup with OAuth and account-authorized tools. Quickstart Getting started Use this URL in your agent's remote MCP settings: Select **OAuth**. Recoup supports [published client metadata (CIMD)](/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied. ## What your agent can do Request **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support. The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound. | Permission | Access | | --- | --- | | `mcp:tools` | Full business-tool catalog across accessible workspaces | | `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` | | `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` | Existing limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience. OAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog. Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs. The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification. New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately. Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected. ## Claude 1. Open **Customize → Connectors → Add custom connector**. 2. Name it **Recoup** and enter the MCP URL above. 3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR. 4. Connect, sign in to Recoup, and select **Allow access**. 5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted. Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward. Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). ## ChatGPT In the interface tested on October 7, 2026: 1. Open **Plugins → Add → Add custom MCP server**. 2. Enter **Recoup**, the MCP URL, and **OAuth**. 3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access. 4. Create the plugin, connect it, and complete Recoup consent. 5. Start a chat with Recoup enabled and request an artist list. ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt). ## Codex Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp). ## Cursor Add a remote server to your project's `.cursor/mcp.json`: Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions. ## Other agents and callbacks Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes: - Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp` - Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth` - Resource: `https://api.recoupable.dev/mcp` Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration. A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only. ### Additional client setup paths The following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist. | Client | Setup and callback guidance | | --- | --- | | [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. | | [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. | | [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. | | [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost: /oauth/callback` unless configured otherwise. | | [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. | | [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. | | [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. | | [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. | Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access. ## Disconnect Open [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again. ## Troubleshooting | Symptom | What to do | | --- | --- | | Custom connector option missing | Check your client's plan and workspace-admin permissions. | | Published identity / CIMD unavailable or fails | Check the [metadata requirements](/mcp-cimd), or choose automatic registration / DCR if your client offers it. | | Connection request expired | Restart Connect from the client; do not reuse an old consent URL. | | Wrong Recoup account | Use Switch before approving. | | Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. | | Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. | | Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. | | `401` after disconnect | Expected: reconnect and approve a new grant. | | `429` | Respect `Retry-After`; avoid repeated registration attempts. | | `503` | Retry later; do not weaken authentication or callback checks. | | Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. | For clients without OAuth, [API-key authentication](/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command. For help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys. Full OAuth MCP calls currently share account-level limits of 120 calls per minute and 30 calls per tool per minute across connected clients. See the [pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts). The `compact_chats` MCP tool accepts up to 50 chats per call under the [pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts); this is an MCP limit, not a claimed REST request limit. "},{"slug":"mcp-cimd","title":"Published client metadata (CIMD)","description":"Connect using an HTTPS client identity without dynamic registration.","category":"Quickstart","group":"Getting started","source":"mcp-cimd.mdx","body":"Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth `client_id`. Recoup retrieves that document and validates the client's callbacks before asking you to approve access.\n\nUse the same MCP server URL: `https://api.recoupable.dev/mcp`. A compatible client can discover CIMD through `client_id_metadata_document_supported: true` in Recoup's [authorization-server metadata](https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth). No vendor-specific registration or callback allowlist is needed.\n\n## Access and trust\n\nCIMD uses the same [permissions and consent](/mcp-oauth) as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work.\n\nA client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account.\n\n## Client requirements\n\n- Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected.\n- Set `client_id` to the exact document URL and include `client_name` and `redirect_uris`.\n- Use a document URL with an explicit path and without credentials, fragments, or dot path segments.\n- Use authorization code flow with PKCE S256 and `mcp:tools` for the full Recoup catalog, or `mcp:read` / `mcp:write` for the original limited personal tools.\n- Public clients should set `token_endpoint_auth_method` to `none`. Never publish client secrets or private keys.\n- Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. `localhost` and `127.0.0.1` remain different hosts.\n\nRecoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy.\n\nMetadata caching respects freshness headers up to five minutes. `no-store`, `no-cache`, absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata.\n\n## Verification status\n\nThe implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits.\n\nA local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on [Connect an agent](/mcp-oauth) were obtained using DCR.\n\nProduction verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified.\n\nIf a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored.\n\nSee the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and [CIMD draft 02](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html). CIMD remains a draft specification; Recoup's provider currently implements draft 02.\n","headings":[{"title":"Access and trust","id":"access-and-trust"},{"title":"Client requirements","id":"client-requirements"},{"title":"Verification status","id":"verification-status"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth \", _jsx(_components.code, {\n children: \"client_id\"\n }), \". Recoup retrieves that document and validates the client's callbacks before asking you to approve access.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the same MCP server URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \". A compatible client can discover CIMD through \", _jsx(_components.code, {\n children: \"client_id_metadata_document_supported: true\"\n }), \" in Recoup's \", _jsx(_components.a, {\n href: \"https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth\",\n children: \"authorization-server metadata\"\n }), \". No vendor-specific registration or callback allowlist is needed.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"access-and-trust\",\n children: \"Access and trust\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"CIMD uses the same \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"permissions and consent\"\n }), \" as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"client-requirements\",\n children: \"Client requirements\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Set \", _jsx(_components.code, {\n children: \"client_id\"\n }), \" to the exact document URL and include \", _jsx(_components.code, {\n children: \"client_name\"\n }), \" and \", _jsx(_components.code, {\n children: \"redirect_uris\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Use a document URL with an explicit path and without credentials, fragments, or dot path segments.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use authorization code flow with PKCE S256 and \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for the full Recoup catalog, or \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" / \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" for the original limited personal tools.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Public clients should set \", _jsx(_components.code, {\n children: \"token_endpoint_auth_method\"\n }), \" to \", _jsx(_components.code, {\n children: \"none\"\n }), \". Never publish client secrets or private keys.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. \", _jsx(_components.code, {\n children: \"localhost\"\n }), \" and \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \" remain different hosts.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Recoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Metadata caching respects freshness headers up to five minutes. \", _jsx(_components.code, {\n children: \"no-store\"\n }), \", \", _jsx(_components.code, {\n children: \"no-cache\"\n }), \", absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"verification-status\",\n children: \"Verification status\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"Connect an agent\"\n }), \" were obtained using DCR.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Production verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See the \", _jsx(_components.a, {\n href: \"https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization\",\n children: \"MCP authorization specification\"\n }), \" and \", _jsx(_components.a, {\n href: \"https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html\",\n children: \"CIMD draft 02\"\n }), \". CIMD remains a draft specification; Recoup's provider currently implements draft 02.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Published client metadata (CIMD) Connect using an HTTPS client identity without dynamic registration. Quickstart Getting started Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth `client_id`. Recoup retrieves that document and validates the client's callbacks before asking you to approve access. Use the same MCP server URL: `https://api.recoupable.dev/mcp`. A compatible client can discover CIMD through `client_id_metadata_document_supported: true` in Recoup's [authorization-server metadata](https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth). No vendor-specific registration or callback allowlist is needed. ## Access and trust CIMD uses the same [permissions and consent](/mcp-oauth) as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work. A client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account. ## Client requirements - Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected. - Set `client_id` to the exact document URL and include `client_name` and `redirect_uris`. - Use a document URL with an explicit path and without credentials, fragments, or dot path segments. - Use authorization code flow with PKCE S256 and `mcp:tools` for the full Recoup catalog, or `mcp:read` / `mcp:write` for the original limited personal tools. - Public clients should set `token_endpoint_auth_method` to `none`. Never publish client secrets or private keys. - Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. `localhost` and `127.0.0.1` remain different hosts. Recoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy. Metadata caching respects freshness headers up to five minutes. `no-store`, `no-cache`, absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata. ## Verification status The implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits. A local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on [Connect an agent](/mcp-oauth) were obtained using DCR. Production verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified. If a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored. See the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and [CIMD draft 02](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html). CIMD remains a draft specification; Recoup's provider currently implements draft 02. "},{"slug":"authentication","title":"Authentication","description":"How authentication works in the Recoup API — API keys, access tokens, and organization access control.","category":"Quickstart","group":"Getting started","source":"authentication.mdx","body":"## Overview\n\nEvery request to the Recoup API must be authenticated using exactly one of two mechanisms:\n\n| Method | Header | Use case |\n|--------|--------|----------|\n| API Key | `x-api-key` | Server-to-server integrations |\n| Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy |\n\nProviding both headers in the same request will result in a `401` error.\n\n\nAgent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details.\n\n\n---\n\n## API Keys\n\nAPI 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.\n\n### Creating an API Key\n\n1. Navigate to [chat.recoupable.dev/keys](https://chat.recoupable.dev/keys)\n2. Enter a descriptive name (e.g. `\"Production Server\"`)\n3. Click **Create API Key**\n\n\nCopy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation.\n\n\n### Using an API Key\n\nPass your key in the `x-api-key` header:\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n### Access to Organizations\n\nIf 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.\n\n- **No org membership** — the key can only access its own account's data\n- **Org member** — the key can pass `account_id` to filter to any account within that organization\n\n\nOrg 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.\n\n\n---\n\n## Access Tokens (Privy)\n\nIf 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.\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"Authorization: Bearer YOUR_PRIVY_JWT\"\n```\n\nThe 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.\n\n---\n\n## How We Verify Access on API Calls\n\nEvery authenticated request goes through `validateAuthContext`, which enforces the following access rules:\n\n### API Key or Bearer Token\n\nBy default, requests access the key owner's own account. When `account_id` is provided:\n\n```\nRequest includes account_id override?\n ├── Same as key owner → Allowed (self-access)\n ├── Key owner is a member of an org that contains account_id → Allowed\n └── No matching org membership → 403 Forbidden\n```\n\nMembership 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.\n\n\nThe Recoup internal admin organization has universal access to all accounts.\n\n\n### Organization Access via `organization_id`\n\nSome endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either:\n\n- A **member** of the organization, or\n- The **organization account itself**\n\n---\n\n## Error Responses\n\n| Status | Cause |\n|--------|-------|\n| `401` | Missing or invalid credentials, or both `x-api-key` and `Authorization` headers provided |\n| `403` | Valid credentials but insufficient access to the requested `account_id` or `organization_id` |\n\n---\n\n## Security Notes\n\n- API keys are **never stored in plaintext** — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database\n- **Never include `account_id` in your API key creation request** — the account is always derived from your authenticated credentials\n- Rotate keys immediately if compromised via the [API Keys Management Page](https://chat.recoupable.dev/keys)\n\n## MCP OAuth and REST credentials\n\nRemote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See [MCP OAuth](/mcp-oauth).\n","headings":[{"title":"Overview","id":"overview"},{"title":"API Keys","id":"api-keys"},{"title":"Access Tokens (Privy)","id":"access-tokens-privy"},{"title":"How We Verify Access on API Calls","id":"how-we-verify-access-on-api-calls"},{"title":"Error Responses","id":"error-responses"},{"title":"Security Notes","id":"security-notes"},{"title":"MCP OAuth and REST credentials","id":"mcp-oauth-and-rest-credentials"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n }, {Info, Note, Warning} = _components;\n if (!Info) _missingMdxReference(\"Info\", true);\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"overview\",\n children: \"Overview\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Every request to the Recoup API must be authenticated using exactly one of two mechanisms:\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Method\"\n }), _jsx(_components.th, {\n children: \"Header\"\n }), _jsx(_components.th, {\n children: \"Use case\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"API Key\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"x-api-key\"\n })\n }), _jsx(_components.td, {\n children: \"Server-to-server integrations\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Access Token\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"Authorization: Bearer \"\n })\n }), _jsx(_components.td, {\n children: \"Frontend apps authenticated via Privy\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Providing both headers in the same request will result in a \", _jsx(_components.code, {\n children: \"401\"\n }), \" error.\"]\n }), \"\\n\", _jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"Agent onboarding endpoints (\", _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" and \", _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \") are \", _jsx(_components.strong, {\n children: \"unauthenticated\"\n }), \" — they exist so agents can obtain their first API key. See the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents guide\"\n }), \" for details.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"api-keys\",\n children: \"API Keys\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are \", _jsx(_components.strong, {\n children: \"personal keys\"\n }), \" — they are always tied to the account that created them.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"creating-an-api-key\",\n children: \"Creating an API Key\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"chat.recoupable.dev/keys\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Enter a descriptive name (e.g. \", _jsx(_components.code, {\n children: \"\\\"Production Server\\\"\"\n }), \")\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Click \", _jsx(_components.strong, {\n children: \"Create API Key\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"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.\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"using-an-api-key\",\n children: \"Using an API Key\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass your key in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"access-to-organizations\",\n children: \"Access to Organizations\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If your account belongs to one or more organizations, your API key can access data across those organizations by passing an \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" parameter on supported endpoints. This lets you filter to any account within an organization your key has access to.\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"No org membership\"\n }), \" — the key can only access its own account's data\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Org member\"\n }), \" — the key can pass \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" to filter to any account within that organization\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Info, {\n children: _jsxs(_components.p, {\n children: [\"Org membership is determined by the account's \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: \"organizations\"\n }), \". An account gains access to an org when it is added as a member.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"access-tokens-privy\",\n children: \"Access Tokens (Privy)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you're building a frontend application that authenticates users via \", _jsx(_components.a, {\n href: \"https://privy.io\",\n children: \"Privy\"\n }), \", you can pass the user's Privy JWT as a Bearer token instead of an API key.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"Authorization: Bearer YOUR_PRIVY_JWT\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"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.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"how-we-verify-access-on-api-calls\",\n children: \"How We Verify Access on API Calls\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Every authenticated request goes through \", _jsx(_components.code, {\n children: \"validateAuthContext\"\n }), \", which enforces the following access rules:\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"api-key-or-bearer-token\",\n children: \"API Key or Bearer Token\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"By default, requests access the key owner's own account. When \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" is provided:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"Request includes account_id override?\\n ├── Same as key owner → Allowed (self-access)\\n ├── Key owner is a member of an org that contains account_id → Allowed\\n └── No matching org membership → 403 Forbidden\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Membership is verified by checking the key owner's \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: \"organizations\"\n }), \" for a record linking the account to the target account's organization.\"]\n }), \"\\n\", _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"The Recoup internal admin organization has universal access to all accounts.\"\n })\n }), \"\\n\", _jsxs(_components.h3, {\n id: \"organization-access-via-organizationid\",\n children: [\"Organization Access via \", _jsx(_components.code, {\n children: \"organization_id\"\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Some endpoints accept an \", _jsx(_components.code, {\n children: \"organization_id\"\n }), \" parameter. When provided, the API additionally validates that the authenticated account is either:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"A \", _jsx(_components.strong, {\n children: \"member\"\n }), \" of the organization, or\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The \", _jsx(_components.strong, {\n children: \"organization account itself\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"error-responses\",\n children: \"Error Responses\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Status\"\n }), _jsx(_components.th, {\n children: \"Cause\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"401\"\n })\n }), _jsxs(_components.td, {\n children: [\"Missing or invalid credentials, or both \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" and \", _jsx(_components.code, {\n children: \"Authorization\"\n }), \" headers provided\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"403\"\n })\n }), _jsxs(_components.td, {\n children: [\"Valid credentials but insufficient access to the requested \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" or \", _jsx(_components.code, {\n children: \"organization_id\"\n })]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"security-notes\",\n children: \"Security Notes\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"API keys are \", _jsx(_components.strong, {\n children: \"never stored in plaintext\"\n }), \" — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsxs(_components.strong, {\n children: [\"Never include \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" in your API key creation request\"]\n }), \" — the account is always derived from your authenticated credentials\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Rotate keys immediately if compromised via the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys Management Page\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"mcp-oauth-and-rest-credentials\",\n children: \"MCP OAuth and REST credentials\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Remote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Authentication How authentication works in the Recoup API — API keys, access tokens, and organization access control. Quickstart Getting started ## Overview Every request to the Recoup API must be authenticated using exactly one of two mechanisms: | Method | Header | Use case | |--------|--------|----------| | API Key | `x-api-key` | Server-to-server integrations | | Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy | Providing both headers in the same request will result in a `401` error. Agent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details. --- ## 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.dev/keys](https://chat.recoupable.dev/keys) 2. Enter a descriptive name (e.g. `\"Production Server\"`) 3. Click **Create API Key** Copy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation. ### Using an API Key Pass your key in the `x-api-key` header: ### 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 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. --- ## Access Tokens (Privy) If you're building a frontend application that authenticates users via [Privy](https://privy.io), you can pass the user's Privy JWT as a Bearer token instead of an API key. 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. --- ## How We Verify Access on API Calls Every authenticated request goes through `validateAuthContext`, which enforces the following access rules: ### API Key or Bearer Token By default, requests access the key owner's own account. When `account_id` is provided: Membership is verified by checking the key owner's [organizations](/api-reference/organizations/list) for a record linking the account to the target account's organization. The Recoup internal admin organization has universal access to all accounts. ### Organization Access via `organization_id` Some endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either: - A **member** of the organization, or - The **organization account itself** --- ## Error Responses | 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.dev/keys) ## MCP OAuth and REST credentials Remote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See [MCP OAuth](/mcp-oauth). "},{"slug":"credits","title":"Credits","description":"How Recoup credits work — what's billed, how to check your balance, and how to upgrade.","category":"Quickstart","group":"Getting started","source":"credits.mdx","body":"Some Recoup endpoints are billed in **credits** — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates.\n\n---\n\n## What's billed\n\n| Family | Billed? | Notes |\n|--------|---------|-------|\n| **Research** ([`/api/research/*`](/api-reference/research/web)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). |\n| **Content generation** ([`/api/content/image`](/api-reference/content/generate-image), [`video`](/api-reference/content/generate-video), upscale, transcribe and analyze) | Yes | Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory. |\n| **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. |\n| **Music analysis** ([`POST /api/songs/analyze`](/api-reference/songs/analyze)) | Yes | \\$0.05 per model call plus \\$0.001166 per second of inference time; `full_report` is the sum of its 13 calls. |\n| **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | \\$0.05, plus \\$0.01 per post requested via `posts` — per social profile scraped. |\n| **Other operations** | Consult the endpoint contract | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. |\n\nUpstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient.\n\n---\n\n## What a credit is worth\n\n**Balances and prices are US dollars.** The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: `1,000,000 = $1.00`, so it can carry sub-cent charges (a \\$0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get).\n\n---\n\n## Check your balance\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/credits \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nResponse shape:\n\n```json\n{\n \"account_id\": \"11111111-1111-4111-8111-111111111111\",\n \"remaining_credits\": 292450000,\n \"total_credits\": 300000000,\n \"used_credits\": 7550000,\n \"is_pro\": true,\n \"plan\": \"pro\",\n \"task_limit\": null,\n \"min_cadence_minutes\": 60,\n \"timestamp\": \"2026-10-01T12:00:00Z\"\n}\n```\n\n`plan`, `task_limit`, and `min_cadence_minutes` describe the [plan](#subscription) the balance belongs to. `total_credits` is your plan-derived monthly allotment. `remaining_credits` can exceed `total_credits` after a top-up or an admin grant, and `used_credits` clamps to 0 in that case. Full schema at [Get Account Credits](/api-reference/accounts/credits-get).\n\n### Plan response examples\n\n`is_pro` on credits and `isPro` on subscriptions mean effective Pro, so both are\nfalse for paid Starter. Use `plan` to distinguish Starter from Free. The credits\nresponse reports the effective allowance; the [subscription response](/api-reference/accounts/subscription-get)\nseparately identifies whether it comes from the account or an organization.\n\n| Situation | Credits `plan` / `is_pro` | Subscription `source` | Task limit / minimum cadence |\n| --- | --- | --- | --- |\n| Free | `free` / `false` | `null` | 1 / weekly |\n| Paid Starter | `starter` / `false` | `account` | 3 / daily |\n| Direct Pro | `pro` / `true` | `account` | `null` (unlimited) / hourly |\n| Starter account with organization Pro | `pro` / `true` | `organization` | `null` (unlimited) / hourly |\n| Inactive subscription without another paid entitlement | `free` / `false` | `null` | 1 / weekly |\n\nFor example, a Pro balance of 325,000,000 against an allowance of 300,000,000\nreturns `used_credits: 0`. The API preserves a signed balance: a negative balance\ncan make this display exceed the allowance. This is not a ledger of charges.\nA null timestamp means the timestamp is unavailable, not proof of no prior activity.\nAn inactive subscription resolves to `status: \"none\"` and null subscription/billing\nfields; this endpoint does not return the canceled subscription's history. Billing\ndetails may also be unavailable on an active response. Named reference examples\nillustrate these states without quoting an available offer or a live payment.\n\nTo see what consumed the balance, list the charges line by line with [`GET /api/accounts/{id}/usage`](/api-reference/accounts/usage-get): one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in `model_id` (for example `POST /api/artist/socials/scrape`), so a list of charges reads as a list of calls.\n\n---\n\n## Subscription\n\nFor Platform, Advisory, Build + Partner, and Enterprise options, see [Recoup pricing](https://recoupable.dev/pricing). API and MCP usage is billed separately through credits.\n\nYour account's current credit allowance and scheduled-task limits are returned by [Get Account Credits](/api-reference/accounts/credits-get). Use `total_credits`, `task_limit`, and `min_cadence_minutes` from that response rather than inferring limits from a public plan name.\n\nThe API may return account identifiers such as `free`, `starter`, or `pro`. These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint.\n\n### Task limits\n\n[`POST /api/tasks`](/api-reference/tasks/create) and [`PATCH /api/tasks`](/api-reference/tasks/update) [check the plan](/api-reference/accounts/credits-get) before writing. Creating a task past `task_limit`, re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than `min_cadence_minutes` returns **HTTP 402** with `error: \"plan_limit\"`:\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"plan_limit\",\n \"limit\": \"task_count\",\n \"message\": \"Free includes 1 task. Starter includes 3, Pro is unlimited.\",\n \"plan\": \"free\",\n \"task_limit\": 1,\n \"min_cadence_minutes\": 10080,\n \"current_task_count\": 1,\n \"billingUrl\": \"https://app.recoupable.dev/plan\"\n}\n```\n\n`limit` is `task_count` or `min_cadence`; `current_task_count` excludes the task being created or updated. Edits that only touch `title`, `prompt`, or `model` never hit the gate.\n\n### Monthly refill\n\nThe refill is a **floor, not an assignment.** It raises `remaining_credits` up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a [top-up](#one-time-top-ups) or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar.\n\nThe refill is lazy rather than scheduled: it applies on the next read of [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get) once your credits row is more than a month old. The balance you read is always the refilled one.\n\n### Manage your subscription\n\nSign in to your [account billing page](https://app.recoupable.dev/plan) to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in [Create Subscription Session](/api-reference/subscriptions/sessions-create) and open its returned checkout URL. Review the price and billing terms before completing checkout.\n\nAdvisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment.\n\n### Check your tier\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/subscription \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nGet `$ACCOUNT_ID` from [`GET /api/accounts/id`](/api-reference/accounts/id) if you don't already have it. Response includes `isPro` (boolean), `status`, `plan`, and `source` (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at [Get Subscription](/api-reference/accounts/subscription-get).\n\n### One-time top-ups\n\nYou can purchase credits any time via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create). The endpoint adapts to what's on the account:\n\n- **Card on file → silent auto-charge.** Recoup charges your saved Stripe card off-session and returns `paymentIntentId`, `creditsPurchased`, and `totalCents`. Credits land within seconds.\n- **No card, or Stripe declines the saved card → Stripe Checkout fallback.** The response contains a Checkout `url` you open in the browser. When Stripe specifically declined a saved card, the response also includes a `declineReason` (e.g. `insufficient_funds`, `expired_card`) so you can explain *why* before sending the customer to update billing.\n\n```bash\ncurl -sS -X POST https://api.recoupable.dev/api/credits/sessions \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"credits\": 1000000, \"successUrl\": \"https://chat.recoupable.dev/credits/success\"}'\n```\n\nFull request/response schema at [Create Credits Top-Up Session](/api-reference/credits/sessions-create).\n\n### Check which card will be charged\n\nBefore triggering a silent off-session charge, inspect the default payment method on file:\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/payment-method \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nResponse shape:\n\n```json\n{\n \"account_id\": \"11111111-1111-4111-8111-111111111111\",\n \"card\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"exp_month\": 12,\n \"exp_year\": 2026,\n \"funding\": \"credit\"\n }\n}\n```\n\n`card` is `null` when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original `exp_month` / `exp_year`); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at [Get Default Payment Method](/api-reference/accounts/payment-method-get).\n\n---\n\n## Running out of credits\n\nEvery billed API request runs a credit gate before it executes. If `remaining_credits` doesn't cover the request's cost, the request stops there and returns **HTTP 402**. Nothing is charged and no Stripe object is created.\n\nThe decision tree:\n\n1. **Enough credits?** → Request proceeds, credits deducted on success.\n2. **Short?** → Request returns **HTTP 402** with the balance, the cost, and a link to billing.\n\nA card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through [`POST /api/credits/sessions`](/api-reference/credits/sessions-create), or when the account has turned on auto top-up. Saving a card ahead of time via [`POST /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-create) makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on [`/api/accounts/{id}/subscription`](/api-reference/accounts/subscription-get), [`/api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-get), and [`/api/accounts/{id}/payments`](/api-reference/accounts/payments-get); pass an organization id as `{id}` to read the organization's billing.\n\n### Auto top-up (opt-in)\n\nAuto top-up is off for every account until it is turned on with [`PUT /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-update), which needs three things chosen by the account: `enabled`, the `amountCents` to buy each time (5.00 to 1,000.00 USD), and the `thresholdCents` balance that triggers it. Both are USD cents; the `remaining_credits` balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file.\n\nOnce on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as `lastError` (returned by [`GET /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-get)), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself.\n\n### Remove a saved card\n\n[`DELETE /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-delete) turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again.\n\nSuccess returns **204** with no body. If no customer or selected card exists, **404** leaves settings and cards unchanged. A **500** can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card.\n\nThis operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently.\n\n---\n\n## 402 Payment Required\n\nWhen the gate comes up short, billed endpoints return **HTTP 402** with a unified body:\n\n```json\n{\n \"error\": \"insufficient_credits\",\n \"remaining_credits\": 120000,\n \"required_credits\": 1000000,\n \"billingUrl\": \"https://app.recoupable.dev\"\n}\n```\n\n| Field | When it appears | Meaning |\n|-------|-----------------|---------|\n| `error` | Always | Literally `\"insufficient_credits\"` |\n| `remaining_credits` | Always | Account balance at the moment of the failed request |\n| `required_credits` | Always | What this endpoint needed |\n| `billingUrl` | Always | Static link to the Recoup app, where a human can save a card and buy credits |\n\n`billingUrl` is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running.\n\n**How to react:**\n\n- **Browser-driven UI** (e.g., the Recoup chat app): send the customer to `billingUrl`, or call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create) inline and open the `url` it returns.\n- **Programmatic / LLM-driven client**: report `remaining_credits` and `required_credits`, and surface `billingUrl` as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands.\n\n---\n\n## Cost per endpoint\n\nCurrent as of this revision of the page. The authoritative source is the per-endpoint reference docs and the `required_credits` field on any 402 response.\n\n| Endpoint | Cost |\n|----------|------|\n| [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | Variable, priced from the model's token usage; see `required_credits` on a 402 |\n| [Recoup artist and track research](/api-reference/research/search) | \\$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups |\n| [`POST /api/research/people`](/api-reference/research/people) | \\$0.05 per call |\n| [`POST /api/research/web`](/api-reference/research/web) | \\$0.01 per call |\n| [`POST /api/research/extract`](/api-reference/research/extract) | \\$0.05 × number of URLs |\n| [`POST /api/research/enrich`](/api-reference/research/enrich) | \\$0.05 / \\$0.10 / \\$0.25 (base / core / ultra processor) |\n| [`POST /api/research/deep`](/api-reference/research/deep) | \\$0.25 per call |\n| [`POST /api/image/generate`](/api-reference/image/generation) | Per-call price; see endpoint reference |\n| [`POST /api/songs/analyze`](/api-reference/songs/analyze) | `$0.05 + $0.001166 × elapsed_seconds` per model call; `full_report` = 13 calls |\n\n## Billing recovery and units\n\n`insufficient_credits` returns `billingUrl`, a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns `checkoutUrl`; subscription Checkout returns `url`. Inspect the endpoint-specific error type.\n\nTop-ups require `successUrl` on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; `totalCents` is 289 for that example. It is not a credit count. `isPro` means effective Pro only, and is false for paid Starter; use `plan` for paid-plan decisions.\n\nScheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names.\n","headings":[{"title":"What's billed","id":"whats-billed"},{"title":"What a credit is worth","id":"what-a-credit-is-worth"},{"title":"Check your balance","id":"check-your-balance"},{"title":"Subscription","id":"subscription"},{"title":"Running out of credits","id":"running-out-of-credits"},{"title":"402 Payment Required","id":"402-payment-required"},{"title":"Cost per endpoint","id":"cost-per-endpoint"},{"title":"Billing recovery and units","id":"billing-recovery-and-units"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Some Recoup endpoints are billed in \", _jsx(_components.strong, {\n children: \"credits\"\n }), \" — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"whats-billed\",\n children: \"What's billed\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Family\"\n }), _jsx(_components.th, {\n children: \"Billed?\"\n }), _jsx(_components.th, {\n children: \"Notes\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Research\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: _jsx(_components.code, {\n children: \"/api/research/*\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. \", _jsx(_components.a, {\n href: \"/api-reference/research/enrich\",\n children: _jsx(_components.code, {\n children: \"enrich\"\n })\n }), \" charges by processor tier; \", _jsx(_components.a, {\n href: \"/api-reference/research/extract\",\n children: _jsx(_components.code, {\n children: \"extract\"\n })\n }), \" charges by URL count).\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Content generation\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/content/generate-image\",\n children: _jsx(_components.code, {\n children: \"/api/content/image\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/content/generate-video\",\n children: _jsx(_components.code, {\n children: \"video\"\n })\n }), \", upscale, transcribe and analyze)\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"AI Chat — streaming\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/chat/workflow\",\n children: _jsx(_components.code, {\n children: \"POST /api/chat\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Variable cost based on model token usage, with a per-request minimum.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Music analysis\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"$0.05 per model call plus $0.001166 per second of inference time; \", _jsx(_components.code, {\n children: \"full_report\"\n }), \" is the sum of its 13 calls.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Social scrape\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/social/scrape\",\n children: _jsx(_components.code, {\n children: \"/api/socials/{id}/scrape\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/artist/socials-scrape\",\n children: _jsx(_components.code, {\n children: \"/api/artist/socials/scrape\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"$0.05, plus $0.01 per post requested via \", _jsx(_components.code, {\n children: \"posts\"\n }), \" — per social profile scraped.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.strong, {\n children: \"Other operations\"\n })\n }), _jsx(_components.td, {\n children: \"Consult the endpoint contract\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/artists/list\",\n children: \"Artist CRUD\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: \"sandboxes\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/sessions/get\",\n children: \"sessions\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/tasks/get\",\n children: \"scheduled tasks\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: \"account/org management\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/agents/signup\",\n children: \"agent signup\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/spotify/search\",\n children: \"Spotify proxies\"\n }), \", etc. Subscription gating may still apply.\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Upstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"what-a-credit-is-worth\",\n children: \"What a credit is worth\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Balances and prices are US dollars.\"\n }), \" The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: \", _jsx(_components.code, {\n children: \"1,000,000 = $1.00\"\n }), \", so it can carry sub-cent charges (a $0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/credits\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"check-your-balance\",\n children: \"Check your balance\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/credits \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response shape:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"11111111-1111-4111-8111-111111111111\\\",\\n \\\"remaining_credits\\\": 292450000,\\n \\\"total_credits\\\": 300000000,\\n \\\"used_credits\\\": 7550000,\\n \\\"is_pro\\\": true,\\n \\\"plan\\\": \\\"pro\\\",\\n \\\"task_limit\\\": null,\\n \\\"min_cadence_minutes\\\": 60,\\n \\\"timestamp\\\": \\\"2026-10-01T12:00:00Z\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"plan\"\n }), \", \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", and \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" describe the \", _jsx(_components.a, {\n href: \"#subscription\",\n children: \"plan\"\n }), \" the balance belongs to. \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \" is your plan-derived monthly allotment. \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" can exceed \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \" after a top-up or an admin grant, and \", _jsx(_components.code, {\n children: \"used_credits\"\n }), \" clamps to 0 in that case. Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"Get Account Credits\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"plan-response-examples\",\n children: \"Plan response examples\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"is_pro\"\n }), \" on credits and \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" on subscriptions mean effective Pro, so both are\\nfalse for paid Starter. Use \", _jsx(_components.code, {\n children: \"plan\"\n }), \" to distinguish Starter from Free. The credits\\nresponse reports the effective allowance; the \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: \"subscription response\"\n }), \"\\nseparately identifies whether it comes from the account or an organization.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Situation\"\n }), _jsxs(_components.th, {\n children: [\"Credits \", _jsx(_components.code, {\n children: \"plan\"\n }), \" / \", _jsx(_components.code, {\n children: \"is_pro\"\n })]\n }), _jsxs(_components.th, {\n children: [\"Subscription \", _jsx(_components.code, {\n children: \"source\"\n })]\n }), _jsx(_components.th, {\n children: \"Task limit / minimum cadence\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Free\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"free\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"null\"\n })\n }), _jsx(_components.td, {\n children: \"1 / weekly\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Paid Starter\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"starter\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"account\"\n })\n }), _jsx(_components.td, {\n children: \"3 / daily\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Direct Pro\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"pro\"\n }), \" / \", _jsx(_components.code, {\n children: \"true\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"account\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"null\"\n }), \" (unlimited) / hourly\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Starter account with organization Pro\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"pro\"\n }), \" / \", _jsx(_components.code, {\n children: \"true\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"organization\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"null\"\n }), \" (unlimited) / hourly\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Inactive subscription without another paid entitlement\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"free\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"null\"\n })\n }), _jsx(_components.td, {\n children: \"1 / weekly\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For example, a Pro balance of 325,000,000 against an allowance of 300,000,000\\nreturns \", _jsx(_components.code, {\n children: \"used_credits: 0\"\n }), \". The API preserves a signed balance: a negative balance\\ncan make this display exceed the allowance. This is not a ledger of charges.\\nA null timestamp means the timestamp is unavailable, not proof of no prior activity.\\nAn inactive subscription resolves to \", _jsx(_components.code, {\n children: \"status: \\\"none\\\"\"\n }), \" and null subscription/billing\\nfields; this endpoint does not return the canceled subscription's history. Billing\\ndetails may also be unavailable on an active response. Named reference examples\\nillustrate these states without quoting an available offer or a live payment.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To see what consumed the balance, list the charges line by line with \", _jsx(_components.a, {\n href: \"/api-reference/accounts/usage-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/usage\"\n })\n }), \": one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in \", _jsx(_components.code, {\n children: \"model_id\"\n }), \" (for example \", _jsx(_components.code, {\n children: \"POST /api/artist/socials/scrape\"\n }), \"), so a list of charges reads as a list of calls.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"subscription\",\n children: \"Subscription\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For Platform, Advisory, Build + Partner, and Enterprise options, see \", _jsx(_components.a, {\n href: \"https://recoupable.dev/pricing\",\n children: \"Recoup pricing\"\n }), \". API and MCP usage is billed separately through credits.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Your account's current credit allowance and scheduled-task limits are returned by \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"Get Account Credits\"\n }), \". Use \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \", \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", and \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" from that response rather than inferring limits from a public plan name.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The API may return account identifiers such as \", _jsx(_components.code, {\n children: \"free\"\n }), \", \", _jsx(_components.code, {\n children: \"starter\"\n }), \", or \", _jsx(_components.code, {\n children: \"pro\"\n }), \". These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"task-limits\",\n children: \"Task limits\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/tasks/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/tasks\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/tasks/update\",\n children: _jsx(_components.code, {\n children: \"PATCH /api/tasks\"\n })\n }), \" \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"check the plan\"\n }), \" before writing. Creating a task past \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with \", _jsx(_components.code, {\n children: \"error: \\\"plan_limit\\\"\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"status\\\": \\\"error\\\",\\n \\\"error\\\": \\\"plan_limit\\\",\\n \\\"limit\\\": \\\"task_count\\\",\\n \\\"message\\\": \\\"Free includes 1 task. Starter includes 3, Pro is unlimited.\\\",\\n \\\"plan\\\": \\\"free\\\",\\n \\\"task_limit\\\": 1,\\n \\\"min_cadence_minutes\\\": 10080,\\n \\\"current_task_count\\\": 1,\\n \\\"billingUrl\\\": \\\"https://app.recoupable.dev/plan\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"limit\"\n }), \" is \", _jsx(_components.code, {\n children: \"task_count\"\n }), \" or \", _jsx(_components.code, {\n children: \"min_cadence\"\n }), \"; \", _jsx(_components.code, {\n children: \"current_task_count\"\n }), \" excludes the task being created or updated. Edits that only touch \", _jsx(_components.code, {\n children: \"title\"\n }), \", \", _jsx(_components.code, {\n children: \"prompt\"\n }), \", or \", _jsx(_components.code, {\n children: \"model\"\n }), \" never hit the gate.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"monthly-refill\",\n children: \"Monthly refill\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The refill is a \", _jsx(_components.strong, {\n children: \"floor, not an assignment.\"\n }), \" It raises \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a \", _jsx(_components.a, {\n href: \"#one-time-top-ups\",\n children: \"top-up\"\n }), \" or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The refill is lazy rather than scheduled: it applies on the next read of \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/credits\"\n })\n }), \" once your credits row is more than a month old. The balance you read is always the refilled one.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"manage-your-subscription\",\n children: \"Manage your subscription\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sign in to your \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/plan\",\n children: \"account billing page\"\n }), \" to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in \", _jsx(_components.a, {\n href: \"/api-reference/subscriptions/sessions-create\",\n children: \"Create Subscription Session\"\n }), \" and open its returned checkout URL. Review the price and billing terms before completing checkout.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Advisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"check-your-tier\",\n children: \"Check your tier\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/subscription \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Get \", _jsx(_components.code, {\n children: \"$ACCOUNT_ID\"\n }), \" from \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n })\n }), \" if you don't already have it. Response includes \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" (boolean), \", _jsx(_components.code, {\n children: \"status\"\n }), \", \", _jsx(_components.code, {\n children: \"plan\"\n }), \", and \", _jsx(_components.code, {\n children: \"source\"\n }), \" (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: \"Get Subscription\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"one-time-top-ups\",\n children: \"One-time top-ups\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"You can purchase credits any time via \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \". The endpoint adapts to what's on the account:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Card on file → silent auto-charge.\"\n }), \" Recoup charges your saved Stripe card off-session and returns \", _jsx(_components.code, {\n children: \"paymentIntentId\"\n }), \", \", _jsx(_components.code, {\n children: \"creditsPurchased\"\n }), \", and \", _jsx(_components.code, {\n children: \"totalCents\"\n }), \". Credits land within seconds.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"No card, or Stripe declines the saved card → Stripe Checkout fallback.\"\n }), \" The response contains a Checkout \", _jsx(_components.code, {\n children: \"url\"\n }), \" you open in the browser. When Stripe specifically declined a saved card, the response also includes a \", _jsx(_components.code, {\n children: \"declineReason\"\n }), \" (e.g. \", _jsx(_components.code, {\n children: \"insufficient_funds\"\n }), \", \", _jsx(_components.code, {\n children: \"expired_card\"\n }), \") so you can explain \", _jsx(_components.em, {\n children: \"why\"\n }), \" before sending the customer to update billing.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS -X POST https://api.recoupable.dev/api/credits/sessions \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"credits\\\": 1000000, \\\"successUrl\\\": \\\"https://chat.recoupable.dev/credits/success\\\"}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Full request/response schema at \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: \"Create Credits Top-Up Session\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"check-which-card-will-be-charged\",\n children: \"Check which card will be charged\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before triggering a silent off-session charge, inspect the default payment method on file:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/payment-method \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response shape:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"11111111-1111-4111-8111-111111111111\\\",\\n \\\"card\\\": {\\n \\\"brand\\\": \\\"visa\\\",\\n \\\"last4\\\": \\\"4242\\\",\\n \\\"exp_month\\\": 12,\\n \\\"exp_year\\\": 2026,\\n \\\"funding\\\": \\\"credit\\\"\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"card\"\n }), \" is \", _jsx(_components.code, {\n children: \"null\"\n }), \" when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original \", _jsx(_components.code, {\n children: \"exp_month\"\n }), \" / \", _jsx(_components.code, {\n children: \"exp_year\"\n }), \"); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-get\",\n children: \"Get Default Payment Method\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"running-out-of-credits\",\n children: \"Running out of credits\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Every billed API request runs a credit gate before it executes. If \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" doesn't cover the request's cost, the request stops there and returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \". Nothing is charged and no Stripe object is created.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The decision tree:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Enough credits?\"\n }), \" → Request proceeds, credits deducted on success.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Short?\"\n }), \" → Request returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with the balance, the cost, and a link to billing.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \", or when the account has turned on auto top-up. Saving a card ahead of time via \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/accounts/{id}/payment-method\"\n })\n }), \" makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/subscription\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/payment-method\"\n })\n }), \", and \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payments-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/payments\"\n })\n }), \"; pass an organization id as \", _jsx(_components.code, {\n children: \"{id}\"\n }), \" to read the organization's billing.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"auto-top-up-opt-in\",\n children: \"Auto top-up (opt-in)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Auto top-up is off for every account until it is turned on with \", _jsx(_components.a, {\n href: \"/api-reference/accounts/auto-top-up-update\",\n children: _jsx(_components.code, {\n children: \"PUT /api/accounts/{id}/auto-top-up\"\n })\n }), \", which needs three things chosen by the account: \", _jsx(_components.code, {\n children: \"enabled\"\n }), \", the \", _jsx(_components.code, {\n children: \"amountCents\"\n }), \" to buy each time (5.00 to 1,000.00 USD), and the \", _jsx(_components.code, {\n children: \"thresholdCents\"\n }), \" balance that triggers it. Both are USD cents; the \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as \", _jsx(_components.code, {\n children: \"lastError\"\n }), \" (returned by \", _jsx(_components.a, {\n href: \"/api-reference/accounts/auto-top-up-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/auto-top-up\"\n })\n }), \"), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"remove-a-saved-card\",\n children: \"Remove a saved card\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-delete\",\n children: _jsx(_components.code, {\n children: \"DELETE /api/accounts/{id}/payment-method\"\n })\n }), \" turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Success returns \", _jsx(_components.strong, {\n children: \"204\"\n }), \" with no body. If no customer or selected card exists, \", _jsx(_components.strong, {\n children: \"404\"\n }), \" leaves settings and cards unchanged. A \", _jsx(_components.strong, {\n children: \"500\"\n }), \" can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"402-payment-required\",\n children: \"402 Payment Required\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"When the gate comes up short, billed endpoints return \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with a unified body:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"error\\\": \\\"insufficient_credits\\\",\\n \\\"remaining_credits\\\": 120000,\\n \\\"required_credits\\\": 1000000,\\n \\\"billingUrl\\\": \\\"https://app.recoupable.dev\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Field\"\n }), _jsx(_components.th, {\n children: \"When it appears\"\n }), _jsx(_components.th, {\n children: \"Meaning\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"error\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsxs(_components.td, {\n children: [\"Literally \", _jsx(_components.code, {\n children: \"\\\"insufficient_credits\\\"\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"remaining_credits\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"Account balance at the moment of the failed request\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"required_credits\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"What this endpoint needed\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"billingUrl\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"Static link to the Recoup app, where a human can save a card and buy credits\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"billingUrl\"\n }), \" is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"How to react:\"\n })\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Browser-driven UI\"\n }), \" (e.g., the Recoup chat app): send the customer to \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \", or call \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \" inline and open the \", _jsx(_components.code, {\n children: \"url\"\n }), \" it returns.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Programmatic / LLM-driven client\"\n }), \": report \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" and \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \", and surface \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \" as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"cost-per-endpoint\",\n children: \"Cost per endpoint\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Current as of this revision of the page. The authoritative source is the per-endpoint reference docs and the \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \" field on any 402 response.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Endpoint\"\n }), _jsx(_components.th, {\n children: \"Cost\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/chat/workflow\",\n children: _jsx(_components.code, {\n children: \"POST /api/chat\"\n })\n }), \" (streaming)\"]\n }), _jsxs(_components.td, {\n children: [\"Variable, priced from the model's token usage; see \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \" on a 402\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/search\",\n children: \"Recoup artist and track research\"\n })\n }), _jsx(_components.td, {\n children: \"$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/people\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/people\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/web\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.01 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/extract\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/extract\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 × number of URLs\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/enrich\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/enrich\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 / $0.10 / $0.25 (base / core / ultra processor)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/deep\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/deep\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.25 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/image/generation\",\n children: _jsx(_components.code, {\n children: \"POST /api/image/generate\"\n })\n })\n }), _jsx(_components.td, {\n children: \"Per-call price; see endpoint reference\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"$0.05 + $0.001166 × elapsed_seconds\"\n }), \" per model call; \", _jsx(_components.code, {\n children: \"full_report\"\n }), \" = 13 calls\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"billing-recovery-and-units\",\n children: \"Billing recovery and units\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"insufficient_credits\"\n }), \" returns \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \", a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns \", _jsx(_components.code, {\n children: \"checkoutUrl\"\n }), \"; subscription Checkout returns \", _jsx(_components.code, {\n children: \"url\"\n }), \". Inspect the endpoint-specific error type.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Top-ups require \", _jsx(_components.code, {\n children: \"successUrl\"\n }), \" on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; \", _jsx(_components.code, {\n children: \"totalCents\"\n }), \" is 289 for that example. It is not a credit count. \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" means effective Pro only, and is false for paid Starter; use \", _jsx(_components.code, {\n children: \"plan\"\n }), \" for paid-plan decisions.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Scheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Credits How Recoup credits work — what's billed, how to check your balance, and how to upgrade. Quickstart Getting started Some Recoup endpoints are billed in **credits** — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates. --- ## What's billed | Family | Billed? | Notes | |--------|---------|-------| | **Research** ([`/api/research/*`](/api-reference/research/web)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). | | **Content generation** ([`/api/content/image`](/api-reference/content/generate-image), [`video`](/api-reference/content/generate-video), upscale, transcribe and analyze) | Yes | Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory. | | **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. | | **Music analysis** ([`POST /api/songs/analyze`](/api-reference/songs/analyze)) | Yes | \\$0.05 per model call plus \\$0.001166 per second of inference time; `full_report` is the sum of its 13 calls. | | **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | \\$0.05, plus \\$0.01 per post requested via `posts` — per social profile scraped. | | **Other operations** | Consult the endpoint contract | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. | Upstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient. --- ## What a credit is worth **Balances and prices are US dollars.** The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: `1,000,000 = $1.00`, so it can carry sub-cent charges (a \\$0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get). --- ## Check your balance Response shape: `plan`, `task_limit`, and `min_cadence_minutes` describe the [plan](#subscription) the balance belongs to. `total_credits` is your plan-derived monthly allotment. `remaining_credits` can exceed `total_credits` after a top-up or an admin grant, and `used_credits` clamps to 0 in that case. Full schema at [Get Account Credits](/api-reference/accounts/credits-get). ### Plan response examples `is_pro` on credits and `isPro` on subscriptions mean effective Pro, so both are false for paid Starter. Use `plan` to distinguish Starter from Free. The credits response reports the effective allowance; the [subscription response](/api-reference/accounts/subscription-get) separately identifies whether it comes from the account or an organization. | Situation | Credits `plan` / `is_pro` | Subscription `source` | Task limit / minimum cadence | | --- | --- | --- | --- | | Free | `free` / `false` | `null` | 1 / weekly | | Paid Starter | `starter` / `false` | `account` | 3 / daily | | Direct Pro | `pro` / `true` | `account` | `null` (unlimited) / hourly | | Starter account with organization Pro | `pro` / `true` | `organization` | `null` (unlimited) / hourly | | Inactive subscription without another paid entitlement | `free` / `false` | `null` | 1 / weekly | For example, a Pro balance of 325,000,000 against an allowance of 300,000,000 returns `used_credits: 0`. The API preserves a signed balance: a negative balance can make this display exceed the allowance. This is not a ledger of charges. A null timestamp means the timestamp is unavailable, not proof of no prior activity. An inactive subscription resolves to `status: \"none\"` and null subscription/billing fields; this endpoint does not return the canceled subscription's history. Billing details may also be unavailable on an active response. Named reference examples illustrate these states without quoting an available offer or a live payment. To see what consumed the balance, list the charges line by line with [`GET /api/accounts/{id}/usage`](/api-reference/accounts/usage-get): one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in `model_id` (for example `POST /api/artist/socials/scrape`), so a list of charges reads as a list of calls. --- ## Subscription For Platform, Advisory, Build + Partner, and Enterprise options, see [Recoup pricing](https://recoupable.dev/pricing). API and MCP usage is billed separately through credits. Your account's current credit allowance and scheduled-task limits are returned by [Get Account Credits](/api-reference/accounts/credits-get). Use `total_credits`, `task_limit`, and `min_cadence_minutes` from that response rather than inferring limits from a public plan name. The API may return account identifiers such as `free`, `starter`, or `pro`. These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint. ### Task limits [`POST /api/tasks`](/api-reference/tasks/create) and [`PATCH /api/tasks`](/api-reference/tasks/update) [check the plan](/api-reference/accounts/credits-get) before writing. Creating a task past `task_limit`, re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than `min_cadence_minutes` returns **HTTP 402** with `error: \"plan_limit\"`: `limit` is `task_count` or `min_cadence`; `current_task_count` excludes the task being created or updated. Edits that only touch `title`, `prompt`, or `model` never hit the gate. ### Monthly refill The refill is a **floor, not an assignment.** It raises `remaining_credits` up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a [top-up](#one-time-top-ups) or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar. The refill is lazy rather than scheduled: it applies on the next read of [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get) once your credits row is more than a month old. The balance you read is always the refilled one. ### Manage your subscription Sign in to your [account billing page](https://app.recoupable.dev/plan) to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in [Create Subscription Session](/api-reference/subscriptions/sessions-create) and open its returned checkout URL. Review the price and billing terms before completing checkout. Advisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment. ### Check your tier Get `$ACCOUNT_ID` from [`GET /api/accounts/id`](/api-reference/accounts/id) if you don't already have it. Response includes `isPro` (boolean), `status`, `plan`, and `source` (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at [Get Subscription](/api-reference/accounts/subscription-get). ### One-time top-ups You can purchase credits any time via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create). The endpoint adapts to what's on the account: - **Card on file → silent auto-charge.** Recoup charges your saved Stripe card off-session and returns `paymentIntentId`, `creditsPurchased`, and `totalCents`. Credits land within seconds. - **No card, or Stripe declines the saved card → Stripe Checkout fallback.** The response contains a Checkout `url` you open in the browser. When Stripe specifically declined a saved card, the response also includes a `declineReason` (e.g. `insufficient_funds`, `expired_card`) so you can explain *why* before sending the customer to update billing. Full request/response schema at [Create Credits Top-Up Session](/api-reference/credits/sessions-create). ### Check which card will be charged Before triggering a silent off-session charge, inspect the default payment method on file: Response shape: `card` is `null` when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original `exp_month` / `exp_year`); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at [Get Default Payment Method](/api-reference/accounts/payment-method-get). --- ## Running out of credits Every billed API request runs a credit gate before it executes. If `remaining_credits` doesn't cover the request's cost, the request stops there and returns **HTTP 402**. Nothing is charged and no Stripe object is created. The decision tree: 1. **Enough credits?** → Request proceeds, credits deducted on success. 2. **Short?** → Request returns **HTTP 402** with the balance, the cost, and a link to billing. A card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through [`POST /api/credits/sessions`](/api-reference/credits/sessions-create), or when the account has turned on auto top-up. Saving a card ahead of time via [`POST /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-create) makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on [`/api/accounts/{id}/subscription`](/api-reference/accounts/subscription-get), [`/api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-get), and [`/api/accounts/{id}/payments`](/api-reference/accounts/payments-get); pass an organization id as `{id}` to read the organization's billing. ### Auto top-up (opt-in) Auto top-up is off for every account until it is turned on with [`PUT /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-update), which needs three things chosen by the account: `enabled`, the `amountCents` to buy each time (5.00 to 1,000.00 USD), and the `thresholdCents` balance that triggers it. Both are USD cents; the `remaining_credits` balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file. Once on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as `lastError` (returned by [`GET /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-get)), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself. ### Remove a saved card [`DELETE /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-delete) turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again. Success returns **204** with no body. If no customer or selected card exists, **404** leaves settings and cards unchanged. A **500** can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card. This operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently. --- ## 402 Payment Required When the gate comes up short, billed endpoints return **HTTP 402** with a unified body: | Field | When it appears | Meaning | |-------|-----------------|---------| | `error` | Always | Literally `\"insufficient_credits\"` | | `remaining_credits` | Always | Account balance at the moment of the failed request | | `required_credits` | Always | What this endpoint needed | | `billingUrl` | Always | Static link to the Recoup app, where a human can save a card and buy credits | `billingUrl` is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running. **How to react:** - **Browser-driven UI** (e.g., the Recoup chat app): send the customer to `billingUrl`, or call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create) inline and open the `url` it returns. - **Programmatic / LLM-driven client**: report `remaining_credits` and `required_credits`, and surface `billingUrl` as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands. --- ## Cost per endpoint Current as of this revision of the page. The authoritative source is the per-endpoint reference docs and the `required_credits` field on any 402 response. | Endpoint | Cost | |----------|------| | [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | Variable, priced from the model's token usage; see `required_credits` on a 402 | | [Recoup artist and track research](/api-reference/research/search) | \\$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups | | [`POST /api/research/people`](/api-reference/research/people) | \\$0.05 per call | | [`POST /api/research/web`](/api-reference/research/web) | \\$0.01 per call | | [`POST /api/research/extract`](/api-reference/research/extract) | \\$0.05 × number of URLs | | [`POST /api/research/enrich`](/api-reference/research/enrich) | \\$0.05 / \\$0.10 / \\$0.25 (base / core / ultra processor) | | [`POST /api/research/deep`](/api-reference/research/deep) | \\$0.25 per call | | [`POST /api/image/generate`](/api-reference/image/generation) | Per-call price; see endpoint reference | | [`POST /api/songs/analyze`](/api-reference/songs/analyze) | `$0.05 + $0.001166 × elapsed_seconds` per model call; `full_report` = 13 calls | ## Billing recovery and units `insufficient_credits` returns `billingUrl`, a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns `checkoutUrl`; subscription Checkout returns `url`. Inspect the endpoint-specific error type. Top-ups require `successUrl` on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; `totalCents` is 289 for that example. It is not a credit count. `isPro` means effective Pro only, and is false for paid Starter; use `plan` for paid-plan decisions. Scheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names. "},{"slug":"research-availability","title":"Research availability","description":"Explore Recoup research, choose the right identifiers, and handle incomplete data.","category":"Quickstart","group":"Getting started","source":"research-availability.mdx","body":"Recoup Research lets you discover artists and tracks, read current metrics,\nexplore audience and playlist activity, and capture recording measurements.\nAuthenticate with your Recoup API key or supported bearer credential. Recoup\nmanages the data connections; you do not need a separate data-service key.\n\nCoverage varies by artist, recording, platform and metric. An empty result means\nno matching data was returned; it does not prove an artist has no activity or audience.\n\n## Choose an identifier\n\nSearch by name, inspect the matches, and pass the selected result's `id` to the\ndetail endpoints. Treat research IDs as opaque strings: do not parse them or\nsubstitute a Recoup account UUID. Artist-name shortcuts use the first match;\nselect an explicit ID when names are ambiguous.\n\nFor portable recording references, store the ISRC and available Spotify or\nApple Music identifiers. Additional response fields and provenance labels may\nvary as Recoup's data connections change. Preserve returned provenance for\ntraceability without using it to choose a data vendor.\n\n## Current track statistics\n\nSupply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus\nthe required `source` (the platform, such as `spotify`). Recoup uses stored\nSpotify measurements when available for an ISRC, and otherwise requests current\nresearch data. Preserve `data_source` and capture timestamps when returned;\nmissing provenance remains unknown. A displayed play count is not a verified\nroyalty-bearing stream count.\n\n## Research endpoints\n\n| Method | Path | Reference |\n| --- | --- | --- |\n| GET | `/api/research` | [Search](/api-reference/research/search) |\n| GET | `/api/research/albums` | [Albums](/api-reference/research/albums) |\n| GET | `/api/research/audience` | [Audience](/api-reference/research/audience) |\n| GET | `/api/research/career` | [Career activities](/api-reference/research/career) |\n| GET | `/api/research/insights` | [Insights activities](/api-reference/research/insights) |\n| GET | `/api/research/lookup` | [Spotify artist lookup](/api-reference/research/lookup) |\n| GET | `/api/research/metrics` | [Current artist metrics](/api-reference/research/metrics) |\n| GET | `/api/research/milestones` | [Milestones](/api-reference/research/milestones) |\n| GET | `/api/research/playlists` | [Artist playlists](/api-reference/research/playlists) |\n| GET | `/api/research/profile` | [Artist profile](/api-reference/research/profile) |\n| GET | `/api/research/similar` | [Related artists](/api-reference/research/similar) |\n| GET | `/api/research/track` | [Track details](/api-reference/research/track) |\n| GET | `/api/research/track/playlists` | [Track playlists](/api-reference/research/track-playlists) |\n| GET | `/api/research/tracks` | [Artist tracks](/api-reference/research/tracks) |\n| GET | `/api/research/urls` | [Platform URLs](/api-reference/research/urls) |\n\n## Understand the results\n\n- Artist metrics are current snapshots. Save dated results to compare them over time.\n- Related artists are unweighted; the accepted similarity axes do not change the ranking.\n- Artist playlist `status=past` uses all-time scope and can include current placements.\n- Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.\n- Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.\n- Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.\n\n## Historical measurement jobs\n\n`POST /api/research/measurement-jobs` supports `source: \"historical\"`\nfor Spotify backfill. It requires a card on file and returns queue counts with\n`id: null`; enqueueing does not confirm capture completion. Recordings with an\nexisting historical research measurement can be skipped even when their history\nis partial. Inspect the available dates before claiming complete coverage.\nCurrent capture jobs return a snapshot ID.\n\n## Costs and unavailable data\n\nSuccessful research calls cost $0.05 (50,000 micro-dollar credits). Track-name\nresolution can add separately charged lookup calls; reuse a selected research\nID when available. Historical enqueue itself does not deduct research credits;\ncapture work has its own balance and budget checks.\n\nFor `402 insufficient_credits`, show the returned `billingUrl`. Surface `429`\nand unavailable-data errors; use bounded retries for transient failures and stop\nwhen the request cannot be served. Recoup does not promise a `Retry-After` header\non these routes. Never fill a missing metric with an invented number or zero.\n","headings":[{"title":"Choose an identifier","id":"choose-an-identifier"},{"title":"Current track statistics","id":"current-track-statistics"},{"title":"Research endpoints","id":"research-endpoints"},{"title":"Understand the results","id":"understand-the-results"},{"title":"Historical measurement jobs","id":"historical-measurement-jobs"},{"title":"Costs and unavailable data","id":"costs-and-unavailable-data"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Recoup Research lets you discover artists and tracks, read current metrics,\\nexplore audience and playlist activity, and capture recording measurements.\\nAuthenticate with your Recoup API key or supported bearer credential. Recoup\\nmanages the data connections; you do not need a separate data-service key.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Coverage varies by artist, recording, platform and metric. An empty result means\\nno matching data was returned; it does not prove an artist has no activity or audience.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"choose-an-identifier\",\n children: \"Choose an identifier\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Search by name, inspect the matches, and pass the selected result's \", _jsx(_components.code, {\n children: \"id\"\n }), \" to the\\ndetail endpoints. Treat research IDs as opaque strings: do not parse them or\\nsubstitute a Recoup account UUID. Artist-name shortcuts use the first match;\\nselect an explicit ID when names are ambiguous.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For portable recording references, store the ISRC and available Spotify or\\nApple Music identifiers. Additional response fields and provenance labels may\\nvary as Recoup's data connections change. Preserve returned provenance for\\ntraceability without using it to choose a data vendor.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"current-track-statistics\",\n children: \"Current track statistics\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Supply exactly one of \", _jsx(_components.code, {\n children: \"isrc\"\n }), \", \", _jsx(_components.code, {\n children: \"spotify_track_id\"\n }), \", or \", _jsx(_components.code, {\n children: \"apple_music_track_id\"\n }), \", plus\\nthe required \", _jsx(_components.code, {\n children: \"source\"\n }), \" (the platform, such as \", _jsx(_components.code, {\n children: \"spotify\"\n }), \"). Recoup uses stored\\nSpotify measurements when available for an ISRC, and otherwise requests current\\nresearch data. Preserve \", _jsx(_components.code, {\n children: \"data_source\"\n }), \" and capture timestamps when returned;\\nmissing provenance remains unknown. A displayed play count is not a verified\\nroyalty-bearing stream count.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"research-endpoints\",\n children: \"Research endpoints\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Method\"\n }), _jsx(_components.th, {\n children: \"Path\"\n }), _jsx(_components.th, {\n children: \"Reference\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/search\",\n children: \"Search\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/albums\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/albums\",\n children: \"Albums\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/audience\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/audience\",\n children: \"Audience\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/career\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/career\",\n children: \"Career activities\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/insights\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/insights\",\n children: \"Insights activities\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/lookup\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/lookup\",\n children: \"Spotify artist lookup\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/metrics\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/metrics\",\n children: \"Current artist metrics\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/milestones\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/milestones\",\n children: \"Milestones\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/playlists\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/playlists\",\n children: \"Artist playlists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/profile\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/profile\",\n children: \"Artist profile\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/similar\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/similar\",\n children: \"Related artists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/track\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/track\",\n children: \"Track details\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/track/playlists\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/track-playlists\",\n children: \"Track playlists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/tracks\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/tracks\",\n children: \"Artist tracks\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/urls\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/urls\",\n children: \"Platform URLs\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"understand-the-results\",\n children: \"Understand the results\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Artist metrics are current snapshots. Save dated results to compare them over time.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Related artists are unweighted; the accepted similarity axes do not change the ranking.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Artist playlist \", _jsx(_components.code, {\n children: \"status=past\"\n }), \" uses all-time scope and can include current placements.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"historical-measurement-jobs\",\n children: \"Historical measurement jobs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/research/measurement-jobs\"\n }), \" supports \", _jsx(_components.code, {\n children: \"source: \\\"historical\\\"\"\n }), \"\\nfor Spotify backfill. It requires a card on file and returns queue counts with\\n\", _jsx(_components.code, {\n children: \"id: null\"\n }), \"; enqueueing does not confirm capture completion. Recordings with an\\nexisting historical research measurement can be skipped even when their history\\nis partial. Inspect the available dates before claiming complete coverage.\\nCurrent capture jobs return a snapshot ID.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"costs-and-unavailable-data\",\n children: \"Costs and unavailable data\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name\\nresolution can add separately charged lookup calls; reuse a selected research\\nID when available. Historical enqueue itself does not deduct research credits;\\ncapture work has its own balance and budget checks.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For \", _jsx(_components.code, {\n children: \"402 insufficient_credits\"\n }), \", show the returned \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \". Surface \", _jsx(_components.code, {\n children: \"429\"\n }), \"\\nand unavailable-data errors; use bounded retries for transient failures and stop\\nwhen the request cannot be served. Recoup does not promise a \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" header\\non these routes. Never fill a missing metric with an invented number or zero.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Research availability Explore Recoup research, choose the right identifiers, and handle incomplete data. Quickstart Getting started Recoup Research lets you discover artists and tracks, read current metrics, explore audience and playlist activity, and capture recording measurements. Authenticate with your Recoup API key or supported bearer credential. Recoup manages the data connections; you do not need a separate data-service key. Coverage varies by artist, recording, platform and metric. An empty result means no matching data was returned; it does not prove an artist has no activity or audience. ## Choose an identifier Search by name, inspect the matches, and pass the selected result's `id` to the detail endpoints. Treat research IDs as opaque strings: do not parse them or substitute a Recoup account UUID. Artist-name shortcuts use the first match; select an explicit ID when names are ambiguous. For portable recording references, store the ISRC and available Spotify or Apple Music identifiers. Additional response fields and provenance labels may vary as Recoup's data connections change. Preserve returned provenance for traceability without using it to choose a data vendor. ## Current track statistics Supply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus the required `source` (the platform, such as `spotify`). Recoup uses stored Spotify measurements when available for an ISRC, and otherwise requests current research data. Preserve `data_source` and capture timestamps when returned; missing provenance remains unknown. A displayed play count is not a verified royalty-bearing stream count. ## Research endpoints | Method | Path | Reference | | --- | --- | --- | | GET | `/api/research` | [Search](/api-reference/research/search) | | GET | `/api/research/albums` | [Albums](/api-reference/research/albums) | | GET | `/api/research/audience` | [Audience](/api-reference/research/audience) | | GET | `/api/research/career` | [Career activities](/api-reference/research/career) | | GET | `/api/research/insights` | [Insights activities](/api-reference/research/insights) | | GET | `/api/research/lookup` | [Spotify artist lookup](/api-reference/research/lookup) | | GET | `/api/research/metrics` | [Current artist metrics](/api-reference/research/metrics) | | GET | `/api/research/milestones` | [Milestones](/api-reference/research/milestones) | | GET | `/api/research/playlists` | [Artist playlists](/api-reference/research/playlists) | | GET | `/api/research/profile` | [Artist profile](/api-reference/research/profile) | | GET | `/api/research/similar` | [Related artists](/api-reference/research/similar) | | GET | `/api/research/track` | [Track details](/api-reference/research/track) | | GET | `/api/research/track/playlists` | [Track playlists](/api-reference/research/track-playlists) | | GET | `/api/research/tracks` | [Artist tracks](/api-reference/research/tracks) | | GET | `/api/research/urls` | [Platform URLs](/api-reference/research/urls) | ## Understand the results - Artist metrics are current snapshots. Save dated results to compare them over time. - Related artists are unweighted; the accepted similarity axes do not change the ranking. - Artist playlist `status=past` uses all-time scope and can include current placements. - Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline. - Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album. - Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied. ## Historical measurement jobs `POST /api/research/measurement-jobs` supports `source: \"historical\"` for Spotify backfill. It requires a card on file and returns queue counts with `id: null`; enqueueing does not confirm capture completion. Recordings with an existing historical research measurement can be skipped even when their history is partial. Inspect the available dates before claiming complete coverage. Current capture jobs return a snapshot ID. ## Costs and unavailable data Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name resolution can add separately charged lookup calls; reuse a selected research ID when available. Historical enqueue itself does not deduct research credits; capture work has its own balance and budget checks. For `402 insufficient_credits`, show the returned `billingUrl`. Surface `429` and unavailable-data errors; use bounded retries for transient failures and stop when the request cannot be served. Recoup does not promise a `Retry-After` header on these routes. Never fill a missing metric with an invented number or zero. "},{"slug":"workflows/create-artist","title":"Create a New Artist","description":"End-to-end workflow to create, research and enrich a new artist account in a single session.","category":"Artists","group":"Workflows","source":"workflows/create-artist.mdx","body":"This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \"researched + enriched\" parity from a sandbox or any external agent.\n\nThe chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.\n\n## Prerequisites\n\n- `$RECOUP_API_KEY` (`x-api-key`) or `$RECOUP_ACCESS_TOKEN` (Privy Bearer JWT) for `api.recoupable.dev`\n- `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes)\n- An artist name to create (e.g. `ARTIST_NAME=\"The Weeknd\"`)\n\nSelect one credential obtained through the approved real-account REST setup:\n\n```bash\nif [ -n \"$RECOUP_API_KEY\" ]; then\n AUTH=(-H \"x-api-key: $RECOUP_API_KEY\")\nelif [ -n \"$RECOUP_ACCESS_TOKEN\" ]; then\n AUTH=(-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\")\nelse\n echo \"Authenticate REST through the approved real-account setup flow.\" >&2\n exit 1\nfi\n```\n\nUse your real account and selected organization. Do not create a disposable\n`agent+` identity or paste credentials into the workspace file.\n\nThe flow has three phases, run from a single checklist file:\n\n1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match\n2. **Enrich** — `PATCH` the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials\n3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array\n\n## Step 0: Scaffold the workspace BEFORE any API call\n\nPick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:\n\n```bash\nARTIST_SLUG=$(echo \"$ARTIST_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\\+/-/g; s/^-//; s/-$//')\nARTIST_DIR=\"artists/$ARTIST_SLUG\"\nmkdir -p \"$ARTIST_DIR\"\n\ncat > \"$ARTIST_DIR/RECOUP.md\" <&2\n return 1 ;;\n 429)\n retry_after=$(awk 'tolower($1)==\"retry-after:\" {sub(/^[^:]*:[[:space:]]*/, \"\"); sub(/\\r$/, \"\"); print}' \"$headers\")\n rm -f \"$headers\"\n printf 'Research step stopped. Retry-After: %s. Resume manually when allowed.\\n' \"${retry_after:-not provided}\" >&2\n return 1 ;;\n 5??) ;;\n *) rm -f \"$headers\"; printf 'Research HTTP %s; resolve before resuming.\\n' \"$status\" >&2; return 1 ;;\n esac\n fi\n if [ \"$attempt\" -lt 3 ]; then sleep \"$((attempt * 2))\"; fi\n done\n rm -f \"$headers\"\n echo 'Research unavailable after three attempts.' >&2\n return 1\n}\n```\n\n### 4a: Resolve the research artist ID\n\n```bash\nLOOKUP=$(research_request lookup --get \\\n --data-urlencode \"spotifyId=$SPOTIFY_ARTIST_ID\") || exit 1\n\nRESEARCH_ARTIST_ID=$(printf '%s' \"$LOOKUP\" | jq -r \\\n '[.id, .artist_info.id] | map(select(type == \"string\") | select(test(\"\\\\S\"))) | first // empty')\n```\n\nSave this value as `researchArtistId`. It is separate from the Recoup artist\naccount UUID and Spotify ID. Do not coerce it to a number or copy an older\nsaved research ID into it; re-resolve and verify older workspaces. If a successful\nlookup has no usable `id`, record that gap and skip 4b–4d, then run 4e.\n\nSee [Artist Lookup](/api-reference/research/lookup) for the response contract.\n\n### 4b–4d: Read available structured signals\n\n```bash\nif [ -n \"$RESEARCH_ARTIST_ID\" ]; then\n PROFILE=$(research_request profile --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\n CAREER=$(research_request career --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\n PLAYLISTS=$(research_request playlists --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\nfi\n```\n\nInspect the fields actually returned. Profile data may be partial; `career` is\nan available activity feed, not a guaranteed complete career timeline.\n`playlists` returns `placements`, which may be empty. Do not turn missing data\ninto zero or infer a label, achievement or placement that is absent.\n\nSee [Artist Profile](/api-reference/research/profile),\n[Artist Activity](/api-reference/research/career) and\n[Playlist Placements](/api-reference/research/playlists).\n\n### 4e: Search for narrative, press and collaborations\n\n```bash\nRESEARCH_WEB=$(research_request web -X POST \\\n -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg name \"$ARTIST_NAME\" \\\n '{query: ($name + \" biography press recent collaborations\")}')\") || exit 1\n```\n\nVerify source links before asserting a fact. See [Web Search](/api-reference/research/web).\n\n**After this step:** persist `researchArtistId` when available. Save the returned\npayloads, source links and coverage gaps under `## Research` in `RECOUP.md`, with\none subsection per request. Tick step 4 only after the successful reads and any\nintentional structured-data skip have been recorded.\n\n## Step 5: Pull the Spotify catalog\n\n```bash\nTOP_TRACKS=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/artist/topTracks\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$SPOTIFY_ARTIST_ID\")\n\nALBUMS=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/artist/albums\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$SPOTIFY_ARTIST_ID\")\n\n# For each notable album, drill in (ALBUM_ID from $ALBUMS):\nALBUM_DETAIL=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/album\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$ALBUM_ID\")\n```\n\n`$SPOTIFY_ARTIST_ID` is the value you exported in step 2.\n\nSee [Spotify Top Tracks](/api-reference/spotify/artist-top-tracks), [Spotify Artist Albums](/api-reference/spotify/artist-albums), and [Spotify Album](/api-reference/spotify/album) for full schemas.\n\n**After this step:** populate the artist's `releases/` folder — write one `releases/{release-slug}/RELEASE.md` per album (album slugs are bare, `-ep` / `-single` / `-compilation` suffixes for other types) using the per-album `GET /api/spotify/album?id=$ALBUM_ID` response, and write the top tracks snapshot to `releases/top-tracks.md`. `RELEASE.md` is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as `⚠️ TBD`. The full template + the field-by-field Spotify mapping live in the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill at `references/release-template.md`. Tick `- [ ] 5.` → `- [x] 5.`.\n\n## Step 6: Search the web for additional socials\n\n```bash\nSOCIALS_SEARCH=$(curl -sS -X POST \"https://api.recoupable.dev/api/research/web\" \\\n \"${AUTH[@]}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg name \"$ARTIST_NAME\" \\\n '{query: ($name + \" official instagram tiktok twitter youtube\")}')\")\n```\n\nParse the results to extract any new social URLs whose host matches the platform reference table below.\n\nSee [Web Search](/api-reference/research/web) for the request/response schema.\n\n**After this step:** save the discovered URLs (one per platform) into the `## Notes` section so step 7 can read them without re-querying. Tick `- [ ] 6.` → `- [x] 6.`.\n\n## Step 7: PATCH the artist with the discovered socials\n\n```bash\ncurl -sS -X PATCH \"https://api.recoupable.dev/api/artists/$ARTIST_ID\" \\\n \"${AUTH[@]}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"profileUrls\": {\n \"INSTAGRAM\": \"https://instagram.com/...\",\n \"TIKTOK\": \"https://tiktok.com/@...\",\n \"TWITTER\": \"https://x.com/...\",\n \"YOUTUBE\": \"https://youtube.com/@...\"\n }\n }'\n```\n\nOnly include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally.\n\nSee [Update Artist](/api-reference/artists/update) for the full body schema.\n\n**After this step:** tick `- [ ] 7.` → `- [x] 7.`.\n\n## Step 8: Synthesize the knowledge base\n\nCombine the available structured and web research (`## Research` section), the Spotify catalog (`releases/`), and the discovered socials into a comprehensive markdown report. Recommended sections:\n\n- Artist biography and origin\n- Discography highlights (top tracks + key albums)\n- Spotify presence (genres, listener count, notable playlists)\n- Social media footprint\n- Recent activity / press\n- Notable collaborations and achievements\n\nAppend the report to the same `RECOUP.md` you scaffolded in Step 0 — add it as a `## Knowledge base` section below the checklist. The path is:\n\n```\nartists/$ARTIST_SLUG/RECOUP.md\n```\n\nThis dovetails with the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL.\n\n**After this step:** tick `- [ ] 8.` → `- [x] 8.`. With every box ticked, the artist is fully set up.\n\n## Platform key reference\n\n`profileUrls` keys are **uppercase** platform identifiers, inferred from the URL host. Recognized platforms:\n\n| URL contains | `profileUrls` key |\n| ---------------------------- | ----------------- |\n| `spotify.com` | `SPOTIFY` |\n| `instagram.com` | `INSTAGRAM` |\n| `tiktok.com` | `TIKTOK` |\n| `x.com`, `twitter.com` | `TWITTER` |\n| `youtube.` | `YOUTUBE` |\n| `apple.com` | `APPLE` |\n| `facebook.com` | `FACEBOOK` |\n| `threads.net`, `threads.com` | `THREADS` |\n\nURLs that don't match any of these are silently skipped — they won't be saved.\n\n## What this workflow doesn't enforce\n\nThere's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The `RECOUP.md` checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't.\n\nA few constraints to honor:\n\n- **Run steps in order.** The frontmatter values written at one step are the inputs for later steps.\n- **Don't continue past a 4xx/5xx without recovery.** Leave the box unchecked, write the error to `## Notes`, and resolve before resuming.\n- **Treat the file as the source of truth.** If something isn't on disk, don't assume it ran.\n","headings":[{"title":"Prerequisites","id":"prerequisites"},{"title":"Step 0: Scaffold the workspace BEFORE any API call","id":"step-0-scaffold-the-workspace-before-any-api-call"},{"title":"Resuming a partial setup","id":"resuming-a-partial-setup"},{"title":"Step 1: Create the artist","id":"step-1-create-the-artist"},{"title":"Step 2: Find the canonical Spotify match","id":"step-2-find-the-canonical-spotify-match"},{"title":"Step 3: Set basic profile + Spotify URL","id":"step-3-set-basic-profile-spotify-url"},{"title":"Step 4: Run Recoup research","id":"step-4-run-recoup-research"},{"title":"Step 5: Pull the Spotify catalog","id":"step-5-pull-the-spotify-catalog"},{"title":"Step 6: Search the web for additional socials","id":"step-6-search-the-web-for-additional-socials"},{"title":"Step 7: PATCH the artist with the discovered socials","id":"step-7-patch-the-artist-with-the-discovered-socials"},{"title":"Step 8: Synthesize the knowledge base","id":"step-8-synthesize-the-knowledge-base"},{"title":"Platform key reference","id":"platform-key-reference"},{"title":"What this workflow doesn't enforce","id":"what-this-workflow-doesnt-enforce"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \\\"researched + enriched\\\" parity from a sandbox or any external agent.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, \", _jsx(_components.strong, {\n children: \"drive the work from a checklist file\"\n }), \": scaffold the artist's \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"prerequisites\",\n children: \"Prerequisites\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$RECOUP_API_KEY\"\n }), \" (\", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \") or \", _jsx(_components.code, {\n children: \"$RECOUP_ACCESS_TOKEN\"\n }), \" (Privy Bearer JWT) for \", _jsx(_components.code, {\n children: \"api.recoupable.dev\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$RECOUP_ORG_ID\"\n }), \" — the org the artist should belong to (recommended in sandboxes)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"An artist name to create (e.g. \", _jsx(_components.code, {\n children: \"ARTIST_NAME=\\\"The Weeknd\\\"\"\n }), \")\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Select one credential obtained through the approved real-account REST setup:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"if [ -n \\\"$RECOUP_API_KEY\\\" ]; then\\n AUTH=(-H \\\"x-api-key: $RECOUP_API_KEY\\\")\\nelif [ -n \\\"$RECOUP_ACCESS_TOKEN\\\" ]; then\\n AUTH=(-H \\\"Authorization: Bearer $RECOUP_ACCESS_TOKEN\\\")\\nelse\\n echo \\\"Authenticate REST through the approved real-account setup flow.\\\" >&2\\n exit 1\\nfi\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use your real account and selected organization. Do not create a disposable\\n\", _jsx(_components.code, {\n children: \"agent+\"\n }), \" identity or paste credentials into the workspace file.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The flow has three phases, run from a single checklist file:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Create + identify\"\n }), \" — \", _jsx(_components.code, {\n children: \"POST /api/artists\"\n }), \", then find the canonical Spotify match\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Enrich\"\n }), \" — \", _jsx(_components.code, {\n children: \"PATCH\"\n }), \" the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Synthesize + persist\"\n }), \" — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally \", _jsx(_components.code, {\n children: \"PATCH\"\n }), \" the \", _jsx(_components.code, {\n children: \"knowledges\"\n }), \" array\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-0-scaffold-the-workspace-before-any-api-call\",\n children: \"Step 0: Scaffold the workspace BEFORE any API call\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pick a slug, make the directory, and write the initial \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"ARTIST_SLUG=$(echo \\\"$ARTIST_NAME\\\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\\\\+/-/g; s/^-//; s/-$//')\\nARTIST_DIR=\\\"artists/$ARTIST_SLUG\\\"\\nmkdir -p \\\"$ARTIST_DIR\\\"\\n\\ncat > \\\"$ARTIST_DIR/RECOUP.md\\\" <&2\\n return 1 ;;\\n 429)\\n retry_after=$(awk 'tolower($1)==\\\"retry-after:\\\" {sub(/^[^:]*:[[:space:]]*/, \\\"\\\"); sub(/\\\\r$/, \\\"\\\"); print}' \\\"$headers\\\")\\n rm -f \\\"$headers\\\"\\n printf 'Research step stopped. Retry-After: %s. Resume manually when allowed.\\\\n' \\\"${retry_after:-not provided}\\\" >&2\\n return 1 ;;\\n 5??) ;;\\n *) rm -f \\\"$headers\\\"; printf 'Research HTTP %s; resolve before resuming.\\\\n' \\\"$status\\\" >&2; return 1 ;;\\n esac\\n fi\\n if [ \\\"$attempt\\\" -lt 3 ]; then sleep \\\"$((attempt * 2))\\\"; fi\\n done\\n rm -f \\\"$headers\\\"\\n echo 'Research unavailable after three attempts.' >&2\\n return 1\\n}\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4a-resolve-the-research-artist-id\",\n children: \"4a: Resolve the research artist ID\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"LOOKUP=$(research_request lookup --get \\\\\\n --data-urlencode \\\"spotifyId=$SPOTIFY_ARTIST_ID\\\") || exit 1\\n\\nRESEARCH_ARTIST_ID=$(printf '%s' \\\"$LOOKUP\\\" | jq -r \\\\\\n '[.id, .artist_info.id] | map(select(type == \\\"string\\\") | select(test(\\\"\\\\\\\\S\\\"))) | first // empty')\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save this value as \", _jsx(_components.code, {\n children: \"researchArtistId\"\n }), \". It is separate from the Recoup artist\\naccount UUID and Spotify ID. Do not coerce it to a number or copy an older\\nsaved research ID into it; re-resolve and verify older workspaces. If a successful\\nlookup has no usable \", _jsx(_components.code, {\n children: \"id\"\n }), \", record that gap and skip 4b–4d, then run 4e.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/lookup\",\n children: \"Artist Lookup\"\n }), \" for the response contract.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4b4d-read-available-structured-signals\",\n children: \"4b–4d: Read available structured signals\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"if [ -n \\\"$RESEARCH_ARTIST_ID\\\" ]; then\\n PROFILE=$(research_request profile --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\n CAREER=$(research_request career --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\n PLAYLISTS=$(research_request playlists --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\nfi\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Inspect the fields actually returned. Profile data may be partial; \", _jsx(_components.code, {\n children: \"career\"\n }), \" is\\nan available activity feed, not a guaranteed complete career timeline.\\n\", _jsx(_components.code, {\n children: \"playlists\"\n }), \" returns \", _jsx(_components.code, {\n children: \"placements\"\n }), \", which may be empty. Do not turn missing data\\ninto zero or infer a label, achievement or placement that is absent.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/profile\",\n children: \"Artist Profile\"\n }), \",\\n\", _jsx(_components.a, {\n href: \"/api-reference/research/career\",\n children: \"Artist Activity\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"/api-reference/research/playlists\",\n children: \"Playlist Placements\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4e-search-for-narrative-press-and-collaborations\",\n children: \"4e: Search for narrative, press and collaborations\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"RESEARCH_WEB=$(research_request web -X POST \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg name \\\"$ARTIST_NAME\\\" \\\\\\n '{query: ($name + \\\" biography press recent collaborations\\\")}')\\\") || exit 1\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Verify source links before asserting a fact. See \", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: \"Web Search\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" persist \", _jsx(_components.code, {\n children: \"researchArtistId\"\n }), \" when available. Save the returned\\npayloads, source links and coverage gaps under \", _jsx(_components.code, {\n children: \"## Research\"\n }), \" in \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \", with\\none subsection per request. Tick step 4 only after the successful reads and any\\nintentional structured-data skip have been recorded.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-5-pull-the-spotify-catalog\",\n children: \"Step 5: Pull the Spotify catalog\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"TOP_TRACKS=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/artist/topTracks\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$SPOTIFY_ARTIST_ID\\\")\\n\\nALBUMS=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/artist/albums\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$SPOTIFY_ARTIST_ID\\\")\\n\\n# For each notable album, drill in (ALBUM_ID from $ALBUMS):\\nALBUM_DETAIL=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/album\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$ALBUM_ID\\\")\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"$SPOTIFY_ARTIST_ID\"\n }), \" is the value you exported in step 2.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/spotify/artist-top-tracks\",\n children: \"Spotify Top Tracks\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/spotify/artist-albums\",\n children: \"Spotify Artist Albums\"\n }), \", and \", _jsx(_components.a, {\n href: \"/api-reference/spotify/album\",\n children: \"Spotify Album\"\n }), \" for full schemas.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" populate the artist's \", _jsx(_components.code, {\n children: \"releases/\"\n }), \" folder — write one \", _jsx(_components.code, {\n children: \"releases/{release-slug}/RELEASE.md\"\n }), \" per album (album slugs are bare, \", _jsx(_components.code, {\n children: \"-ep\"\n }), \" / \", _jsx(_components.code, {\n children: \"-single\"\n }), \" / \", _jsx(_components.code, {\n children: \"-compilation\"\n }), \" suffixes for other types) using the per-album \", _jsx(_components.code, {\n children: \"GET /api/spotify/album?id=$ALBUM_ID\"\n }), \" response, and write the top tracks snapshot to \", _jsx(_components.code, {\n children: \"releases/top-tracks.md\"\n }), \". \", _jsx(_components.code, {\n children: \"RELEASE.md\"\n }), \" is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as \", _jsx(_components.code, {\n children: \"⚠️ TBD\"\n }), \". The full template + the field-by-field Spotify mapping live in the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace\",\n children: _jsx(_components.code, {\n children: \"artist-workspace\"\n })\n }), \" skill at \", _jsx(_components.code, {\n children: \"references/release-template.md\"\n }), \". Tick \", _jsx(_components.code, {\n children: \"- [ ] 5.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 5.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-6-search-the-web-for-additional-socials\",\n children: \"Step 6: Search the web for additional socials\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"SOCIALS_SEARCH=$(curl -sS -X POST \\\"https://api.recoupable.dev/api/research/web\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg name \\\"$ARTIST_NAME\\\" \\\\\\n '{query: ($name + \\\" official instagram tiktok twitter youtube\\\")}')\\\")\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Parse the results to extract any new social URLs whose host matches the platform reference table below.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: \"Web Search\"\n }), \" for the request/response schema.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" save the discovered URLs (one per platform) into the \", _jsx(_components.code, {\n children: \"## Notes\"\n }), \" section so step 7 can read them without re-querying. Tick \", _jsx(_components.code, {\n children: \"- [ ] 6.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 6.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-7-patch-the-artist-with-the-discovered-socials\",\n children: \"Step 7: PATCH the artist with the discovered socials\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS -X PATCH \\\"https://api.recoupable.dev/api/artists/$ARTIST_ID\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\n \\\"profileUrls\\\": {\\n \\\"INSTAGRAM\\\": \\\"https://instagram.com/...\\\",\\n \\\"TIKTOK\\\": \\\"https://tiktok.com/@...\\\",\\n \\\"TWITTER\\\": \\\"https://x.com/...\\\",\\n \\\"YOUTUBE\\\": \\\"https://youtube.com/@...\\\"\\n }\\n }'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Only include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/artists/update\",\n children: \"Update Artist\"\n }), \" for the full body schema.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" tick \", _jsx(_components.code, {\n children: \"- [ ] 7.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 7.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-8-synthesize-the-knowledge-base\",\n children: \"Step 8: Synthesize the knowledge base\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Combine the available structured and web research (\", _jsx(_components.code, {\n children: \"## Research\"\n }), \" section), the Spotify catalog (\", _jsx(_components.code, {\n children: \"releases/\"\n }), \"), and the discovered socials into a comprehensive markdown report. Recommended sections:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Artist biography and origin\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Discography highlights (top tracks + key albums)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Spotify presence (genres, listener count, notable playlists)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Social media footprint\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Recent activity / press\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Notable collaborations and achievements\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Append the report to the same \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" you scaffolded in Step 0 — add it as a \", _jsx(_components.code, {\n children: \"## Knowledge base\"\n }), \" section below the checklist. The path is:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"artists/$ARTIST_SLUG/RECOUP.md\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This dovetails with the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace\",\n children: _jsx(_components.code, {\n children: \"artist-workspace\"\n })\n }), \" skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" tick \", _jsx(_components.code, {\n children: \"- [ ] 8.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 8.\"\n }), \". With every box ticked, the artist is fully set up.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"platform-key-reference\",\n children: \"Platform key reference\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"profileUrls\"\n }), \" keys are \", _jsx(_components.strong, {\n children: \"uppercase\"\n }), \" platform identifiers, inferred from the URL host. Recognized platforms:\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"URL contains\"\n }), _jsxs(_components.th, {\n children: [_jsx(_components.code, {\n children: \"profileUrls\"\n }), \" key\"]\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"spotify.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"SPOTIFY\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"instagram.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"INSTAGRAM\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"tiktok.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"TIKTOK\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"x.com\"\n }), \", \", _jsx(_components.code, {\n children: \"twitter.com\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"TWITTER\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"youtube.\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"YOUTUBE\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"apple.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"APPLE\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"facebook.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"FACEBOOK\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"threads.net\"\n }), \", \", _jsx(_components.code, {\n children: \"threads.com\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"THREADS\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"URLs that don't match any of these are silently skipped — they won't be saved.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-this-workflow-doesnt-enforce\",\n children: \"What this workflow doesn't enforce\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"There's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A few constraints to honor:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Run steps in order.\"\n }), \" The frontmatter values written at one step are the inputs for later steps.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Don't continue past a 4xx/5xx without recovery.\"\n }), \" Leave the box unchecked, write the error to \", _jsx(_components.code, {\n children: \"## Notes\"\n }), \", and resolve before resuming.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Treat the file as the source of truth.\"\n }), \" If something isn't on disk, don't assume it ran.\"]\n }), \"\\n\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Create a New Artist End-to-end workflow to create, research and enrich a new artist account in a single session. Artists Workflows This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \"researched + enriched\" parity from a sandbox or any external agent. The chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it. ## Prerequisites - `$RECOUP_API_KEY` (`x-api-key`) or `$RECOUP_ACCESS_TOKEN` (Privy Bearer JWT) for `api.recoupable.dev` - `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes) - An artist name to create (e.g. `ARTIST_NAME=\"The Weeknd\"`) Select one credential obtained through the approved real-account REST setup: Use your real account and selected organization. Do not create a disposable `agent+` identity or paste credentials into the workspace file. The flow has three phases, run from a single checklist file: 1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match 2. **Enrich** — `PATCH` the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials 3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array ## Step 0: Scaffold the workspace BEFORE any API call Pick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps: The sandbox is already scoped to a single Recoupable organization (its repo _is_ the org), so artists live at the top level — there is no `orgs/` directory. Don't proceed to step 1 until the file exists on disk. **After every step that follows, do two writes back to `RECOUP.md`:** tick the checkbox for the step you just ran (`- [ ]` → `- [x]`) and persist any captured value into the frontmatter. Later steps read those values from the frontmatter — never re-derive what's already saved. ## Resuming a partial setup If `$ARTIST_DIR/RECOUP.md` already exists, do not re-scaffold and do not re-run completed steps. Read the file, find the first unchecked item, and resume from there using the values already saved in the frontmatter: If every item is checked, the artist is fully set up — confirm with the user before doing anything else. ## Step 1: Create the artist Capture `account_id` as `$ARTIST_ID` — every subsequent step needs it. `organization_id` is optional but should be included when running inside a sandbox so the artist is scoped to the right org. See [Create Artist](/api-reference/artists/create) for the full request/response schema. **After this step:** write `artistId: $ARTIST_ID` into the frontmatter and tick `- [ ] 1.` → `- [x] 1.` in `RECOUP.md`. ## Step 2: Find the canonical Spotify match Inspect the returned candidates' names, profile links, images and catalog. Set `SELECTED_SPOTIFY_ARTIST_ID` to the verified match; popularity alone does not establish identity. If candidates remain ambiguous, resolve that before saving the artist's profile. If the verified artist is absent from the first ten results, repeat the search with a more specific name or known catalog context and inspect the new results. Do not substitute another artist. After verifying the candidate, export its fields: Also keep `genres`, `followers.total`, and `popularity` from `$MATCH` for the KB report later. See [Spotify Search](/api-reference/spotify/search) for the full query parameters and response schema. **After this step:** write `spotifyArtistId`, `spotifyProfileUrl`, and `imageUrl` into the frontmatter, save `genres` / `followers.total` / `popularity` to the `## Notes` section, and tick `- [ ] 2.` → `- [x] 2.`. ## Step 3: Set basic profile + Spotify URL One `PATCH` covers the image and the Spotify social URL. Use **uppercase** platform keys in `profileUrls` (the API matches platforms case-sensitively — see the reference table below). 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 only after verifying it in the research (step 4). See [Update Artist](/api-reference/artists/update) for the full body schema. **After this step:** tick `- [ ] 3.` → `- [x] 3.`. ## Step 4: Run Recoup research Resolve the verified Spotify artist to an opaque Recoup research ID, then read available profile fields, activity and playlist placements. Coverage varies by artist and platform: an empty successful response is a data gap, not a request to warm a cache. Use a web search for biography, press and collaborations. The four structured reads below cost $0.05 each when successful, or $0.20 total (200,000 micro-dollar credits). Web research is billed separately; check the current credit reference before running it. Check HTTP status before extracting IDs or making dependent calls. This helper allows at most three attempts for network failures or `5xx`, each with a 90-second timeout. A `402` surfaces `billingUrl`; a `429` stops the step and prints `Retry-After` for a later manual retry; it does not wait or retry automatically. Leave the step unchecked on errors. ### 4a: Resolve the research artist ID Save this value as `researchArtistId`. It is separate from the Recoup artist account UUID and Spotify ID. Do not coerce it to a number or copy an older saved research ID into it; re-resolve and verify older workspaces. If a successful lookup has no usable `id`, record that gap and skip 4b–4d, then run 4e. See [Artist Lookup](/api-reference/research/lookup) for the response contract. ### 4b–4d: Read available structured signals Inspect the fields actually returned. Profile data may be partial; `career` is an available activity feed, not a guaranteed complete career timeline. `playlists` returns `placements`, which may be empty. Do not turn missing data into zero or infer a label, achievement or placement that is absent. See [Artist Profile](/api-reference/research/profile), [Artist Activity](/api-reference/research/career) and [Playlist Placements](/api-reference/research/playlists). ### 4e: Search for narrative, press and collaborations Verify source links before asserting a fact. See [Web Search](/api-reference/research/web). **After this step:** persist `researchArtistId` when available. Save the returned payloads, source links and coverage gaps under `## Research` in `RECOUP.md`, with one subsection per request. Tick step 4 only after the successful reads and any intentional structured-data skip have been recorded. ## Step 5: Pull the Spotify catalog `$SPOTIFY_ARTIST_ID` is the value you exported in step 2. See [Spotify Top Tracks](/api-reference/spotify/artist-top-tracks), [Spotify Artist Albums](/api-reference/spotify/artist-albums), and [Spotify Album](/api-reference/spotify/album) for full schemas. **After this step:** populate the artist's `releases/` folder — write one `releases/{release-slug}/RELEASE.md` per album (album slugs are bare, `-ep` / `-single` / `-compilation` suffixes for other types) using the per-album `GET /api/spotify/album?id=$ALBUM_ID` response, and write the top tracks snapshot to `releases/top-tracks.md`. `RELEASE.md` is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as `⚠️ TBD`. The full template + the field-by-field Spotify mapping live in the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill at `references/release-template.md`. Tick `- [ ] 5.` → `- [x] 5.`. ## Step 6: Search the web for additional socials Parse the results to extract any new social URLs whose host matches the platform reference table below. See [Web Search](/api-reference/research/web) for the request/response schema. **After this step:** save the discovered URLs (one per platform) into the `## Notes` section so step 7 can read them without re-querying. Tick `- [ ] 6.` → `- [x] 6.`. ## Step 7: PATCH the artist with the discovered socials Only include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally. See [Update Artist](/api-reference/artists/update) for the full body schema. **After this step:** tick `- [ ] 7.` → `- [x] 7.`. ## Step 8: Synthesize the knowledge base Combine the available structured and web research (`## Research` section), the Spotify catalog (`releases/`), and the discovered socials into a comprehensive markdown report. Recommended sections: - Artist biography and origin - Discography highlights (top tracks + key albums) - Spotify presence (genres, listener count, notable playlists) - Social media footprint - Recent activity / press - Notable collaborations and achievements Append the report to the same `RECOUP.md` you scaffolded in Step 0 — add it as a `## Knowledge base` section below the checklist. The path is: This dovetails with the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL. **After this step:** tick `- [ ] 8.` → `- [x] 8.`. With every box ticked, the artist is fully set up. ## Platform key reference `profileUrls` keys are **uppercase** platform identifiers, inferred from the URL host. Recognized platforms: | URL contains | `profileUrls` key | | ---------------------------- | ----------------- | | `spotify.com` | `SPOTIFY` | | `instagram.com` | `INSTAGRAM` | | `tiktok.com` | `TIKTOK` | | `x.com`, `twitter.com` | `TWITTER` | | `youtube.` | `YOUTUBE` | | `apple.com` | `APPLE` | | `facebook.com` | `FACEBOOK` | | `threads.net`, `threads.com` | `THREADS` | URLs that don't match any of these are silently skipped — they won't be saved. ## What this workflow doesn't enforce There's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The `RECOUP.md` checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't. A few constraints to honor: - **Run steps in order.** The frontmatter values written at one step are the inputs for later steps. - **Don't continue past a 4xx/5xx without recovery.** Leave the box unchecked, write the error to `## Notes`, and resolve before resuming. - **Treat the file as the source of truth.** If something isn't on disk, don't assume it ran. "},{"slug":"api-reference/artists/list","title":"Get Artists","description":"Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to.","category":"Artists","group":"Artists","source":"api-reference/artists/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists","spec":"releases.json"},"searchText":"Get Artists Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to. Artists Artists GET /api/artists "},{"slug":"api-reference/artists/profile","title":"Get Artist Profile","description":"Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call.","category":"Artists","group":"Artists","source":"api-reference/artists/profile.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/profile","spec":"releases.json"},"searchText":"Get Artist Profile Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call. Artists Artists GET /api/artists/{id}/profile "},{"slug":"api-reference/artists/create","title":"Create Artist","description":"Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization.","category":"Artists","group":"Artists","source":"api-reference/artists/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/artists","spec":"releases.json"},"searchText":"Create Artist Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization. Artists Artists POST /api/artists "},{"slug":"api-reference/artists/update","title":"Update Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Update Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/pin","title":"Pin Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/pin.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Pin Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/unpin","title":"Unpin Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/unpin.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Unpin Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/delete","title":"Delete Artist","description":"Delete an artist accessible to the authenticated account.","category":"Artists","group":"Artists","source":"api-reference/artists/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Delete Artist Delete an artist accessible to the authenticated account. Artists Artists DELETE /api/artists/{id} "},{"slug":"api-reference/artists/socials","title":"Get Artist Socials","description":"Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember.","category":"Artists","group":"Artists","source":"api-reference/artists/socials.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/socials","spec":"releases.json"},"searchText":"Get Artist Socials Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember. Artists Artists GET /api/artists/{id}/socials "},{"slug":"api-reference/artists/socials-delete","title":"Delete Artist Social","description":"Remove a social profile link from an artist to correct a wrongly auto-matched social.","category":"Artists","group":"Artists","source":"api-reference/artists/socials-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/artists/{id}/socials/{socialId}","spec":"releases.json"},"searchText":"Delete Artist Social Remove a social profile link from an artist to correct a wrongly auto-matched social. Artists Artists DELETE /api/artists/{id}/socials/{socialId} "},{"slug":"api-reference/fans/get","title":"Get Artist Fans","description":"Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists.","category":"Artists","group":"Fans","source":"api-reference/fans/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/fans","spec":"releases.json"},"searchText":"Get Artist Fans Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists. Artists Fans GET /api/artists/{id}/fans "},{"slug":"api-reference/chat/workflow","title":"Stream Chat","description":"Stream sandbox-driven chat (Vercel Workflow)","category":"Chats","group":"Streaming","source":"api-reference/chat/workflow.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat","spec":"research.json"},"searchText":"Stream Chat Stream sandbox-driven chat (Vercel Workflow) Chats Streaming POST /api/chat "},{"slug":"api-reference/chat/workflow-stream","title":"Resume Chat Stream","description":"Resume a chat response stream","category":"Chats","group":"Streaming","source":"api-reference/chat/workflow-stream.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chat/{chatId}/stream","spec":"research.json"},"searchText":"Resume Chat Stream Resume a chat response stream Chats Streaming GET /api/chat/{chatId}/stream "},{"slug":"api-reference/chat/runs","title":"Start Chat Run","description":"Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow).","category":"Chats","group":"Streaming","source":"api-reference/chat/runs.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat/runs","spec":"research.json"},"searchText":"Start Chat Run Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow). Chats Streaming POST /api/chat/runs "},{"slug":"api-reference/chat/runs-status","title":"Get Chat Run Status","description":"Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.","category":"Chats","group":"Streaming","source":"api-reference/chat/runs-status.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chat/runs/{runId}","spec":"research.json"},"searchText":"Get Chat Run Status Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content. Chats Streaming GET /api/chat/runs/{runId} "},{"slug":"api-reference/chat/stop","title":"Stop Chat","description":"Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account.","category":"Chats","group":"Streaming","source":"api-reference/chat/stop.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat/{chatId}/stop","spec":"research.json"},"searchText":"Stop Chat Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account. Chats Streaming POST /api/chat/{chatId}/stop "},{"slug":"api-reference/chat/create","title":"Create Chat","description":"Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to.","category":"Chats","group":"Chats","source":"api-reference/chat/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats","spec":"research.json"},"searchText":"Create Chat Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to. Chats Chats POST /api/chats "},{"slug":"api-reference/chat/chats","title":"Get Chats","description":"Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL.","category":"Chats","group":"Chats","source":"api-reference/chat/chats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats","spec":"research.json"},"searchText":"Get Chats Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL. Chats Chats GET /api/chats "},{"slug":"api-reference/chat/artist","title":"Get Chat Artist","description":"Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller.","category":"Chats","group":"Chats","source":"api-reference/chat/artist.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats/{id}/artist","spec":"research.json"},"searchText":"Get Chat Artist Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller. Chats Chats GET /api/chats/{id}/artist "},{"slug":"api-reference/chat/update","title":"Update Chat","description":"Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters.","category":"Chats","group":"Chats","source":"api-reference/chat/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/chats","spec":"research.json"},"searchText":"Update Chat Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters. Chats Chats PATCH /api/chats "},{"slug":"api-reference/chat/delete","title":"Delete Chat","description":"Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself.","category":"Chats","group":"Chats","source":"api-reference/chat/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/chats","spec":"research.json"},"searchText":"Delete Chat Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself. Chats Chats DELETE /api/chats "},{"slug":"api-reference/chat/compact","title":"Compact Chats","description":"Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary.","category":"Chats","group":"Chats","source":"api-reference/chat/compact.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats/compact","spec":"research.json"},"searchText":"Compact Chats Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary. Chats Chats POST /api/chats/compact "},{"slug":"api-reference/ai/models","title":"List Models","description":"Returns the catalog of language models available through the Vercel AI Gateway. Embedding models are filtered out. The full schema mirrors the Vercel AI Gateway response (`GatewayLanguageModelEntry` from `@ai-sdk/gateway`); the documented properties below are the load-bearing fields used by clients. No authentication required.","category":"Chats","group":"Chats","source":"api-reference/ai/models.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/ai/models","spec":"ai.json"},"searchText":"List Models Returns the catalog of language models available through the Vercel AI Gateway. Embedding models are filtered out. The full schema mirrors the Vercel AI Gateway response (`GatewayLanguageModelEntry` from `@ai-sdk/gateway`); the documented properties below are the load-bearing fields used by clients. No authentication required. Chats Chats GET /api/ai/models "},{"slug":"api-reference/chat/messages","title":"Get Chat Messages","description":"Retrieve all messages (memories) for a specific chat room in chronological order.","category":"Chats","group":"Messages","source":"api-reference/chat/messages.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats/{id}/messages","spec":"research.json"},"searchText":"Get Chat Messages Retrieve all messages (memories) for a specific chat room in chronological order. Chats Messages GET /api/chats/{id}/messages "},{"slug":"api-reference/chat/messages-copy","title":"Copy Chat Messages","description":"Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy.","category":"Chats","group":"Messages","source":"api-reference/chat/messages-copy.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats/{id}/messages/copy","spec":"research.json"},"searchText":"Copy Chat Messages Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy. Chats Messages POST /api/chats/{id}/messages/copy "},{"slug":"api-reference/chat/messages-trailing-delete","title":"Delete Trailing Chat Messages","description":"Delete all messages in a chat from a given message onward (inclusive), identified by `from_message_id`.","category":"Chats","group":"Messages","source":"api-reference/chat/messages-trailing-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/chats/{id}/messages/trailing","spec":"research.json"},"searchText":"Delete Trailing Chat Messages Delete all messages in a chat from a given message onward (inclusive), identified by `from_message_id`. Chats Messages DELETE /api/chats/{id}/messages/trailing "},{"slug":"api-reference/research/search","title":"Research Search","description":"Search Recoup Research for artists, tracks or labels by name. Artist and track matches include an `id` when an identifier is available. Select a match and reuse that ID for detail requests. `type` accepts artists, tracks or labels, plus their singular aliases, case-insensitively. Playlist search is unavailable. Recoup defaults `limit` to 10; pagination strings are passed to the data connection and its limits apply.","category":"Research","group":"Artist discovery","source":"api-reference/research/search.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research","spec":"research.json"},"searchText":"Research Search Search Recoup Research for artists, tracks or labels by name. Artist and track matches include an `id` when an identifier is available. Select a match and reuse that ID for detail requests. `type` accepts artists, tracks or labels, plus their singular aliases, case-insensitively. Playlist search is unavailable. Recoup defaults `limit` to 10; pagination strings are passed to the data connection and its limits apply. Research Artist discovery GET /api/research "},{"slug":"api-reference/research/lookup","title":"Lookup by URL","description":"Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved.","category":"Research","group":"Artist discovery","source":"api-reference/research/lookup.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/lookup","spec":"research.json"},"searchText":"Lookup by URL Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved. Research Artist discovery GET /api/research/lookup "},{"slug":"api-reference/research/profile","title":"Artist Profile","description":"Read artist identity and available biography, links, genres and related-artist metadata. Fields depend on available research data. For current platform counts, use [Metrics](/api-reference/research/metrics).","category":"Research","group":"Artist discovery","source":"api-reference/research/profile.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/profile","spec":"research.json"},"searchText":"Artist Profile Read artist identity and available biography, links, genres and related-artist metadata. Fields depend on available research data. For current platform counts, use [Metrics](/api-reference/research/metrics). Research Artist discovery GET /api/research/profile "},{"slug":"api-reference/research/metrics","title":"Platform Metrics","description":"Read current artist statistics for the required platform `source`. This is a synchronous snapshot, without a historical series or refresh-pending job. A valid source does not guarantee data is available. Save dated responses to compare results over time.","category":"Research","group":"Metrics & insights","source":"api-reference/research/metrics.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/metrics","spec":"research.json"},"searchText":"Platform Metrics Read current artist statistics for the required platform `source`. This is a synchronous snapshot, without a historical series or refresh-pending job. A valid source does not guarantee data is available. Save dated responses to compare results over time. Research Metrics & insights GET /api/research/metrics "},{"slug":"api-reference/research/audience","title":"Audience Demographics","description":"Read available audience data for an artist and platform. The default is `instagram`; other supported data connections can include Spotify, TikTok and YouTube. Geographic and demographic coverage varies. Age and gender breakdowns are not guaranteed.","category":"Research","group":"Metrics & insights","source":"api-reference/research/audience.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/audience","spec":"research.json"},"searchText":"Audience Demographics Read available audience data for an artist and platform. The default is `instagram`; other supported data connections can include Spotify, TikTok and YouTube. Geographic and demographic coverage varies. Age and gender breakdowns are not guaranteed. Research Metrics & insights GET /api/research/audience "},{"slug":"api-reference/research/insights","title":"Insights Activities","description":"Read available artist activities under `insights`. This endpoint returns activity data; it does not generate an AI analysis or a separate insight report.","category":"Research","group":"Metrics & insights","source":"api-reference/research/insights.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/insights","spec":"research.json"},"searchText":"Insights Activities Read available artist activities under `insights`. This endpoint returns activity data; it does not generate an AI analysis or a separate insight report. Research Metrics & insights GET /api/research/insights "},{"slug":"api-reference/research/career","title":"Career Timeline","description":"Read available dated artist activities under `career`. Career, insights and milestones use the same activity feed. This endpoint does not calculate a career stage or score, and does not guarantee a complete career history.","category":"Research","group":"Metrics & insights","source":"api-reference/research/career.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/career","spec":"research.json"},"searchText":"Career Timeline Read available dated artist activities under `career`. Career, insights and milestones use the same activity feed. This endpoint does not calculate a career stage or score, and does not guarantee a complete career history. Research Metrics & insights GET /api/research/career "},{"slug":"api-reference/research/milestones","title":"Milestones","description":"Read available artist activities under `milestones`. Coverage varies; an empty result does not prove the artist has no milestones. This endpoint does not guarantee a complete history or scored career timeline.","category":"Research","group":"Metrics & insights","source":"api-reference/research/milestones.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/milestones","spec":"research.json"},"searchText":"Milestones Read available artist activities under `milestones`. Coverage varies; an empty result does not prove the artist has no milestones. This endpoint does not guarantee a complete history or scored career timeline. Research Metrics & insights GET /api/research/milestones "},{"slug":"api-reference/research/events","title":"Artist Events","description":"List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup.","category":"Research","group":"Metrics & insights","source":"api-reference/research/events.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/events","spec":"research.json"},"searchText":"Artist Events List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup. Research Metrics & insights POST /api/research/events "},{"slug":"api-reference/research/similar","title":"Similar Artists","description":"Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored.","category":"Research","group":"Metrics & insights","source":"api-reference/research/similar.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/similar","spec":"research.json"},"searchText":"Similar Artists Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored. Research Metrics & insights GET /api/research/similar "},{"slug":"api-reference/research/urls","title":"Social URLs","description":"Read available platform URLs as `{domain, url}` entries. A missing link means no matching URL was returned; it does not prove the artist lacks an account on that platform.","category":"Research","group":"Metrics & insights","source":"api-reference/research/urls.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/urls","spec":"research.json"},"searchText":"Social URLs Read available platform URLs as `{domain, url}` entries. A missing link means no matching URL was returned; it does not prove the artist lacks an account on that platform. Research Metrics & insights GET /api/research/urls "},{"slug":"api-reference/research/albums","title":"Albums","description":"Read the artist catalog through the `albums` view using the `artist_id` selected from [Search](/api-reference/research/search). Results can include track-shaped catalog entries rather than distinct album objects. `is_primary` accepts true/false; filtering depends on the data connection. `limit` must be a positive integer string and `offset` a non-negative integer string.","category":"Research","group":"Catalog","source":"api-reference/research/albums.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/albums","spec":"research.json"},"searchText":"Albums Read the artist catalog through the `albums` view using the `artist_id` selected from [Search](/api-reference/research/search). Results can include track-shaped catalog entries rather than distinct album objects. `is_primary` accepts true/false; filtering depends on the data connection. `limit` must be a positive integer string and `offset` a non-negative integer string. Research Catalog GET /api/research/albums "},{"slug":"api-reference/research/tracks","title":"Tracks","description":"Read available artist catalog entries under `tracks`. Entries can include remixes and features; completeness and fields vary. This endpoint accepts an artist identifier without catalog pagination or filtering controls.","category":"Research","group":"Catalog","source":"api-reference/research/tracks.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/tracks","spec":"research.json"},"searchText":"Tracks Read available artist catalog entries under `tracks`. Entries can include remixes and features; completeness and fields vary. This endpoint accepts an artist identifier without catalog pagination or filtering controls. Research Catalog GET /api/research/tracks "},{"slug":"api-reference/research/track","title":"Track","description":"Read track details using the `id` selected from [Search](/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording.","category":"Research","group":"Catalog","source":"api-reference/research/track.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track","spec":"research.json"},"searchText":"Track Read track details using the `id` selected from [Search](/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording. Research Catalog GET /api/research/track "},{"slug":"api-reference/research/track-stats","title":"Track Stats","description":"Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown.","category":"Research","group":"Catalog","source":"api-reference/research/track-stats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track/stats","spec":"research.json"},"searchText":"Track Stats Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown. Research Catalog GET /api/research/track/stats "},{"slug":"api-reference/research/measurements","title":"Track measurements","description":"Track measurements","category":"Research","group":"Catalog","source":"api-reference/research/measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/tracks/{id}/measurements","spec":"research.json"},"searchText":"Track measurements Track measurements Research Catalog GET /api/research/tracks/{id}/measurements "},{"slug":"api-reference/research/album-measurements","title":"Album measurements","description":"Album measurements","category":"Research","group":"Catalog","source":"api-reference/research/album-measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/albums/{id}/measurements","spec":"research.json"},"searchText":"Album measurements Album measurements Research Catalog GET /api/research/albums/{id}/measurements "},{"slug":"api-reference/research/measurement-jobs","title":"Create measurement job","description":"Create a measurement job","category":"Research","group":"Catalog","source":"api-reference/research/measurement-jobs.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/measurement-jobs","spec":"research.json"},"searchText":"Create measurement job Create a measurement job Research Catalog POST /api/research/measurement-jobs "},{"slug":"api-reference/research/playlists","title":"Playlist Placements","description":"Read available playlist placements for an artist. `status=current` selects current scope; `status=past` selects all-time scope, which can include current placements. `limit` is an optional raw string with no Recoup default; supported limits and coverage depend on the data connection.","category":"Research","group":"Playlists","source":"api-reference/research/playlists.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/playlists","spec":"research.json"},"searchText":"Playlist Placements Read available playlist placements for an artist. `status=current` selects current scope; `status=past` selects all-time scope, which can include current placements. `limit` is an optional raw string with no Recoup default; supported limits and coverage depend on the data connection. Research Playlists GET /api/research/playlists "},{"slug":"api-reference/research/track-playlists","title":"Track Playlists","description":"Read available track playlist and activity entries. Supply a selected track `id`, or a track name `q` with optional `artist`. Name resolution selects the first Spotify match and resolves its research ID; `id` takes precedence. Filtering and pagination support depend on the data connection. With no filter flags, editorial, indie, majorCurator and popularIndie default to true. Track-name resolution can add separately charged lookup calls; reuse a selected ID to avoid them.","category":"Research","group":"Playlists","source":"api-reference/research/track-playlists.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track/playlists","spec":"research.json"},"searchText":"Track Playlists Read available track playlist and activity entries. Supply a selected track `id`, or a track name `q` with optional `artist`. Name resolution selects the first Spotify match and resolves its research ID; `id` takes precedence. Filtering and pagination support depend on the data connection. With no filter flags, editorial, indie, majorCurator and popularIndie default to true. Track-name resolution can add separately charged lookup calls; reuse a selected ID to avoid them. Research Playlists GET /api/research/track/playlists "},{"slug":"api-reference/research/web","title":"Web Search","description":"Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover.","category":"Research","group":"Web & social","source":"api-reference/research/web.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/web","spec":"research.json"},"searchText":"Web Search Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover. Research Web & social POST /api/research/web "},{"slug":"api-reference/research/deep","title":"Deep Research","description":"Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources.","category":"Research","group":"Web & social","source":"api-reference/research/deep.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/deep","spec":"research.json"},"searchText":"Deep Research Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources. Research Web & social POST /api/research/deep "},{"slug":"api-reference/research/people","title":"People Search","description":"Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data.","category":"Research","group":"Web & social","source":"api-reference/research/people.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/people","spec":"research.json"},"searchText":"People Search Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data. Research Web & social POST /api/research/people "},{"slug":"api-reference/research/extract","title":"Extract URL","description":"Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content.","category":"Research","group":"Web & social","source":"api-reference/research/extract.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/extract","spec":"research.json"},"searchText":"Extract URL Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content. Research Web & social POST /api/research/extract "},{"slug":"api-reference/research/enrich","title":"Enrich","description":"Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected.","category":"Research","group":"Web & social","source":"api-reference/research/enrich.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/enrich","spec":"research.json"},"searchText":"Enrich Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected. Research Web & social POST /api/research/enrich "},{"slug":"api-reference/songs/songs","title":"Get Songs","description":"Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information.","category":"Catalog","group":"Songs","source":"api-reference/songs/songs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/songs","spec":"releases.json"},"searchText":"Get Songs Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information. Catalog Songs GET /api/songs "},{"slug":"api-reference/songs/create","title":"Song creation availability","description":"Import songs into an owned catalog; standalone song creation is not available.","category":"Catalog","group":"Songs","source":"api-reference/songs/create.mdx","body":"Standalone `POST /api/songs` is not available. The API currently supports\n[`GET /api/songs`](/api-reference/songs/songs) for reading songs.\n\n## Add songs to a catalog\n\nIf you have an existing catalog you can access, use\n[`POST /api/catalogs/songs`](/api-reference/songs/catalog-songs-add).\nEach song needs its `catalog_id` and `isrc`; optional name, album, notes and\nartist names supply fallback metadata. The API checks access to every named\ncatalog before processing songs. This writes song records and catalog links;\nit is not a standalone create-only replacement.\n\n## Unfinished product decision\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) owns the\ndecision whether a separate song-creation API is needed and what ownership,\nmetadata-update and duplicate behavior it should allow. The old standalone\nrequest and response are removed from the callable specification until that\ndecision and its implementation exist. Do not omit `catalog_id` or substitute\nan unrelated catalog to make a write succeed.\n","headings":[{"title":"Add songs to a catalog","id":"add-songs-to-a-catalog"},{"title":"Unfinished product decision","id":"unfinished-product-decision"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Standalone \", _jsx(_components.code, {\n children: \"POST /api/songs\"\n }), \" is not available. The API currently supports\\n\", _jsx(_components.a, {\n href: \"/api-reference/songs/songs\",\n children: _jsx(_components.code, {\n children: \"GET /api/songs\"\n })\n }), \" for reading songs.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"add-songs-to-a-catalog\",\n children: \"Add songs to a catalog\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you have an existing catalog you can access, use\\n\", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-add\",\n children: _jsx(_components.code, {\n children: \"POST /api/catalogs/songs\"\n })\n }), \".\\nEach song needs its \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" and \", _jsx(_components.code, {\n children: \"isrc\"\n }), \"; optional name, album, notes and\\nartist names supply fallback metadata. The API checks access to every named\\ncatalog before processing songs. This writes song records and catalog links;\\nit is not a standalone create-only replacement.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"unfinished-product-decision\",\n children: \"Unfinished product decision\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" owns the\\ndecision whether a separate song-creation API is needed and what ownership,\\nmetadata-update and duplicate behavior it should allow. The old standalone\\nrequest and response are removed from the callable specification until that\\ndecision and its implementation exist. Do not omit \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" or substitute\\nan unrelated catalog to make a write succeed.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Song creation availability Import songs into an owned catalog; standalone song creation is not available. Catalog Songs Standalone `POST /api/songs` is not available. The API currently supports [`GET /api/songs`](/api-reference/songs/songs) for reading songs. ## Add songs to a catalog If you have an existing catalog you can access, use [`POST /api/catalogs/songs`](/api-reference/songs/catalog-songs-add). Each song needs its `catalog_id` and `isrc`; optional name, album, notes and artist names supply fallback metadata. The API checks access to every named catalog before processing songs. This writes song records and catalog links; it is not a standalone create-only replacement. ## Unfinished product decision [Reconciliation #327](https://github.com/recoupable/mono/issues/327) owns the decision whether a separate song-creation API is needed and what ownership, metadata-update and duplicate behavior it should allow. The old standalone request and response are removed from the callable specification until that decision and its implementation exist. Do not omit `catalog_id` or substitute an unrelated catalog to make a write succeed. "},{"slug":"api-reference/songs/analyze","title":"Analyze Songs","description":"Analyze music using a state-of-the-art Audio Language Model ([Music Flamingo](https://www.universalmusic.com/universal-music-group-to-transform-music-experience-for-billions-of-fans-with-nvidia-ai/)) that listens directly to the audio waveform.","category":"Catalog","group":"Songs","source":"api-reference/songs/analyze.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/songs/analyze","spec":"releases.json"},"searchText":"Analyze Songs Analyze music using a state-of-the-art Audio Language Model ([Music Flamingo](https://www.universalmusic.com/universal-music-group-to-transform-music-experience-for-billions-of-fans-with-nvidia-ai/)) that listens directly to the audio waveform. Catalog Songs POST /api/songs/analyze "},{"slug":"api-reference/songs/analyze-presets","title":"List Analyze Presets","description":"Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token.","category":"Catalog","group":"Songs","source":"api-reference/songs/analyze-presets.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/songs/analyze/presets","spec":"releases.json"},"searchText":"List Analyze Presets Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token. Catalog Songs GET /api/songs/analyze/presets "},{"slug":"api-reference/songs/catalogs","title":"Get Catalogs","description":"Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalogs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/catalogs","spec":"releases.json"},"searchText":"Get Catalogs Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run). Catalog Catalogs GET /api/accounts/{id}/catalogs "},{"slug":"api-reference/songs/catalogs-create","title":"Create Catalog","description":"Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalogs-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/catalogs","spec":"releases.json"},"searchText":"Create Catalog Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization. Catalog Catalogs POST /api/catalogs "},{"slug":"api-reference/songs/catalog-rename","title":"Rename Catalog","description":"Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-rename.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/catalogs/{catalogId}","spec":"releases.json"},"searchText":"Rename Catalog Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete). Catalog Catalogs PATCH /api/catalogs/{catalogId} "},{"slug":"api-reference/songs/catalog-delete","title":"Delete Catalog","description":"Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/catalogs/{catalogId}","spec":"releases.json"},"searchText":"Delete Catalog Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations). Catalog Catalogs DELETE /api/catalogs/{catalogId} "},{"slug":"api-reference/songs/valuation-run","title":"Run Valuation","description":"Run valuation","category":"Catalog","group":"Catalogs","source":"api-reference/songs/valuation-run.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/valuation","spec":"releases.json"},"searchText":"Run Valuation Run valuation Catalog Catalogs POST /api/valuation "},{"slug":"api-reference/songs/runs","title":"Get Runs","description":"Get runs","category":"Catalog","group":"Catalogs","source":"api-reference/songs/runs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/runs","spec":"releases.json"},"searchText":"Get Runs Get runs Catalog Catalogs GET /api/runs "},{"slug":"api-reference/songs/catalog-measurements","title":"Get Catalog Measurements","description":"Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/measurements","spec":"releases.json"},"searchText":"Get Catalog Measurements Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song. Catalog Catalogs GET /api/catalogs/{catalogId}/measurements "},{"slug":"api-reference/songs/catalog-playcount-history","title":"Catalog Playcount History","description":"Read catalog playcount history and period comparisons","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-playcount-history.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/playcount-history","spec":"releases.json"},"searchText":"Catalog Playcount History Read catalog playcount history and period comparisons Catalog Catalogs GET /api/catalogs/{catalogId}/playcount-history "},{"slug":"api-reference/songs/catalog-valuations","title":"Valuation history availability","description":"Saved valuation history is unfinished; current estimates do not establish a history.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-valuations.mdx","body":"Saved catalog valuation history is not available through\n`GET /api/catalogs/{catalogId}/valuations`. Current valuation calculations and\ncatalog measurements do not establish that estimates were saved or can be read\nback as a dated series.\n\n## Existing implementation work\n\n[Reconciliation #326](https://github.com/recoupable/mono/issues/326) owns this\noutcome through [App #1911](https://github.com/recoupable/app/issues/1911) and\n[API #795](https://github.com/recoupable/api/pull/795).\n[API #1059](https://github.com/recoupable/api/pull/1059) continues that work as a\nheld draft of internal adapters. It does not register a REST route, MCP tool or\nproduction caller and does not connect successful valuation runs to persistence.\n\nThe existing owner must finish the access prerequisite, run-to-save integration,\npublic read contract and authorized deployed save/readback before this feature\ncan be advertised. Removing the unfinished operation from the callable\nspecification does not complete or cancel valuation history. Do not rerun a paid\nvaluation solely to try to recover an unconfirmed save.\n","headings":[{"title":"Existing implementation work","id":"existing-implementation-work"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Saved catalog valuation history is not available through\\n\", _jsx(_components.code, {\n children: \"GET /api/catalogs/{catalogId}/valuations\"\n }), \". Current valuation calculations and\\ncatalog measurements do not establish that estimates were saved or can be read\\nback as a dated series.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"existing-implementation-work\",\n children: \"Existing implementation work\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/326\",\n children: \"Reconciliation #326\"\n }), \" owns this\\noutcome through \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/app/issues/1911\",\n children: \"App #1911\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/795\",\n children: \"API #795\"\n }), \".\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/1059\",\n children: \"API #1059\"\n }), \" continues that work as a\\nheld draft of internal adapters. It does not register a REST route, MCP tool or\\nproduction caller and does not connect successful valuation runs to persistence.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The existing owner must finish the access prerequisite, run-to-save integration,\\npublic read contract and authorized deployed save/readback before this feature\\ncan be advertised. Removing the unfinished operation from the callable\\nspecification does not complete or cancel valuation history. Do not rerun a paid\\nvaluation solely to try to recover an unconfirmed save.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Valuation history availability Saved valuation history is unfinished; current estimates do not establish a history. Catalog Catalogs Saved catalog valuation history is not available through `GET /api/catalogs/{catalogId}/valuations`. Current valuation calculations and catalog measurements do not establish that estimates were saved or can be read back as a dated series. ## Existing implementation work [Reconciliation #326](https://github.com/recoupable/mono/issues/326) owns this outcome through [App #1911](https://github.com/recoupable/app/issues/1911) and [API #795](https://github.com/recoupable/api/pull/795). [API #1059](https://github.com/recoupable/api/pull/1059) continues that work as a held draft of internal adapters. It does not register a REST route, MCP tool or production caller and does not connect successful valuation runs to persistence. The existing owner must finish the access prerequisite, run-to-save integration, public read contract and authorized deployed save/readback before this feature can be advertised. Removing the unfinished operation from the callable specification does not complete or cancel valuation history. Do not rerun a paid valuation solely to try to recover an unconfirmed save. "},{"slug":"api-reference/songs/catalog-songs","title":"Get Catalog Songs","description":"Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs.mdx","body":"\n This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints.\n\n\nA successful query with no matching songs returns HTTP `200`, an empty `songs`\narray, and `pagination.total_count: 0`. This also applies to an accessible catalog\nwith no songs. An empty result is not a `404` response.\n\nUse a nonempty `artistName` to request songs with a matching artist name. Omit the filter to\ninclude songs without a linked artist. Filtering applies before pagination and\nthe total count; a client can use a zero count to decide whether to retry without\nthe artist filter.\n\nMissing or inaccessible catalogs return `403`. A server or database failure\nreturns `500` with `status: \"error\"` and `error: \"Internal server error\"`.\n","headings":[],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the \", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-add\",\n children: \"Add Catalog Songs\"\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-delete\",\n children: \"Remove Catalog Songs\"\n }), \" endpoints.\"]\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A successful query with no matching songs returns HTTP \", _jsx(_components.code, {\n children: \"200\"\n }), \", an empty \", _jsx(_components.code, {\n children: \"songs\"\n }), \"\\narray, and \", _jsx(_components.code, {\n children: \"pagination.total_count: 0\"\n }), \". This also applies to an accessible catalog\\nwith no songs. An empty result is not a \", _jsx(_components.code, {\n children: \"404\"\n }), \" response.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use a nonempty \", _jsx(_components.code, {\n children: \"artistName\"\n }), \" to request songs with a matching artist name. Omit the filter to\\ninclude songs without a linked artist. Filtering applies before pagination and\\nthe total count; a client can use a zero count to decide whether to retry without\\nthe artist filter.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Missing or inaccessible catalogs return \", _jsx(_components.code, {\n children: \"403\"\n }), \". A server or database failure\\nreturns \", _jsx(_components.code, {\n children: \"500\"\n }), \" with \", _jsx(_components.code, {\n children: \"status: \\\"error\\\"\"\n }), \" and \", _jsx(_components.code, {\n children: \"error: \\\"Internal server error\\\"\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"GET","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Get Catalog Songs Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0. Catalog Catalogs GET /api/catalogs/songs This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints. A successful query with no matching songs returns HTTP `200`, an empty `songs` array, and `pagination.total_count: 0`. This also applies to an accessible catalog with no songs. An empty result is not a `404` response. Use a nonempty `artistName` to request songs with a matching artist name. Omit the filter to include songs without a linked artist. Filtering applies before pagination and the total count; a client can use a zero count to decide whether to retry without the artist filter. Missing or inaccessible catalogs return `403`. A server or database failure returns `500` with `status: \"error\"` and `error: \"Internal server error\"`. "},{"slug":"api-reference/songs/catalog-songs-add","title":"Add Catalog Songs","description":"Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs-add.mdx","body":"\n For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.\n\n","headings":[],"compiled":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.\"\n })\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"POST","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Add Catalog Songs Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used. Catalog Catalogs POST /api/catalogs/songs For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used. "},{"slug":"api-reference/songs/catalog-songs-delete","title":"Remove Catalog Songs","description":"Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs-delete.mdx","body":"\n This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted.\n\n","headings":[],"compiled":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"This endpoint removes the relationship in \", _jsx(_components.code, {\n children: \"catalog_songs\"\n }), \" for each \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" and ISRC pair. The song data itself is not deleted.\"]\n })\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"DELETE","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Remove Catalog Songs Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair. Catalog Catalogs DELETE /api/catalogs/songs This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted. "},{"slug":"api-reference/songs/catalog-streams","title":"Daily Catalog Streams","description":"Read daily catalog streams","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-streams.mdx","body":"## Date range and coverage\n\nSet `days` to an integer from 1 to 366 days. For example, use `days=90` for a 90-day comparison period. `since` is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive.\n\nA supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while `pagination.has_more` is true. Missing measurements suppress growth; they do not establish zero streams.\n\nThe catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection.\n","headings":[{"title":"Date range and coverage","id":"date-range-and-coverage"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"date-range-and-coverage\",\n children: \"Date range and coverage\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Set \", _jsx(_components.code, {\n children: \"days\"\n }), \" to an integer from 1 to 366 days. For example, use \", _jsx(_components.code, {\n children: \"days=90\"\n }), \" for a 90-day comparison period. \", _jsx(_components.code, {\n children: \"since\"\n }), \" is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while \", _jsx(_components.code, {\n children: \"pagination.has_more\"\n }), \" is true. Missing measurements suppress growth; they do not establish zero streams.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","api":{"method":"GET","path":"/api/catalogs/{catalogId}/streams","spec":"releases.json"},"searchText":"Daily Catalog Streams Read daily catalog streams Catalog Catalogs GET /api/catalogs/{catalogId}/streams ## Date range and coverage Set `days` to an integer from 1 to 366 days. For example, use `days=90` for a 90-day comparison period. `since` is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive. A supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while `pagination.has_more` is true. Missing measurements suppress growth; they do not establish zero streams. The catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection. "},{"slug":"api-reference/songs/catalog-stream-tracking","title":"Catalog Stream Tracking","description":"Inspect daily catalog tracking","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-stream-tracking.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/stream-tracking","spec":"releases.json"},"searchText":"Catalog Stream Tracking Inspect daily catalog tracking Catalog Catalogs GET /api/catalogs/{catalogId}/stream-tracking "},{"slug":"api-reference/songs/update-catalog-stream-tracking","title":"Update Catalog Stream Tracking","description":"Control daily catalog tracking","category":"Catalog","group":"Catalogs","source":"api-reference/songs/update-catalog-stream-tracking.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/catalogs/{catalogId}/stream-tracking","spec":"releases.json"},"searchText":"Update Catalog Stream Tracking Control daily catalog tracking Catalog Catalogs POST /api/catalogs/{catalogId}/stream-tracking "},{"slug":"api-reference/context/operate","title":"Context Engine","description":"Ingest, read, or compile context briefs","category":"Catalog","group":"Context","source":"api-reference/context/operate.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context","spec":"context.json"},"searchText":"Context Engine Ingest, read, or compile context briefs Catalog Context POST /api/context "},{"slug":"api-reference/context/guest-start","title":"Start guest context","description":"Start guest context extraction","category":"Catalog","group":"Context","source":"api-reference/context/guest-start.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context/guest","spec":"context.json"},"searchText":"Start guest context Start guest context extraction Catalog Context POST /api/context/guest "},{"slug":"api-reference/context/guest-read","title":"Read guest context","description":"Read guest context","category":"Catalog","group":"Context","source":"api-reference/context/guest-read.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/context/guest","spec":"context.json"},"searchText":"Read guest context Read guest context Catalog Context GET /api/context/guest "},{"slug":"api-reference/context/guest-claim","title":"Claim guest context","description":"Claim guest context after sign-in","category":"Catalog","group":"Context","source":"api-reference/context/guest-claim.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context/guest/claim","spec":"context.json"},"searchText":"Claim guest context Claim guest context after sign-in Catalog Context POST /api/context/guest/claim "},{"slug":"workflows/generate-music-video","title":"Generate a Music Video","description":"End-to-end workflow to produce a vertical, social-ready music video — image, motion, caption — from an artist and a song.","category":"Content","group":"Workflows","source":"workflows/generate-music-video.mdx","body":"This is the canonical recipe used internally by Recoup's `create-content` background task. Two paths are documented below: the **async pipeline** that an LLM agent should use, and the **manual recipe** for humans (or for cases where you want to swap a single step).\n\n## Hand it to your LLM\n\nThe fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a `.md` suffix, so models can fetch and follow it without parsing HTML:\n\n```\nGenerate a music video for The Weeknd – \"Blinding Lights\" using\nhttps://docs.recoupable.dev/workflows/generate-music-video.md\n```\n\nSwap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL.\n\n## Running as an agent? Use the async pipeline\n\n`POST /api/content/video` is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments.\n\nUse the async path instead — same five steps, run server-side:\n\n```bash\n# Trigger\nRUN_IDS=$(curl -sS -X POST \"https://api.recoupable.dev/api/content/create\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg artist \"$ARTIST_ACCOUNT_ID\" --arg template \"$TEMPLATE\" \\\n '{artist_account_id: $artist, template: $template}')\" \\\n | jq -r '.runIds[]')\n\n# Poll (every ~10s) until COMPLETED / FAILED / CANCELED / CRASHED\nRUN_ID=$(echo \"$RUN_IDS\" | head -1)\nuntil STATUS=$(curl -sS \"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq -r '.runs[0].status') && \\\n [[ \"$STATUS\" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do\n sleep 10\ndone\n\n# Read the output\ncurl -sS \"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq '.runs[0].output'\n# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }\n```\n\nPolling fits inside short shell timeouts and survives session restarts. See [Tasks Runs](/api-reference/tasks/runs) for the full status enum (`QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, etc.) and the `CreateContentRunOutput` schema.\n\n### Resolving `$ARTIST_ACCOUNT_ID`\n\n`POST /api/content/create` needs the artist's `account_id`. Three calls:\n\n```bash\nORG_ID=$(curl -sS \"https://api.recoupable.dev/api/organizations\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" | jq -r '.organizations[0].id')\n\nARTIST_ACCOUNT_ID=$(curl -sS \"https://api.recoupable.dev/api/artists?org_id=$ORG_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq -r --arg name \"$ARTIST_NAME\" '.artists[] | select(.name == $name) | .account_id')\n```\n\nThe artist record exposes both `id` and `account_id` (both UUIDs). Use **`account_id`** — `id` is the artist row's primary key, `account_id` is the underlying account that owns it. The two are easy to swap; you'll get a 404 from `/api/content/create` if you pass the wrong one.\n\n## Where the song lives\n\nStep 5 (and the async pipeline's lipsync mode) need a `song.mp3`. **Don't assume one exists, and don't assume the user has one locally.** Walk the agent through this fallback chain:\n\n1. **Check the artist's sandbox repo first.** Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths:\n\n ```\n .openclaw/workspace/orgs/{org-slug}/artists/{artist-slug}/songs/{song-slug}/{song-slug}.mp3\n /lyrics.json\n /clips.json\n ```\n\n Discover the repo with [`GET /api/sandboxes`](/api-reference/sandboxes/list) (returns `github_repo` and a `filetree`); fetch a file with [`GET /api/sandboxes/file?path=…`](/api-reference/sandboxes/file). **Binary files (`.mp3`, `.png`, `.mp4`) come back base64-encoded in the `content` field — decode before writing to disk.**\n\n2. **If no song is in the sandbox, ask the user how to proceed.** Two options to offer:\n - *\"Want me to fetch the audio from YouTube?\"* — agent downloads via `yt-dlp` (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications.\n - *\"Want to supply the song yourself?\"* — user uploads / drops a path; agent reads from there.\n\n Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call.\n\n3. **Don't fall back to \"use a placeholder track.\"** A music video without the song is not a deliverable.\n\n## Manual recipe (humans + targeted overrides)\n\nThe rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length).\n\n### Prerequisites\n\n- An auth credential for `api.recoupable.dev`. Two options — pick one and use it for every call below:\n - **API key** (`recoup_sk_…`, recommended for sandbox / agent use): pass as `-H \"x-api-key: $RECOUP_API_KEY\"`.\n - One-shot agent: `POST /api/agents/signup` with an `agent+{unique}@recoupable.com` email returns the key immediately.\n - Real-email signup: same endpoint with a real email mails a 6-digit code; complete with `POST /api/agents/verify`. See [Agents](/agents).\n - **Privy access token** (for end-user flows in chat/UI): pass as `-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\"`.\n - The examples below use `x-api-key`. Substitute `Authorization: Bearer …` if you're using a Privy token.\n- `$ARTIST_NAME`, `$SONG_TITLE`, `$SONG_LYRICS_CLIP` (a 1–2 sentence mood snippet)\n- `$REFERENCE_IMAGE_URL` *(optional)* — an artist photo or album cover to seed the image; if your template's purpose is \"show this exact image\" (e.g. `album-record-store`), set this and skip image generation in step 2\n- A `song.mp3` for step 5. **Don't ask the user for a local file** — fetch from the artist's repo via `/api/sandboxes/file`.\n- `ffmpeg` installed locally for step 5\n\n### Step 0: Scaffold the workspace BEFORE any API call\n\nThe `VIDEO.md` checklist *is* the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box.\n\n```bash\nVIDEO_SLUG=$(echo \"$SONG_TITLE\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-//; s/-$//')\nVIDEO_DIR=\"videos/$VIDEO_SLUG\"\nmkdir -p \"$VIDEO_DIR\"\n\ncat > \"$VIDEO_DIR/VIDEO.md\" < \"$VIDEO_DIR/caption.txt\"\n\n# Single-line filter graph — newlines inside -filter_complex are literal characters and break the [v] label\nffmpeg -y \\\n -stream_loop -1 -i \"$VIDEO_DIR/clip.mp4\" \\\n -i \"$SONG_PATH\" \\\n -filter_complex \"[0:v]crop=ih*9/16:ih,scale=1080:1920,drawtext=fontfile=$CAPTION_FONT:textfile=$VIDEO_DIR/caption.txt:fontcolor=$CAPTION_COLOR:fontsize=$CAPTION_FONT_SIZE:x=(w-text_w)/2:y=h-text_h-120:box=1:boxcolor=$CAPTION_STROKE@0.5:boxborderw=20[v]\" \\\n -map \"[v]\" -map \"1:a\" \\\n -shortest -c:v libx264 -c:a aac -pix_fmt yuv420p \\\n \"$FINAL_PATH\"\n```\n\n**After:** write `finalVideoPath`, tick the box. With every box ticked, the music video is complete.\n\n## Step 6: Publish (optional)\n\nOnce the MP4 is rendered, push it to the artist's socials with the [Connectors API](/api-reference/connectors/list). One heads-up worth knowing:\n\n- **TikTok URL ownership.** `TIKTOK_PUBLISH_VIDEO` (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. `fal.media` URLs will fail with `url_ownership_unverified` — use `TIKTOK_UPLOAD_VIDEO` instead, which accepts the same URL and uploads server-side.\n\n---\n\nThe checklist is the source of truth — if a box isn't ticked, treat the step as not run.\n","headings":[{"title":"Hand it to your LLM","id":"hand-it-to-your-llm"},{"title":"Running as an agent? Use the async pipeline","id":"running-as-an-agent-use-the-async-pipeline"},{"title":"Where the song lives","id":"where-the-song-lives"},{"title":"Manual recipe (humans + targeted overrides)","id":"manual-recipe-humans-targeted-overrides"},{"title":"Step 6: Publish (optional)","id":"step-6-publish-optional"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"This is the canonical recipe used internally by Recoup's \", _jsx(_components.code, {\n children: \"create-content\"\n }), \" background task. Two paths are documented below: the \", _jsx(_components.strong, {\n children: \"async pipeline\"\n }), \" that an LLM agent should use, and the \", _jsx(_components.strong, {\n children: \"manual recipe\"\n }), \" for humans (or for cases where you want to swap a single step).\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hand-it-to-your-llm\",\n children: \"Hand it to your LLM\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a \", _jsx(_components.code, {\n children: \".md\"\n }), \" suffix, so models can fetch and follow it without parsing HTML:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"Generate a music video for The Weeknd – \\\"Blinding Lights\\\" using\\nhttps://docs.recoupable.dev/workflows/generate-music-video.md\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Swap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"running-as-an-agent-use-the-async-pipeline\",\n children: \"Running as an agent? Use the async pipeline\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/video\"\n }), \" is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the async path instead — same five steps, run server-side:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"# Trigger\\nRUN_IDS=$(curl -sS -X POST \\\"https://api.recoupable.dev/api/content/create\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg artist \\\"$ARTIST_ACCOUNT_ID\\\" --arg template \\\"$TEMPLATE\\\" \\\\\\n '{artist_account_id: $artist, template: $template}')\\\" \\\\\\n | jq -r '.runIds[]')\\n\\n# Poll (every ~10s) until COMPLETED / FAILED / CANCELED / CRASHED\\nRUN_ID=$(echo \\\"$RUN_IDS\\\" | head -1)\\nuntil STATUS=$(curl -sS \\\"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq -r '.runs[0].status') && \\\\\\n [[ \\\"$STATUS\\\" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do\\n sleep 10\\ndone\\n\\n# Read the output\\ncurl -sS \\\"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq '.runs[0].output'\\n# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Polling fits inside short shell timeouts and survives session restarts. See \", _jsx(_components.a, {\n href: \"/api-reference/tasks/runs\",\n children: \"Tasks Runs\"\n }), \" for the full status enum (\", _jsx(_components.code, {\n children: \"QUEUED\"\n }), \", \", _jsx(_components.code, {\n children: \"EXECUTING\"\n }), \", \", _jsx(_components.code, {\n children: \"COMPLETED\"\n }), \", \", _jsx(_components.code, {\n children: \"FAILED\"\n }), \", \", _jsx(_components.code, {\n children: \"CANCELED\"\n }), \", \", _jsx(_components.code, {\n children: \"CRASHED\"\n }), \", etc.) and the \", _jsx(_components.code, {\n children: \"CreateContentRunOutput\"\n }), \" schema.\"]\n }), \"\\n\", _jsxs(_components.h3, {\n id: \"resolving-artistaccountid\",\n children: [\"Resolving \", _jsx(_components.code, {\n children: \"$ARTIST_ACCOUNT_ID\"\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/create\"\n }), \" needs the artist's \", _jsx(_components.code, {\n children: \"account_id\"\n }), \". Three calls:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"ORG_ID=$(curl -sS \\\"https://api.recoupable.dev/api/organizations\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" | jq -r '.organizations[0].id')\\n\\nARTIST_ACCOUNT_ID=$(curl -sS \\\"https://api.recoupable.dev/api/artists?org_id=$ORG_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq -r --arg name \\\"$ARTIST_NAME\\\" '.artists[] | select(.name == $name) | .account_id')\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The artist record exposes both \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" (both UUIDs). Use \", _jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"account_id\"\n })\n }), \" — \", _jsx(_components.code, {\n children: \"id\"\n }), \" is the artist row's primary key, \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" is the underlying account that owns it. The two are easy to swap; you'll get a 404 from \", _jsx(_components.code, {\n children: \"/api/content/create\"\n }), \" if you pass the wrong one.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"where-the-song-lives\",\n children: \"Where the song lives\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Step 5 (and the async pipeline's lipsync mode) need a \", _jsx(_components.code, {\n children: \"song.mp3\"\n }), \". \", _jsx(_components.strong, {\n children: \"Don't assume one exists, and don't assume the user has one locally.\"\n }), \" Walk the agent through this fallback chain:\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Check the artist's sandbox repo first.\"\n }), \" Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \".openclaw/workspace/orgs/{org-slug}/artists/{artist-slug}/songs/{song-slug}/{song-slug}.mp3\\n /lyrics.json\\n /clips.json\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Discover the repo with \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes\"\n })\n }), \" (returns \", _jsx(_components.code, {\n children: \"github_repo\"\n }), \" and a \", _jsx(_components.code, {\n children: \"filetree\"\n }), \"); fetch a file with \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/file\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes/file?path=…\"\n })\n }), \". \", _jsxs(_components.strong, {\n children: [\"Binary files (\", _jsx(_components.code, {\n children: \".mp3\"\n }), \", \", _jsx(_components.code, {\n children: \".png\"\n }), \", \", _jsx(_components.code, {\n children: \".mp4\"\n }), \") come back base64-encoded in the \", _jsx(_components.code, {\n children: \"content\"\n }), \" field — decode before writing to disk.\"]\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"If no song is in the sandbox, ask the user how to proceed.\"\n }), \" Two options to offer:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.em, {\n children: \"\\\"Want me to fetch the audio from YouTube?\\\"\"\n }), \" — agent downloads via \", _jsx(_components.code, {\n children: \"yt-dlp\"\n }), \" (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.em, {\n children: \"\\\"Want to supply the song yourself?\\\"\"\n }), \" — user uploads / drops a path; agent reads from there.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Don't fall back to \\\"use a placeholder track.\\\"\"\n }), \" A music video without the song is not a deliverable.\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"manual-recipe-humans-targeted-overrides\",\n children: \"Manual recipe (humans + targeted overrides)\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length).\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"prerequisites\",\n children: \"Prerequisites\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"An auth credential for \", _jsx(_components.code, {\n children: \"api.recoupable.dev\"\n }), \". Two options — pick one and use it for every call below:\", \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"API key\"\n }), \" (\", _jsx(_components.code, {\n children: \"recoup_sk_…\"\n }), \", recommended for sandbox / agent use): pass as \", _jsx(_components.code, {\n children: \"-H \\\"x-api-key: $RECOUP_API_KEY\\\"\"\n }), \".\", \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"One-shot agent: \", _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" with an \", _jsx(_components.code, {\n children: \"agent+{unique}@recoupable.com\"\n }), \" email returns the key immediately.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Real-email signup: same endpoint with a real email mails a 6-digit code; complete with \", _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \". See \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents\"\n }), \".\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Privy access token\"\n }), \" (for end-user flows in chat/UI): pass as \", _jsx(_components.code, {\n children: \"-H \\\"Authorization: Bearer $RECOUP_ACCESS_TOKEN\\\"\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The examples below use \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \". Substitute \", _jsx(_components.code, {\n children: \"Authorization: Bearer …\"\n }), \" if you're using a Privy token.\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$ARTIST_NAME\"\n }), \", \", _jsx(_components.code, {\n children: \"$SONG_TITLE\"\n }), \", \", _jsx(_components.code, {\n children: \"$SONG_LYRICS_CLIP\"\n }), \" (a 1–2 sentence mood snippet)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$REFERENCE_IMAGE_URL\"\n }), \" \", _jsx(_components.em, {\n children: \"(optional)\"\n }), \" — an artist photo or album cover to seed the image; if your template's purpose is \\\"show this exact image\\\" (e.g. \", _jsx(_components.code, {\n children: \"album-record-store\"\n }), \"), set this and skip image generation in step 2\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"A \", _jsx(_components.code, {\n children: \"song.mp3\"\n }), \" for step 5. \", _jsx(_components.strong, {\n children: \"Don't ask the user for a local file\"\n }), \" — fetch from the artist's repo via \", _jsx(_components.code, {\n children: \"/api/sandboxes/file\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"ffmpeg\"\n }), \" installed locally for step 5\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"step-0-scaffold-the-workspace-before-any-api-call\",\n children: \"Step 0: Scaffold the workspace BEFORE any API call\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.code, {\n children: \"VIDEO.md\"\n }), \" checklist \", _jsx(_components.em, {\n children: \"is\"\n }), \" the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"VIDEO_SLUG=$(echo \\\"$SONG_TITLE\\\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-//; s/-$//')\\nVIDEO_DIR=\\\"videos/$VIDEO_SLUG\\\"\\nmkdir -p \\\"$VIDEO_DIR\\\"\\n\\ncat > \\\"$VIDEO_DIR/VIDEO.md\\\" < \\\"$VIDEO_DIR/caption.txt\\\"\\n\\n# Single-line filter graph — newlines inside -filter_complex are literal characters and break the [v] label\\nffmpeg -y \\\\\\n -stream_loop -1 -i \\\"$VIDEO_DIR/clip.mp4\\\" \\\\\\n -i \\\"$SONG_PATH\\\" \\\\\\n -filter_complex \\\"[0:v]crop=ih*9/16:ih,scale=1080:1920,drawtext=fontfile=$CAPTION_FONT:textfile=$VIDEO_DIR/caption.txt:fontcolor=$CAPTION_COLOR:fontsize=$CAPTION_FONT_SIZE:x=(w-text_w)/2:y=h-text_h-120:box=1:boxcolor=$CAPTION_STROKE@0.5:boxborderw=20[v]\\\" \\\\\\n -map \\\"[v]\\\" -map \\\"1:a\\\" \\\\\\n -shortest -c:v libx264 -c:a aac -pix_fmt yuv420p \\\\\\n \\\"$FINAL_PATH\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After:\"\n }), \" write \", _jsx(_components.code, {\n children: \"finalVideoPath\"\n }), \", tick the box. With every box ticked, the music video is complete.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-6-publish-optional\",\n children: \"Step 6: Publish (optional)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once the MP4 is rendered, push it to the artist's socials with the \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors API\"\n }), \". One heads-up worth knowing:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"TikTok URL ownership.\"\n }), \" \", _jsx(_components.code, {\n children: \"TIKTOK_PUBLISH_VIDEO\"\n }), \" (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. \", _jsx(_components.code, {\n children: \"fal.media\"\n }), \" URLs will fail with \", _jsx(_components.code, {\n children: \"url_ownership_unverified\"\n }), \" — use \", _jsx(_components.code, {\n children: \"TIKTOK_UPLOAD_VIDEO\"\n }), \" instead, which accepts the same URL and uploads server-side.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.p, {\n children: \"The checklist is the source of truth — if a box isn't ticked, treat the step as not run.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Generate a Music Video End-to-end workflow to produce a vertical, social-ready music video — image, motion, caption — from an artist and a song. Content Workflows This is the canonical recipe used internally by Recoup's `create-content` background task. Two paths are documented below: the **async pipeline** that an LLM agent should use, and the **manual recipe** for humans (or for cases where you want to swap a single step). ## Hand it to your LLM The fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a `.md` suffix, so models can fetch and follow it without parsing HTML: Swap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL. ## Running as an agent? Use the async pipeline `POST /api/content/video` is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments. Use the async path instead — same five steps, run server-side: Polling fits inside short shell timeouts and survives session restarts. See [Tasks Runs](/api-reference/tasks/runs) for the full status enum (`QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, etc.) and the `CreateContentRunOutput` schema. ### Resolving `$ARTIST_ACCOUNT_ID` `POST /api/content/create` needs the artist's `account_id`. Three calls: The artist record exposes both `id` and `account_id` (both UUIDs). Use **`account_id`** — `id` is the artist row's primary key, `account_id` is the underlying account that owns it. The two are easy to swap; you'll get a 404 from `/api/content/create` if you pass the wrong one. ## Where the song lives Step 5 (and the async pipeline's lipsync mode) need a `song.mp3`. **Don't assume one exists, and don't assume the user has one locally.** Walk the agent through this fallback chain: 1. **Check the artist's sandbox repo first.** Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths: Discover the repo with [`GET /api/sandboxes`](/api-reference/sandboxes/list) (returns `github_repo` and a `filetree`); fetch a file with [`GET /api/sandboxes/file?path=…`](/api-reference/sandboxes/file). **Binary files (`.mp3`, `.png`, `.mp4`) come back base64-encoded in the `content` field — decode before writing to disk.** 2. **If no song is in the sandbox, ask the user how to proceed.** Two options to offer: - *\"Want me to fetch the audio from YouTube?\"* — agent downloads via `yt-dlp` (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications. - *\"Want to supply the song yourself?\"* — user uploads / drops a path; agent reads from there. Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call. 3. **Don't fall back to \"use a placeholder track.\"** A music video without the song is not a deliverable. ## Manual recipe (humans + targeted overrides) The rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length). ### Prerequisites - An auth credential for `api.recoupable.dev`. Two options — pick one and use it for every call below: - **API key** (`recoup_sk_…`, recommended for sandbox / agent use): pass as `-H \"x-api-key: $RECOUP_API_KEY\"`. - One-shot agent: `POST /api/agents/signup` with an `agent+{unique}@recoupable.com` email returns the key immediately. - Real-email signup: same endpoint with a real email mails a 6-digit code; complete with `POST /api/agents/verify`. See [Agents](/agents). - **Privy access token** (for end-user flows in chat/UI): pass as `-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\"`. - The examples below use `x-api-key`. Substitute `Authorization: Bearer …` if you're using a Privy token. - `$ARTIST_NAME`, `$SONG_TITLE`, `$SONG_LYRICS_CLIP` (a 1–2 sentence mood snippet) - `$REFERENCE_IMAGE_URL` *(optional)* — an artist photo or album cover to seed the image; if your template's purpose is \"show this exact image\" (e.g. `album-record-store`), set this and skip image generation in step 2 - A `song.mp3` for step 5. **Don't ask the user for a local file** — fetch from the artist's repo via `/api/sandboxes/file`. - `ffmpeg` installed locally for step 5 ### Step 0: Scaffold the workspace BEFORE any API call The `VIDEO.md` checklist *is* the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box. ### Step 1: Pick a template (required: list **and** detail) Templates carry the prompt, reference images, and styling that drive the rest of the chain — you can't write a good Step 2 prompt without them. List, pick, then fetch detail: **Templates that list \"Requires: face image\"** (e.g. `artist-caption-bedroom`) will fall back to their bundled reference images and produce a generic-likeness subject if you don't supply one — they don't 400. Pass `$REFERENCE_IMAGE_URL` if you want the model to preserve a specific artist's likeness, or omit it for a stock-feeling result. See [List Templates](/api-reference/content/templates) and [Template Detail](/api-reference/content/template-detail). **After:** write `template` into frontmatter, tick the box. ### Step 2: Generate the base image Use the template's own prompt and reference images — don't write your own from scratch. The template encodes the visual style; freeform prompts almost always drift off-brand. **Shortcut:** if `$REFERENCE_IMAGE_URL` is the exact image you want (e.g. an album cover for `album-record-store`, or a final editorial photo), set `IMAGE_URL=$REFERENCE_IMAGE_URL` and skip this call entirely. **Avoid:** prompts that aim for a real artist's likeness. Veo (used in step 3) rejects celebrity-likeness images with a 422. Use the template's prompt as-is and let the reference images carry the style. See [Generate Image](/api-reference/content/generate-image). **After:** write `imageUrl`, tick the box. ### Optional: Upscale (image or video) Same endpoint for both, swap `type`. Skip if you don't need the resolution bump. See [Upscale](/api-reference/content/upscale). ### Step 3: Generate the video Pass the image and a short motion prompt. For lipsync, also pass a presigned `audio_url` to a song clip — the model will animate the artist's mouth. This call routinely takes 60–180s. **From a short-shell agent, use the async pipeline at the top of this page instead.** From a long-lived shell, output is an 8s clip. Step 5 loops it to song length. See [Generate Video](/api-reference/content/generate-video). **After:** write `videoUrl`, tick the box. ### Step 4: Generate the caption `length` accepts `\"short\"` (default), `\"medium\"`, `\"long\"`, or `\"none\"` to skip. The four styling fields (`font`, `color`, `borderColor`, `maxFontSize`) are template-driven hints — Step 5 wires them into ffmpeg's `drawtext` so the burned-in caption matches the template's brand. See [Generate Caption](/api-reference/content/generate-caption). **After:** write `captionText`, tick the box. ### Step 5: Compose the final 9:16 video (local) The API returns a 16:9 motion clip. Compose locally: crop to 9:16, overlay the song audio for the full duration, and burn in the caption with the styling from step 4. **After:** write `finalVideoPath`, tick the box. With every box ticked, the music video is complete. ## Step 6: Publish (optional) Once the MP4 is rendered, push it to the artist's socials with the [Connectors API](/api-reference/connectors/list). One heads-up worth knowing: - **TikTok URL ownership.** `TIKTOK_PUBLISH_VIDEO` (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. `fal.media` URLs will fail with `url_ownership_unverified` — use `TIKTOK_UPLOAD_VIDEO` instead, which accepts the same URL and uploads server-side. --- The checklist is the source of truth — if a box isn't ticked, treat the step as not run. "},{"slug":"api-reference/content/create","title":"Create Content","description":"Trigger 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).","category":"Content","group":"Content Creation","source":"api-reference/content/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/create","spec":"content.json"},"searchText":"Create Content Trigger 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). Content Content Creation POST /api/content/create "},{"slug":"api-reference/content/generate-image","title":"Generate Image","description":"Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL.","category":"Content","group":"Content Creation","source":"api-reference/content/generate-image.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/image","spec":"content.json"},"searchText":"Generate Image Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL. Content Content Creation POST /api/content/image "},{"slug":"api-reference/content/generate-video","title":"Generate Video","description":"Generate a video from a text prompt, optionally animating a still image (`image_url`) or transitioning between two images (`image_url` + `end_image_url`).","category":"Content","group":"Content Creation","source":"api-reference/content/generate-video.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/video","spec":"content.json"},"searchText":"Generate Video Generate a video from a text prompt, optionally animating a still image (`image_url`) or transitioning between two images (`image_url` + `end_image_url`). Content Content Creation POST /api/content/video "},{"slug":"api-reference/content/generate-caption","title":"Generate Caption","description":"Generate a short caption from a topic. Returns the text content and default styling (font, color, size).","category":"Content","group":"Content Creation","source":"api-reference/content/generate-caption.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/caption","spec":"content.json"},"searchText":"Generate Caption Generate a short caption from a topic. Returns the text content and default styling (font, color, size). Content Content Creation POST /api/content/caption "},{"slug":"api-reference/content/transcribe-audio","title":"Transcribe Audio","description":"Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments.","category":"Content","group":"Content Creation","source":"api-reference/content/transcribe-audio.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/transcribe","spec":"content.json"},"searchText":"Transcribe Audio Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments. Content Content Creation POST /api/content/transcribe "},{"slug":"api-reference/content/edit","title":"Edit Content","description":"Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.","category":"Content","group":"Content Creation","source":"api-reference/content/edit.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/content","spec":"content.json"},"searchText":"Edit Content Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array. Content Content Creation PATCH /api/content "},{"slug":"api-reference/content/upscale","title":"Upscale Content","description":"Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL.","category":"Content","group":"Content Creation","source":"api-reference/content/upscale.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/upscale","spec":"content.json"},"searchText":"Upscale Content Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL. Content Content Creation POST /api/content/upscale "},{"slug":"api-reference/content/analyze-video","title":"Analyze Video","description":"Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text.","category":"Content","group":"Content Creation","source":"api-reference/content/analyze-video.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/analyze","spec":"content.json"},"searchText":"Analyze Video Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text. Content Content Creation POST /api/content/analyze "},{"slug":"api-reference/content/templates","title":"List Templates","description":"List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one.","category":"Content","group":"Content Creation","source":"api-reference/content/templates.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/templates","spec":"content.json"},"searchText":"List Templates List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one. Content Content Creation GET /api/content/templates "},{"slug":"api-reference/content/template-detail","title":"Get Template Detail","description":"Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations.","category":"Content","group":"Content Creation","source":"api-reference/content/template-detail.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/templates/{id}","spec":"content.json"},"searchText":"Get Template Detail Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations. Content Content Creation GET /api/content/templates/{id} "},{"slug":"api-reference/content/validate","title":"Validate Artist","description":"Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter.","category":"Content","group":"Content Creation","source":"api-reference/content/validate.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/validate","spec":"content.json"},"searchText":"Validate Artist Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter. Content Content Creation GET /api/content/validate "},{"slug":"api-reference/content/estimate","title":"Estimate Cost","description":"Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits.","category":"Content","group":"Content Creation","source":"api-reference/content/estimate.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/estimate","spec":"content.json"},"searchText":"Estimate Cost Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits. Content Content Creation GET /api/content/estimate "},{"slug":"api-reference/image/generation","title":"Generate Image","description":"Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking.","category":"Content","group":"Content Creation","source":"api-reference/image/generation.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/image/generate","spec":"content.json"},"searchText":"Generate Image Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking. Content Content Creation GET /api/image/generate "},{"slug":"api-reference/transcribe/audio","title":"Transcribe Audio","description":"Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage. The owner account is derived from your credentials; you must have access to the specified artist_account_id.","category":"Content","group":"Content Creation","source":"api-reference/transcribe/audio.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/transcribe","spec":"content.json"},"searchText":"Transcribe Audio Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage. The owner account is derived from your credentials; you must have access to the specified artist_account_id. Content Content Creation POST /api/transcribe "},{"slug":"api-reference/content/lipsync","title":"Generate lipsync (release pending)","description":"Generate audio-driven video (release pending)","category":"Content","group":"Content Creation","source":"api-reference/content/lipsync.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/lipsync","spec":"content.json"},"searchText":"Generate lipsync (release pending) Generate audio-driven video (release pending) Content Content Creation POST /api/content/lipsync "},{"slug":"api-reference/music/generate","title":"Generate Music","description":"Generate music","category":"Content","group":"Music","source":"api-reference/music/generate.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/music","spec":"content.json"},"searchText":"Generate Music Generate music Content Music POST /api/music "},{"slug":"api-reference/music/list","title":"List Music Generations","description":"List music generations","category":"Content","group":"Music","source":"api-reference/music/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/music","spec":"content.json"},"searchText":"List Music Generations List music generations Content Music GET /api/music "},{"slug":"api-reference/music/get","title":"Get Music Generation","description":"Get music generation","category":"Content","group":"Music","source":"api-reference/music/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/music/{generationId}","spec":"content.json"},"searchText":"Get Music Generation Get music generation Content Music GET /api/music/{generationId} "},{"slug":"api-reference/music/legacy","title":"Music API migration","description":"Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths.","category":"Content","group":"Music","source":"api-reference/music/legacy.mdx","body":"## Generate a song now\n\nUse [`POST /api/music`](/api-reference/music/generate) with a prompt and lyrics.\nIt returns `202` with a generation record; poll\n[`GET /api/music/{generationId}`](/api-reference/music/get) for completion and\nthe resulting audio URL. It does not return audio in the initial response.\nSee the current reference for accepted settings, account scope and credits.\n\n## Former music routes\n\nThe six POST paths below are retired from the callable specification because\nthey have no implemented handlers in the current API. They are not aliases for\n`POST /api/music`. Their specialized outcomes are not equivalent to ordinary\nsong generation and are not declared canceled by this correction.\n\n| Former path | Current choice and remaining limit |\n| --- | --- |\n| `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. |\n| `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. |\n| `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. |\n| `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. |\n| `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. |\n| `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. |\n\n## What remains undecided\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the\nspecialized capability decisions. The current music-generation implementation\nis tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and\n[API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every\nformer capability. An agent or local skill may help prepare inputs, but that\ndoes not establish a hosted route or compatibility with the former request.\n\nThis is a reference correction. No provider run or audio-quality check was\nperformed to make these availability statements.\n","headings":[{"title":"Generate a song now","id":"generate-a-song-now"},{"title":"Former music routes","id":"former-music-routes"},{"title":"What remains undecided","id":"what-remains-undecided"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"generate-a-song-now\",\n children: \"Generate a song now\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.a, {\n href: \"/api-reference/music/generate\",\n children: _jsx(_components.code, {\n children: \"POST /api/music\"\n })\n }), \" with a prompt and lyrics.\\nIt returns \", _jsx(_components.code, {\n children: \"202\"\n }), \" with a generation record; poll\\n\", _jsx(_components.a, {\n href: \"/api-reference/music/get\",\n children: _jsx(_components.code, {\n children: \"GET /api/music/{generationId}\"\n })\n }), \" for completion and\\nthe resulting audio URL. It does not return audio in the initial response.\\nSee the current reference for accepted settings, account scope and credits.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"former-music-routes\",\n children: \"Former music routes\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The six POST paths below are retired from the callable specification because\\nthey have no implemented handlers in the current API. They are not aliases for\\n\", _jsx(_components.code, {\n children: \"POST /api/music\"\n }), \". Their specialized outcomes are not equivalent to ordinary\\nsong generation and are not declared canceled by this correction.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Former path\"\n }), _jsx(_components.th, {\n children: \"Current choice and remaining limit\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/compose\"\n })\n }), _jsx(_components.td, {\n children: \"Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/compose/detailed\"\n })\n }), _jsx(_components.td, {\n children: \"Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/plan\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/stream\"\n })\n }), _jsx(_components.td, {\n children: \"Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/video-to-music\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/stem-separation\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems.\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-remains-undecided\",\n children: \"What remains undecided\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" retains the\\nspecialized capability decisions. The current music-generation implementation\\nis tracked in \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/app/issues/1992\",\n children: \"App #1992\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/848\",\n children: \"API #848\"\n }), \"; it is not delivery of every\\nformer capability. An agent or local skill may help prepare inputs, but that\\ndoes not establish a hosted route or compatibility with the former request.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This is a reference correction. No provider run or audio-quality check was\\nperformed to make these availability statements.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Music API migration Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths. Content Music ## Generate a song now Use [`POST /api/music`](/api-reference/music/generate) with a prompt and lyrics. It returns `202` with a generation record; poll [`GET /api/music/{generationId}`](/api-reference/music/get) for completion and the resulting audio URL. It does not return audio in the initial response. See the current reference for accepted settings, account scope and credits. ## Former music routes The six POST paths below are retired from the callable specification because they have no implemented handlers in the current API. They are not aliases for `POST /api/music`. Their specialized outcomes are not equivalent to ordinary song generation and are not declared canceled by this correction. | Former path | Current choice and remaining limit | | --- | --- | | `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. | | `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. | | `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. | | `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. | | `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. | | `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. | ## What remains undecided [Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the specialized capability decisions. The current music-generation implementation is tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and [API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every former capability. An agent or local skill may help prepare inputs, but that does not establish a hosted route or compatibility with the former request. This is a reference correction. No provider run or audio-quality check was performed to make these availability statements. "},{"slug":"api-reference/posts/get","title":"Get Artist Posts","description":"Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections.","category":"Content","group":"Posts & Comments","source":"api-reference/posts/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/posts","spec":"social.json"},"searchText":"Get Artist Posts Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections. Content Posts & Comments GET /api/artists/{id}/posts "},{"slug":"api-reference/comments/get","title":"Get Comments","description":"Read saved comments on an authorized creator’s linked posts","category":"Content","group":"Posts & Comments","source":"api-reference/comments/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/comments","spec":"social.json"},"searchText":"Get Comments Read saved comments on an authorized creator’s linked posts Content Posts & Comments GET /api/comments "},{"slug":"api-reference/social/scrape","title":"Social Scrape","description":"Trigger a scrape of one social profile. Use [Get Artist Socials](/api-reference/artists/socials) first to get the social `id`. The response contains scraper run metadata; poll it with the [Scraper Results API](/api-reference/apify/scraper).","category":"Social Media","group":"Social","source":"api-reference/social/scrape.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/socials/{id}/scrape","spec":"social.json"},"searchText":"Social Scrape Trigger a scrape of one social profile. Use [Get Artist Socials](/api-reference/artists/socials) first to get the social `id`. The response contains scraper run metadata; poll it with the [Scraper Results API](/api-reference/apify/scraper). Social Media Social POST /api/socials/{id}/scrape "},{"slug":"api-reference/artist/socials-scrape","title":"api-reference/artist/socials-scrape","description":"Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper).","category":"Social Media","group":"Social","source":"api-reference/artist/socials-scrape.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/artist/socials/scrape","spec":"releases.json"},"searchText":"api-reference/artist/socials-scrape Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper). Social Media Social POST /api/artist/socials/scrape "},{"slug":"api-reference/spotify/search","title":"Search","description":"Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/search.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/search","spec":"social.json"},"searchText":"Search Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API. Social Media Spotify GET /api/spotify/search "},{"slug":"api-reference/spotify/artist","title":"Get Artist","description":"Get Spotify catalog information for a single artist identified by their unique Spotify ID.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/","spec":"social.json"},"searchText":"Get Artist Get Spotify catalog information for a single artist identified by their unique Spotify ID. Social Media Spotify GET /api/spotify/artist/ "},{"slug":"api-reference/spotify/artist-albums","title":"Get Artist Albums","description":"Get Spotify catalog information about an artist's albums.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist-albums.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/albums","spec":"social.json"},"searchText":"Get Artist Albums Get Spotify catalog information about an artist's albums. Social Media Spotify GET /api/spotify/artist/albums "},{"slug":"api-reference/spotify/artist-top-tracks","title":"Get Artist Top Tracks","description":"Get an artist's top tracks by country.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist-top-tracks.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/topTracks","spec":"social.json"},"searchText":"Get Artist Top Tracks Get an artist's top tracks by country. Social Media Spotify GET /api/spotify/artist/topTracks "},{"slug":"api-reference/spotify/album","title":"Get Album","description":"Get Spotify catalog information for a single album.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/album.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/album","spec":"social.json"},"searchText":"Get Album Get Spotify catalog information for a single album. Social Media Spotify GET /api/spotify/album "},{"slug":"api-reference/apple/songs","title":"Songs by ISRC","description":"Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose.","category":"Social Media","group":"Apple Music","source":"api-reference/apple/songs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/apple/songs","spec":"social.json"},"searchText":"Songs by ISRC Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose. Social Media Apple Music GET /api/apple/songs "},{"slug":"api-reference/apify/scraper","title":"Scraper Results","description":"Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results.","category":"Social Media","group":"Apify","source":"api-reference/apify/scraper.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/apify/runs/{runId}","spec":"social.json"},"searchText":"Scraper Results Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results. Social Media Apify GET /api/apify/runs/{runId} "},{"slug":"api-reference/agents/signup","title":"Agent Signup","description":"Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key.","category":"Agents & Sandboxes","group":"Agent Onboarding","source":"api-reference/agents/signup.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/signup","spec":"accounts.json"},"searchText":"Agent Signup Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key. Agents & Sandboxes Agent Onboarding POST /api/agents/signup "},{"slug":"api-reference/agents/verify","title":"Verify Agent Email","description":"Verify an agent's email with the code sent during signup. Returns an API key on success.","category":"Agents & Sandboxes","group":"Agent Onboarding","source":"api-reference/agents/verify.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/verify","spec":"accounts.json"},"searchText":"Verify Agent Email Verify an agent's email with the code sent during signup. Returns an API key on success. Agents & Sandboxes Agent Onboarding POST /api/agents/verify "},{"slug":"agents","title":"Agents","description":"Verified email onboarding for a separate Recoup REST API key.","category":"Agents & Sandboxes","group":"Agents","source":"agents.mdx","body":"## Use your real account\n\nPrefer [MCP OAuth](/mcp-oauth) for supported AI hosts. REST integrations need a\nseparate API key; an OAuth connection does not export one into your shell.\n\nUse the email verification flow below with an address the user controls. Keep\nthe returned key out of messages and logs, and store it through a secret facility\nor an explicitly approved local environment file. Never use a disposable account\nto recover an existing user's data.\n\nThe source signup contract also supports immediate keys for new `agent+` addresses.\nThat creates a separate identity; it does not grant customer or organization access.\nIt is not the recommended onboarding path for customer work. Multiple API keys per\naccount are supported, without revoking existing keys.\n\n## Standard signup (email verification)\n\nIf you're building a human-facing integration and want the user to verify their real email, use an email address the user controls:\n\nStep 1 — request a verification code:\n\n```bash\ncurl -X POST \"https://api.recoupable.dev/api/agents/signup\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\"}'\n```\n\nStep 2 — submit the 6-digit code from the verification email:\n\n```bash\ncurl -X POST \"https://api.recoupable.dev/api/agents/verify\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"code\": \"123456\"}'\n```\n\nResponse:\n\n```json\n{\n \"account_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"api_key\": \"recoup_sk_abc123...\",\n \"message\": \"Verified\"\n}\n```\n\n## Using your API key\n\nPass the returned `api_key` in the `x-api-key` header on every authenticated request:\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\nSee [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request.\n","headings":[{"title":"Use your real account","id":"use-your-real-account"},{"title":"Standard signup (email verification)","id":"standard-signup-email-verification"},{"title":"Using your API key","id":"using-your-api-key"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"use-your-real-account\",\n children: \"Use your real account\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Prefer \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for supported AI hosts. REST integrations need a\\nseparate API key; an OAuth connection does not export one into your shell.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the email verification flow below with an address the user controls. Keep\\nthe returned key out of messages and logs, and store it through a secret facility\\nor an explicitly approved local environment file. Never use a disposable account\\nto recover an existing user's data.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The source signup contract also supports immediate keys for new \", _jsx(_components.code, {\n children: \"agent+\"\n }), \" addresses.\\nThat creates a separate identity; it does not grant customer or organization access.\\nIt is not the recommended onboarding path for customer work. Multiple API keys per\\naccount are supported, without revoking existing keys.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"standard-signup-email-verification\",\n children: \"Standard signup (email verification)\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you're building a human-facing integration and want the user to verify their real email, use an email address the user controls:\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Step 1 — request a verification code:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X POST \\\"https://api.recoupable.dev/api/agents/signup\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"email\\\": \\\"you@example.com\\\"}'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Step 2 — submit the 6-digit code from the verification email:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X POST \\\"https://api.recoupable.dev/api/agents/verify\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"email\\\": \\\"you@example.com\\\", \\\"code\\\": \\\"123456\\\"}'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\\n \\\"api_key\\\": \\\"recoup_sk_abc123...\\\",\\n \\\"message\\\": \\\"Verified\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"using-your-api-key\",\n children: \"Using your API key\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass the returned \", _jsx(_components.code, {\n children: \"api_key\"\n }), \" in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header on every authenticated request:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"Authentication\"\n }), \" for the full authentication model, including organization access and Bearer token support, and \", _jsx(_components.a, {\n href: \"/quickstart\",\n children: \"Quickstart\"\n }), \" for your first end-to-end request.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Agents Verified email onboarding for a separate Recoup REST API key. Agents & Sandboxes Agents ## Use your real account Prefer [MCP OAuth](/mcp-oauth) for supported AI hosts. REST integrations need a separate API key; an OAuth connection does not export one into your shell. Use the email verification flow below with an address the user controls. Keep the returned key out of messages and logs, and store it through a secret facility or an explicitly approved local environment file. Never use a disposable account to recover an existing user's data. The source signup contract also supports immediate keys for new `agent+` addresses. That creates a separate identity; it does not grant customer or organization access. It is not the recommended onboarding path for customer work. Multiple API keys per account are supported, without revoking existing keys. ## Standard signup (email verification) If you're building a human-facing integration and want the user to verify their real email, use an email address the user controls: Step 1 — request a verification code: Step 2 — submit the 6-digit code from the verification email: Response: ## Using your API key Pass the returned `api_key` in the `x-api-key` header on every authenticated request: See [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request. "},{"slug":"content-agent","title":"Content Agent","description":"Use hosted creative presets and current image, video and composition primitives.","category":"Agents & Sandboxes","group":"Agents","source":"content-agent.mdx","body":"## Release Packs\n\nFor a song-centered content pack, use [Release Packs](/release-packs): collect\nessential context inline, preserve one job, quote the complete scope and produce\nreviewed media. New releases, catalog rediscovery, anniversaries, reissues and\nremixes use the same brief-driven path. These pack operations do not require an\nexisting artist or repository; availability depends on deployed host tools.\n\n## Hosted workflows\n\n`POST /api/content/create` retains the hosted preset workflow. Supply the authorized\n`artist_account_id`, optional `template`, `images`, `songs`, `batch` (defaults to 1; range 1–30), `lipsync`, `upscale`\nand `caption_length`. Discover templates through `/api/content/templates` and its\ndetail route. The response contains `runIds`; poll `/api/tasks/runs?runId=...` until\nterminal. Report failures and inspect the final artifact before delivery.\n\nHosted lipsync is a supported preset intent. The coordinated API/worker repair\nrestores the selected song window to the fixed audio-to-video path; that repaired\njourney is release-pending until deployment and actual output verification.\n\n## Direct primitives\n\nFor images use `POST /api/content/image` with `prompt` and up to 10 unique\n`image_urls`. The house model is Muse Image, switching to its edit path when\nreferences are present. New clients must use `image_urls`; compatibility aliases\nare translated by the reconciliation release.\n\nFor video use `POST /api/content/video` with `prompt`, optional `image_url` and\n`end_image_url`, integer `duration` 5–15, and `resolution` `480P` or `768P`.\nThe house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model,\nreference-only, extend, `video_url` or `audio_url` request control. Unsupported\nsemantic inputs return 400 in the reconciliation release, before paid generation.\n\nThe dedicated `/api/content/lipsync` primitive restores the existing fixed LTX\nmodel for the worker; it is not assumed available on an older deployment.\nCaption, transcribe, analyze, upscale and edit have their own endpoint contracts.\nLocal ffmpeg composition can crop, trim, overlay or mux a song; it does not create\nmouth synchronization or prove a hosted generation succeeded.\n\n## Cost and evidence\n\nEach generation/inference stage can consume credits. `/api/content/estimate`\nreturns an advisory estimate, not a guaranteed price or complete final ledger.\nA later failed composition does not imply that completed upstream work was free.\nOn insufficient credits, surface `billingUrl` and stop. Consult [Credits](/credits).\n\nRecord image inspection, motion review and audio playback. The worker checks for\nan audio stream on lipsync output before composition; perceptual mouth alignment\nstill requires inspection. Automated checks do not replace human QA.\n\n## Slack integration\n\nThe separate [Slack webhook](/api-reference/content-agent/webhook) handles\nContent Agent mentions. Its request/event contract and the [completion callback](/api-reference/content-agent/callback) are distinct from direct primitives.\nWorkspace operators must configure the Slack application and service credentials;\ninstalling a creative skill does not install that integration.\n\n### Set up the Slack app\n\nCreate a Slack app, enable the `chat:write` and `app_mentions:read` bot scopes,\nand subscribe to `app_mention` events at\n`https://api.recoupable.dev/api/content-agent/slack`. Install it in the intended\nworkspace and invite it to the channel.\n\nConfigure `SLACK_CONTENT_BOT_TOKEN`, `SLACK_CONTENT_SIGNING_SECRET`,\n`CODING_AGENT_CALLBACK_SECRET` and `REDIS_URL` in the Recoup API service.\nThe existing Tasks worker uses the same `CODING_AGENT_CALLBACK_SECRET` for\ncompletion callbacks and its authorized Recoup credential and API base URL.\nKeep these values in service secret settings. The current callback secret name\nis `CODING_AGENT_CALLBACK_SECRET`; `CONTENT_AGENT_CALLBACK_SECRET` is obsolete.\n\nSlack sends the signed-request headers listed in the [webhook reference](/api-reference/content-agent/webhook).\nKeep `SLACK_CONTENT_SIGNING_SECRET` matched to that Slack app. Setup requests\nwith missing or invalid signatures, a timestamp outside the five-minute window,\nor an unavailable signing secret return `401` with plain-text `Unauthorized`.\nA verified setup request returns its JSON challenge. If setup fails, check the\napp secret and service clock against [Slack request verification](https://docs.slack.dev/authentication/verifying-requests-from-slack/).\nOrdinary event acknowledgements come from the Slack adapter; they acknowledge\nreceipt while generation completes separately.\n\nMention the installed bot with the authorized artist account UUID:\n\n```text\n@RecoupContentAgent ARTIST_ACCOUNT_UUID artist-caption-bedroom batch=1\n```\n\nThe template, `batch=N` (1–30) and `lipsync` flags are optional. Check the\nacknowledgment, then inspect the completed result or reported failure in the\nthread. Generated output still requires the inspection described above.\n","headings":[{"title":"Release Packs","id":"release-packs"},{"title":"Hosted workflows","id":"hosted-workflows"},{"title":"Direct primitives","id":"direct-primitives"},{"title":"Cost and evidence","id":"cost-and-evidence"},{"title":"Slack integration","id":"slack-integration"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"release-packs\",\n children: \"Release Packs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a song-centered content pack, use \", _jsx(_components.a, {\n href: \"/release-packs\",\n children: \"Release Packs\"\n }), \": collect\\nessential context inline, preserve one job, quote the complete scope and produce\\nreviewed media. New releases, catalog rediscovery, anniversaries, reissues and\\nremixes use the same brief-driven path. These pack operations do not require an\\nexisting artist or repository; availability depends on deployed host tools.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hosted-workflows\",\n children: \"Hosted workflows\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/create\"\n }), \" retains the hosted preset workflow. Supply the authorized\\n\", _jsx(_components.code, {\n children: \"artist_account_id\"\n }), \", optional \", _jsx(_components.code, {\n children: \"template\"\n }), \", \", _jsx(_components.code, {\n children: \"images\"\n }), \", \", _jsx(_components.code, {\n children: \"songs\"\n }), \", \", _jsx(_components.code, {\n children: \"batch\"\n }), \" (defaults to 1; range 1–30), \", _jsx(_components.code, {\n children: \"lipsync\"\n }), \", \", _jsx(_components.code, {\n children: \"upscale\"\n }), \"\\nand \", _jsx(_components.code, {\n children: \"caption_length\"\n }), \". Discover templates through \", _jsx(_components.code, {\n children: \"/api/content/templates\"\n }), \" and its\\ndetail route. The response contains \", _jsx(_components.code, {\n children: \"runIds\"\n }), \"; poll \", _jsx(_components.code, {\n children: \"/api/tasks/runs?runId=...\"\n }), \" until\\nterminal. Report failures and inspect the final artifact before delivery.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Hosted lipsync is a supported preset intent. The coordinated API/worker repair\\nrestores the selected song window to the fixed audio-to-video path; that repaired\\njourney is release-pending until deployment and actual output verification.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"direct-primitives\",\n children: \"Direct primitives\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For images use \", _jsx(_components.code, {\n children: \"POST /api/content/image\"\n }), \" with \", _jsx(_components.code, {\n children: \"prompt\"\n }), \" and up to 10 unique\\n\", _jsx(_components.code, {\n children: \"image_urls\"\n }), \". The house model is Muse Image, switching to its edit path when\\nreferences are present. New clients must use \", _jsx(_components.code, {\n children: \"image_urls\"\n }), \"; compatibility aliases\\nare translated by the reconciliation release.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For video use \", _jsx(_components.code, {\n children: \"POST /api/content/video\"\n }), \" with \", _jsx(_components.code, {\n children: \"prompt\"\n }), \", optional \", _jsx(_components.code, {\n children: \"image_url\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"end_image_url\"\n }), \", integer \", _jsx(_components.code, {\n children: \"duration\"\n }), \" 5–15, and \", _jsx(_components.code, {\n children: \"resolution\"\n }), \" \", _jsx(_components.code, {\n children: \"480P\"\n }), \" or \", _jsx(_components.code, {\n children: \"768P\"\n }), \".\\nThe house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model,\\nreference-only, extend, \", _jsx(_components.code, {\n children: \"video_url\"\n }), \" or \", _jsx(_components.code, {\n children: \"audio_url\"\n }), \" request control. Unsupported\\nsemantic inputs return 400 in the reconciliation release, before paid generation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The dedicated \", _jsx(_components.code, {\n children: \"/api/content/lipsync\"\n }), \" primitive restores the existing fixed LTX\\nmodel for the worker; it is not assumed available on an older deployment.\\nCaption, transcribe, analyze, upscale and edit have their own endpoint contracts.\\nLocal ffmpeg composition can crop, trim, overlay or mux a song; it does not create\\nmouth synchronization or prove a hosted generation succeeded.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"cost-and-evidence\",\n children: \"Cost and evidence\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each generation/inference stage can consume credits. \", _jsx(_components.code, {\n children: \"/api/content/estimate\"\n }), \"\\nreturns an advisory estimate, not a guaranteed price or complete final ledger.\\nA later failed composition does not imply that completed upstream work was free.\\nOn insufficient credits, surface \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \" and stop. Consult \", _jsx(_components.a, {\n href: \"/credits\",\n children: \"Credits\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Record image inspection, motion review and audio playback. The worker checks for\\nan audio stream on lipsync output before composition; perceptual mouth alignment\\nstill requires inspection. Automated checks do not replace human QA.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"slack-integration\",\n children: \"Slack integration\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The separate \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/webhook\",\n children: \"Slack webhook\"\n }), \" handles\\nContent Agent mentions. Its request/event contract and the \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/callback\",\n children: \"completion callback\"\n }), \" are distinct from direct primitives.\\nWorkspace operators must configure the Slack application and service credentials;\\ninstalling a creative skill does not install that integration.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"set-up-the-slack-app\",\n children: \"Set up the Slack app\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Create a Slack app, enable the \", _jsx(_components.code, {\n children: \"chat:write\"\n }), \" and \", _jsx(_components.code, {\n children: \"app_mentions:read\"\n }), \" bot scopes,\\nand subscribe to \", _jsx(_components.code, {\n children: \"app_mention\"\n }), \" events at\\n\", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/api/content-agent/slack\"\n }), \". Install it in the intended\\nworkspace and invite it to the channel.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Configure \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_BOT_TOKEN\"\n }), \", \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_SIGNING_SECRET\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \" and \", _jsx(_components.code, {\n children: \"REDIS_URL\"\n }), \" in the Recoup API service.\\nThe existing Tasks worker uses the same \", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \" for\\ncompletion callbacks and its authorized Recoup credential and API base URL.\\nKeep these values in service secret settings. The current callback secret name\\nis \", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \"; \", _jsx(_components.code, {\n children: \"CONTENT_AGENT_CALLBACK_SECRET\"\n }), \" is obsolete.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Slack sends the signed-request headers listed in the \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/webhook\",\n children: \"webhook reference\"\n }), \".\\nKeep \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_SIGNING_SECRET\"\n }), \" matched to that Slack app. Setup requests\\nwith missing or invalid signatures, a timestamp outside the five-minute window,\\nor an unavailable signing secret return \", _jsx(_components.code, {\n children: \"401\"\n }), \" with plain-text \", _jsx(_components.code, {\n children: \"Unauthorized\"\n }), \".\\nA verified setup request returns its JSON challenge. If setup fails, check the\\napp secret and service clock against \", _jsx(_components.a, {\n href: \"https://docs.slack.dev/authentication/verifying-requests-from-slack/\",\n children: \"Slack request verification\"\n }), \".\\nOrdinary event acknowledgements come from the Slack adapter; they acknowledge\\nreceipt while generation completes separately.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Mention the installed bot with the authorized artist account UUID:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-text\",\n children: \"@RecoupContentAgent ARTIST_ACCOUNT_UUID artist-caption-bedroom batch=1\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The template, \", _jsx(_components.code, {\n children: \"batch=N\"\n }), \" (1–30) and \", _jsx(_components.code, {\n children: \"lipsync\"\n }), \" flags are optional. Check the\\nacknowledgment, then inspect the completed result or reported failure in the\\nthread. Generated output still requires the inspection described above.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Content Agent Use hosted creative presets and current image, video and composition primitives. Agents & Sandboxes Agents ## Release Packs For a song-centered content pack, use [Release Packs](/release-packs): collect essential context inline, preserve one job, quote the complete scope and produce reviewed media. New releases, catalog rediscovery, anniversaries, reissues and remixes use the same brief-driven path. These pack operations do not require an existing artist or repository; availability depends on deployed host tools. ## Hosted workflows `POST /api/content/create` retains the hosted preset workflow. Supply the authorized `artist_account_id`, optional `template`, `images`, `songs`, `batch` (defaults to 1; range 1–30), `lipsync`, `upscale` and `caption_length`. Discover templates through `/api/content/templates` and its detail route. The response contains `runIds`; poll `/api/tasks/runs?runId=...` until terminal. Report failures and inspect the final artifact before delivery. Hosted lipsync is a supported preset intent. The coordinated API/worker repair restores the selected song window to the fixed audio-to-video path; that repaired journey is release-pending until deployment and actual output verification. ## Direct primitives For images use `POST /api/content/image` with `prompt` and up to 10 unique `image_urls`. The house model is Muse Image, switching to its edit path when references are present. New clients must use `image_urls`; compatibility aliases are translated by the reconciliation release. For video use `POST /api/content/video` with `prompt`, optional `image_url` and `end_image_url`, integer `duration` 5–15, and `resolution` `480P` or `768P`. The house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model, reference-only, extend, `video_url` or `audio_url` request control. Unsupported semantic inputs return 400 in the reconciliation release, before paid generation. The dedicated `/api/content/lipsync` primitive restores the existing fixed LTX model for the worker; it is not assumed available on an older deployment. Caption, transcribe, analyze, upscale and edit have their own endpoint contracts. Local ffmpeg composition can crop, trim, overlay or mux a song; it does not create mouth synchronization or prove a hosted generation succeeded. ## Cost and evidence Each generation/inference stage can consume credits. `/api/content/estimate` returns an advisory estimate, not a guaranteed price or complete final ledger. A later failed composition does not imply that completed upstream work was free. On insufficient credits, surface `billingUrl` and stop. Consult [Credits](/credits). Record image inspection, motion review and audio playback. The worker checks for an audio stream on lipsync output before composition; perceptual mouth alignment still requires inspection. Automated checks do not replace human QA. ## Slack integration The separate [Slack webhook](/api-reference/content-agent/webhook) handles Content Agent mentions. Its request/event contract and the [completion callback](/api-reference/content-agent/callback) are distinct from direct primitives. Workspace operators must configure the Slack application and service credentials; installing a creative skill does not install that integration. ### Set up the Slack app Create a Slack app, enable the `chat:write` and `app_mentions:read` bot scopes, and subscribe to `app_mention` events at `https://api.recoupable.dev/api/content-agent/slack`. Install it in the intended workspace and invite it to the channel. Configure `SLACK_CONTENT_BOT_TOKEN`, `SLACK_CONTENT_SIGNING_SECRET`, `CODING_AGENT_CALLBACK_SECRET` and `REDIS_URL` in the Recoup API service. The existing Tasks worker uses the same `CODING_AGENT_CALLBACK_SECRET` for completion callbacks and its authorized Recoup credential and API base URL. Keep these values in service secret settings. The current callback secret name is `CODING_AGENT_CALLBACK_SECRET`; `CONTENT_AGENT_CALLBACK_SECRET` is obsolete. Slack sends the signed-request headers listed in the [webhook reference](/api-reference/content-agent/webhook). Keep `SLACK_CONTENT_SIGNING_SECRET` matched to that Slack app. Setup requests with missing or invalid signatures, a timestamp outside the five-minute window, or an unavailable signing secret return `401` with plain-text `Unauthorized`. A verified setup request returns its JSON challenge. If setup fails, check the app secret and service clock against [Slack request verification](https://docs.slack.dev/authentication/verifying-requests-from-slack/). Ordinary event acknowledgements come from the Slack adapter; they acknowledge receipt while generation completes separately. Mention the installed bot with the authorized artist account UUID: The template, `batch=N` (1–30) and `lipsync` flags are optional. Check the acknowledgment, then inspect the completed result or reported failure in the thread. Generated output still requires the inspection described above. "},{"slug":"release-packs","title":"Release Packs","description":"Turn a song and a campaign occasion into a coherent set of reviewed music assets.","category":"Agents & Sandboxes","group":"Agents","source":"release-packs.mdx","body":"\nThis contract accompanies the Release Packs first-use rollout. Availability depends\non the deployed API and the tools exposed by your connected host. A plugin download\nor successful sign-in alone does not establish that generation is available.\n\n\n## Start with the music\n\nAsk your agent: **“Create a release pack for this song.”** Supply the audio or an\naccessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a\nreissue, a remix, or a catalog rediscovery campaign.\n\nThe agent reuses information you have already supplied and any selected, accessible\nRecoup context. It asks only for essential gaps: the correct artist and recording,\nthe occasion, and artwork or creative direction. You can ask it to propose a\ndirection from the music instead. It must distinguish that proposal from your\nestablished branding.\n\nYou do not need an existing artist profile, Spotify history, connected social\naccounts, a catalog import, or a GitHub workspace to prepare a pack. An empty\nRecoup roster is a valid new account. Sign in through your host's Recoup connection\nwhen the agent needs authenticated execution; it should resume the same request.\n\n**“Plan a release” is a different request.** It produces a creative brief and\nrollout plan. Ask for a release pack to produce media, or ask for both so the agent\ncan carry the same brief into production.\n\nWhen ChatGPT supplies a selected attachment to the upload tool, the tool accepts\nits host file reference directly. It imports the selected download URL into\nprivate Recoup storage and validates the actual media bytes. Other hosts can use\nthe supported source URL, inline or signed-upload modes; a filename alone is not\nan accessible recording.\n\nFor direct API uploads, small inline files are limited to approximately 3 MB\n(4,000,000 base64 characters). For normal song files, request a private signed\nupload, transfer the file and finalize it, or import an accessible HTTPS source\nup to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable\nonly after the agent can access its actual bytes. Audio formats include MP3,\nWAV, FLAC and M4A. Source images can be PNG, JPEG or WebP.\n\n## What the brief contains\n\n| Input | How it is used |\n| --- | --- |\n| Artist, song and exact version | Keep the recording, remix and artist identity consistent |\n| Real audio and selected hook | Put the correct music into the finished clips |\n| Occasion | Choose relevant concepts and copy rather than defaulting to “out now” |\n| Creative direction or references | Keep a coherent visual family and voice |\n| Primary action and destination | Write relevant captions without inventing links |\n| Audience, platforms and constraints | Choose useful formats and respect supplied boundaries |\n\nFor anniversaries, the original release date and campaign date are separate. If\nthe original date is unknown, the agent must obtain it before making dated\nanniversary claims. A catalog request needs a bounded selection of recordings;\nit must not silently generate a pack for every track.\n\nResearch enriches the brief. Missing research or audience metrics should not\nforce unrelated onboarding or fabricated statistics. Existing artwork and\nsupplied preferences can be enough to propose strong creative work. An artist's\nface is optional; artwork-led and typographic work are valid directions.\n\n## Scope and budget before generation\n\n### Save a direction and choose how involved to be\n\nConnections exposing `brief.creative_context` can save an established visual world,\na rough idea or an exploratory direction in the same pack. The field is optional;\nolder connections keep their existing brief behavior. It holds attributed references,\nup to three direction candidates and the selected candidate.\n\n**Run with it** uses `working_mode: \"autonomous\"`: the agent records its direction\nselection and continues within the approved budget. **Show me directions first**\nuses `working_mode: \"guided\"`: final quoting and generation wait for a selection\nrecorded from the customer's feedback. An agent's own choice does not count as\ncustomer selection in guided mode.\n\nSave candidates under `directions`, then record `selection.direction_id`,\n`selection.selected_by` (`customer` or `agent`) and a short `decision_note`.\nDirection and reference IDs must be unique within this brief; selections cannot\npoint to another pack's candidate. Updating these fields follows the same saved\njob and expected-revision rules and invalidates its earlier quote.\n\nA reference manifest item declares its source, media type and `usage`:\n`reference_only` is inspiration, while `production` explicitly makes an image\neligible as a selected generation input. Only production images referenced by\nthe chosen direction enter the renderer. Together with explicit legacy\n`reference_image_urls`, at most five distinct production images are supported.\nThe original source manifest stays unchanged when production inputs are resolved.\n\nThis first slice accepts supplied direction boards through an optional `board_url`.\nIt does not add automatic mood-board generation, public-profile harvesting or new\nasset types. Discover those capabilities before promising them. An optional\ncustomer checkpoint does not authorize additional spending or publication.\n\nPreparation and generation are separate operations. Before paid production, the\nagent shows the proposed direction, deliverables, cost scope and maximum budget.\nThe quote binds the current brief and deliverables. Changing the song or scope\nrequires a new quote; an earlier approval cannot silently authorize different work.\n\nThe default scope is 15 creative pieces: eight video clips, four quote cards, one\nartwork, one carousel and one visualizer, with captions. A carousel is one piece;\nits slides and alternate aspect ratios are identified as components or variants.\nYou can request a smaller scope. The quote must describe the actual selected work,\nincluding chargeable stages and any retry allowance. Current quotes charge for\nimage and motion generation; captioning, audio analysis, composition and inspection\nare included without an added customer fee. The approved amount is held before\nproduction; unused stages are refunded. A new paid retry needs its own quote.\n\nThe older `GET /api/content/estimate` is an advisory per-video estimate. It is not\na complete Release Packs quote. On insufficient credits the agent surfaces the\nreturned `billingUrl`; it must not buy credits, switch accounts or retry paid\ngeneration automatically.\n\n## One job, with visible progress\n\nThe pack retains its brief, revision, quote, individual asset states and completed\nwork. Signing in, waiting for a render, or recovering from a failed stage should\nnot make you repeat the request or regenerate the whole pack.\n\nThe first representative asset is produced and inspected early. The agent then\ncontinues the agreed batch within your budget, unless you requested a preview\ncheckpoint. Progress distinguishes requested, generated, inspected and delivered\nassets. A partly generated pack is reported as partial.\n\n## Review and delivery\n\nA finished music-bearing asset must contain the selected recording and the correct\naudio window. Inspection covers sound, timing, duration, framing, readable text,\nvisual consistency and the campaign brief. A render request, a prompt or a concept\nis not a finished asset. Static image inspection and video inspection are separate.\n\nDelivery includes previews, usable files, captions, a manifest and any unresolved\ngaps. The agent retains successful work when a stage fails and retries only within\nthe approved scope and budget. Release Packs stops at the assets: posting and\nscheduling need a separate request.\n\nAfter delivery, you can save confirmed artist preferences for next time. A\none-off creative proposal must not overwrite established branding or become a\npermanent public knowledge-base entry automatically.\n\n## API and connected tools\n\nConnected operations are `prepare_release_pack`, `get_release_pack`,\n`estimate_release_pack`, `generate_release_pack`, `retry_release_pack`,\n`upload_release_pack_asset` and `export_release_pack`. Discover their actual schemas\nin the connected host; older connections may need a refresh.\n\nThe shared API contract separates preparation, reading, quoting, generation,\nretry and selected-asset upload. Connected tools use the same account and job\nrules. Credentials remain with the host; an agent must not extract OAuth tokens\ninto REST requests or ask for an API key to compensate for a missing MCP tool.\n\nIf a required operation is unavailable, the agent should name that operation,\nretain the brief and explain the next step. It must not claim the entire account\nis disconnected or present a plan as completed media.\n","headings":[{"title":"Start with the music","id":"start-with-the-music"},{"title":"What the brief contains","id":"what-the-brief-contains"},{"title":"Scope and budget before generation","id":"scope-and-budget-before-generation"},{"title":"One job, with visible progress","id":"one-job-with-visible-progress"},{"title":"Review and delivery","id":"review-and-delivery"},{"title":"API and connected tools","id":"api-and-connected-tools"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n }, {Info} = _components;\n if (!Info) _missingMdxReference(\"Info\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Info, {\n children: _jsx(_components.p, {\n children: \"This contract accompanies the Release Packs first-use rollout. Availability depends\\non the deployed API and the tools exposed by your connected host. A plugin download\\nor successful sign-in alone does not establish that generation is available.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"start-with-the-music\",\n children: \"Start with the music\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Ask your agent: \", _jsx(_components.strong, {\n children: \"“Create a release pack for this song.”\"\n }), \" Supply the audio or an\\naccessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a\\nreissue, a remix, or a catalog rediscovery campaign.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The agent reuses information you have already supplied and any selected, accessible\\nRecoup context. It asks only for essential gaps: the correct artist and recording,\\nthe occasion, and artwork or creative direction. You can ask it to propose a\\ndirection from the music instead. It must distinguish that proposal from your\\nestablished branding.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"You do not need an existing artist profile, Spotify history, connected social\\naccounts, a catalog import, or a GitHub workspace to prepare a pack. An empty\\nRecoup roster is a valid new account. Sign in through your host's Recoup connection\\nwhen the agent needs authenticated execution; it should resume the same request.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"“Plan a release” is a different request.\"\n }), \" It produces a creative brief and\\nrollout plan. Ask for a release pack to produce media, or ask for both so the agent\\ncan carry the same brief into production.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"When ChatGPT supplies a selected attachment to the upload tool, the tool accepts\\nits host file reference directly. It imports the selected download URL into\\nprivate Recoup storage and validates the actual media bytes. Other hosts can use\\nthe supported source URL, inline or signed-upload modes; a filename alone is not\\nan accessible recording.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"For direct API uploads, small inline files are limited to approximately 3 MB\\n(4,000,000 base64 characters). For normal song files, request a private signed\\nupload, transfer the file and finalize it, or import an accessible HTTPS source\\nup to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable\\nonly after the agent can access its actual bytes. Audio formats include MP3,\\nWAV, FLAC and M4A. Source images can be PNG, JPEG or WebP.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-the-brief-contains\",\n children: \"What the brief contains\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Input\"\n }), _jsx(_components.th, {\n children: \"How it is used\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Artist, song and exact version\"\n }), _jsx(_components.td, {\n children: \"Keep the recording, remix and artist identity consistent\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Real audio and selected hook\"\n }), _jsx(_components.td, {\n children: \"Put the correct music into the finished clips\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Occasion\"\n }), _jsx(_components.td, {\n children: \"Choose relevant concepts and copy rather than defaulting to “out now”\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Creative direction or references\"\n }), _jsx(_components.td, {\n children: \"Keep a coherent visual family and voice\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Primary action and destination\"\n }), _jsx(_components.td, {\n children: \"Write relevant captions without inventing links\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Audience, platforms and constraints\"\n }), _jsx(_components.td, {\n children: \"Choose useful formats and respect supplied boundaries\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For anniversaries, the original release date and campaign date are separate. If\\nthe original date is unknown, the agent must obtain it before making dated\\nanniversary claims. A catalog request needs a bounded selection of recordings;\\nit must not silently generate a pack for every track.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Research enriches the brief. Missing research or audience metrics should not\\nforce unrelated onboarding or fabricated statistics. Existing artwork and\\nsupplied preferences can be enough to propose strong creative work. An artist's\\nface is optional; artwork-led and typographic work are valid directions.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"scope-and-budget-before-generation\",\n children: \"Scope and budget before generation\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"save-a-direction-and-choose-how-involved-to-be\",\n children: \"Save a direction and choose how involved to be\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connections exposing \", _jsx(_components.code, {\n children: \"brief.creative_context\"\n }), \" can save an established visual world,\\na rough idea or an exploratory direction in the same pack. The field is optional;\\nolder connections keep their existing brief behavior. It holds attributed references,\\nup to three direction candidates and the selected candidate.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Run with it\"\n }), \" uses \", _jsx(_components.code, {\n children: \"working_mode: \\\"autonomous\\\"\"\n }), \": the agent records its direction\\nselection and continues within the approved budget. \", _jsx(_components.strong, {\n children: \"Show me directions first\"\n }), \"\\nuses \", _jsx(_components.code, {\n children: \"working_mode: \\\"guided\\\"\"\n }), \": final quoting and generation wait for a selection\\nrecorded from the customer's feedback. An agent's own choice does not count as\\ncustomer selection in guided mode.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save candidates under \", _jsx(_components.code, {\n children: \"directions\"\n }), \", then record \", _jsx(_components.code, {\n children: \"selection.direction_id\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"selection.selected_by\"\n }), \" (\", _jsx(_components.code, {\n children: \"customer\"\n }), \" or \", _jsx(_components.code, {\n children: \"agent\"\n }), \") and a short \", _jsx(_components.code, {\n children: \"decision_note\"\n }), \".\\nDirection and reference IDs must be unique within this brief; selections cannot\\npoint to another pack's candidate. Updating these fields follows the same saved\\njob and expected-revision rules and invalidates its earlier quote.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A reference manifest item declares its source, media type and \", _jsx(_components.code, {\n children: \"usage\"\n }), \":\\n\", _jsx(_components.code, {\n children: \"reference_only\"\n }), \" is inspiration, while \", _jsx(_components.code, {\n children: \"production\"\n }), \" explicitly makes an image\\neligible as a selected generation input. Only production images referenced by\\nthe chosen direction enter the renderer. Together with explicit legacy\\n\", _jsx(_components.code, {\n children: \"reference_image_urls\"\n }), \", at most five distinct production images are supported.\\nThe original source manifest stays unchanged when production inputs are resolved.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This first slice accepts supplied direction boards through an optional \", _jsx(_components.code, {\n children: \"board_url\"\n }), \".\\nIt does not add automatic mood-board generation, public-profile harvesting or new\\nasset types. Discover those capabilities before promising them. An optional\\ncustomer checkpoint does not authorize additional spending or publication.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Preparation and generation are separate operations. Before paid production, the\\nagent shows the proposed direction, deliverables, cost scope and maximum budget.\\nThe quote binds the current brief and deliverables. Changing the song or scope\\nrequires a new quote; an earlier approval cannot silently authorize different work.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The default scope is 15 creative pieces: eight video clips, four quote cards, one\\nartwork, one carousel and one visualizer, with captions. A carousel is one piece;\\nits slides and alternate aspect ratios are identified as components or variants.\\nYou can request a smaller scope. The quote must describe the actual selected work,\\nincluding chargeable stages and any retry allowance. Current quotes charge for\\nimage and motion generation; captioning, audio analysis, composition and inspection\\nare included without an added customer fee. The approved amount is held before\\nproduction; unused stages are refunded. A new paid retry needs its own quote.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The older \", _jsx(_components.code, {\n children: \"GET /api/content/estimate\"\n }), \" is an advisory per-video estimate. It is not\\na complete Release Packs quote. On insufficient credits the agent surfaces the\\nreturned \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \"; it must not buy credits, switch accounts or retry paid\\ngeneration automatically.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"one-job-with-visible-progress\",\n children: \"One job, with visible progress\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The pack retains its brief, revision, quote, individual asset states and completed\\nwork. Signing in, waiting for a render, or recovering from a failed stage should\\nnot make you repeat the request or regenerate the whole pack.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The first representative asset is produced and inspected early. The agent then\\ncontinues the agreed batch within your budget, unless you requested a preview\\ncheckpoint. Progress distinguishes requested, generated, inspected and delivered\\nassets. A partly generated pack is reported as partial.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"review-and-delivery\",\n children: \"Review and delivery\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"A finished music-bearing asset must contain the selected recording and the correct\\naudio window. Inspection covers sound, timing, duration, framing, readable text,\\nvisual consistency and the campaign brief. A render request, a prompt or a concept\\nis not a finished asset. Static image inspection and video inspection are separate.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Delivery includes previews, usable files, captions, a manifest and any unresolved\\ngaps. The agent retains successful work when a stage fails and retries only within\\nthe approved scope and budget. Release Packs stops at the assets: posting and\\nscheduling need a separate request.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"After delivery, you can save confirmed artist preferences for next time. A\\none-off creative proposal must not overwrite established branding or become a\\npermanent public knowledge-base entry automatically.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"api-and-connected-tools\",\n children: \"API and connected tools\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connected operations are \", _jsx(_components.code, {\n children: \"prepare_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"get_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"estimate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"generate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"retry_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"upload_release_pack_asset\"\n }), \" and \", _jsx(_components.code, {\n children: \"export_release_pack\"\n }), \". Discover their actual schemas\\nin the connected host; older connections may need a refresh.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The shared API contract separates preparation, reading, quoting, generation,\\nretry and selected-asset upload. Connected tools use the same account and job\\nrules. Credentials remain with the host; an agent must not extract OAuth tokens\\ninto REST requests or ask for an API key to compensate for a missing MCP tool.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If a required operation is unavailable, the agent should name that operation,\\nretain the brief and explain the next step. It must not claim the entire account\\nis disconnected or present a plan as completed media.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Release Packs Turn a song and a campaign occasion into a coherent set of reviewed music assets. Agents & Sandboxes Agents This contract accompanies the Release Packs first-use rollout. Availability depends on the deployed API and the tools exposed by your connected host. A plugin download or successful sign-in alone does not establish that generation is available. ## Start with the music Ask your agent: **“Create a release pack for this song.”** Supply the audio or an accessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a reissue, a remix, or a catalog rediscovery campaign. The agent reuses information you have already supplied and any selected, accessible Recoup context. It asks only for essential gaps: the correct artist and recording, the occasion, and artwork or creative direction. You can ask it to propose a direction from the music instead. It must distinguish that proposal from your established branding. You do not need an existing artist profile, Spotify history, connected social accounts, a catalog import, or a GitHub workspace to prepare a pack. An empty Recoup roster is a valid new account. Sign in through your host's Recoup connection when the agent needs authenticated execution; it should resume the same request. **“Plan a release” is a different request.** It produces a creative brief and rollout plan. Ask for a release pack to produce media, or ask for both so the agent can carry the same brief into production. When ChatGPT supplies a selected attachment to the upload tool, the tool accepts its host file reference directly. It imports the selected download URL into private Recoup storage and validates the actual media bytes. Other hosts can use the supported source URL, inline or signed-upload modes; a filename alone is not an accessible recording. For direct API uploads, small inline files are limited to approximately 3 MB (4,000,000 base64 characters). For normal song files, request a private signed upload, transfer the file and finalize it, or import an accessible HTTPS source up to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable only after the agent can access its actual bytes. Audio formats include MP3, WAV, FLAC and M4A. Source images can be PNG, JPEG or WebP. ## What the brief contains | Input | How it is used | | --- | --- | | Artist, song and exact version | Keep the recording, remix and artist identity consistent | | Real audio and selected hook | Put the correct music into the finished clips | | Occasion | Choose relevant concepts and copy rather than defaulting to “out now” | | Creative direction or references | Keep a coherent visual family and voice | | Primary action and destination | Write relevant captions without inventing links | | Audience, platforms and constraints | Choose useful formats and respect supplied boundaries | For anniversaries, the original release date and campaign date are separate. If the original date is unknown, the agent must obtain it before making dated anniversary claims. A catalog request needs a bounded selection of recordings; it must not silently generate a pack for every track. Research enriches the brief. Missing research or audience metrics should not force unrelated onboarding or fabricated statistics. Existing artwork and supplied preferences can be enough to propose strong creative work. An artist's face is optional; artwork-led and typographic work are valid directions. ## Scope and budget before generation ### Save a direction and choose how involved to be Connections exposing `brief.creative_context` can save an established visual world, a rough idea or an exploratory direction in the same pack. The field is optional; older connections keep their existing brief behavior. It holds attributed references, up to three direction candidates and the selected candidate. **Run with it** uses `working_mode: \"autonomous\"`: the agent records its direction selection and continues within the approved budget. **Show me directions first** uses `working_mode: \"guided\"`: final quoting and generation wait for a selection recorded from the customer's feedback. An agent's own choice does not count as customer selection in guided mode. Save candidates under `directions`, then record `selection.direction_id`, `selection.selected_by` (`customer` or `agent`) and a short `decision_note`. Direction and reference IDs must be unique within this brief; selections cannot point to another pack's candidate. Updating these fields follows the same saved job and expected-revision rules and invalidates its earlier quote. A reference manifest item declares its source, media type and `usage`: `reference_only` is inspiration, while `production` explicitly makes an image eligible as a selected generation input. Only production images referenced by the chosen direction enter the renderer. Together with explicit legacy `reference_image_urls`, at most five distinct production images are supported. The original source manifest stays unchanged when production inputs are resolved. This first slice accepts supplied direction boards through an optional `board_url`. It does not add automatic mood-board generation, public-profile harvesting or new asset types. Discover those capabilities before promising them. An optional customer checkpoint does not authorize additional spending or publication. Preparation and generation are separate operations. Before paid production, the agent shows the proposed direction, deliverables, cost scope and maximum budget. The quote binds the current brief and deliverables. Changing the song or scope requires a new quote; an earlier approval cannot silently authorize different work. The default scope is 15 creative pieces: eight video clips, four quote cards, one artwork, one carousel and one visualizer, with captions. A carousel is one piece; its slides and alternate aspect ratios are identified as components or variants. You can request a smaller scope. The quote must describe the actual selected work, including chargeable stages and any retry allowance. Current quotes charge for image and motion generation; captioning, audio analysis, composition and inspection are included without an added customer fee. The approved amount is held before production; unused stages are refunded. A new paid retry needs its own quote. The older `GET /api/content/estimate` is an advisory per-video estimate. It is not a complete Release Packs quote. On insufficient credits the agent surfaces the returned `billingUrl`; it must not buy credits, switch accounts or retry paid generation automatically. ## One job, with visible progress The pack retains its brief, revision, quote, individual asset states and completed work. Signing in, waiting for a render, or recovering from a failed stage should not make you repeat the request or regenerate the whole pack. The first representative asset is produced and inspected early. The agent then continues the agreed batch within your budget, unless you requested a preview checkpoint. Progress distinguishes requested, generated, inspected and delivered assets. A partly generated pack is reported as partial. ## Review and delivery A finished music-bearing asset must contain the selected recording and the correct audio window. Inspection covers sound, timing, duration, framing, readable text, visual consistency and the campaign brief. A render request, a prompt or a concept is not a finished asset. Static image inspection and video inspection are separate. Delivery includes previews, usable files, captions, a manifest and any unresolved gaps. The agent retains successful work when a stage fails and retries only within the approved scope and budget. Release Packs stops at the assets: posting and scheduling need a separate request. After delivery, you can save confirmed artist preferences for next time. A one-off creative proposal must not overwrite established branding or become a permanent public knowledge-base entry automatically. ## API and connected tools Connected operations are `prepare_release_pack`, `get_release_pack`, `estimate_release_pack`, `generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and `export_release_pack`. Discover their actual schemas in the connected host; older connections may need a refresh. The shared API contract separates preparation, reading, quoting, generation, retry and selected-asset upload. Connected tools use the same account and job rules. Credentials remain with the host; an agent must not extract OAuth tokens into REST requests or ask for an API key to compensate for a missing MCP tool. If a required operation is unavailable, the agent should name that operation, retain the brief and explain the next step. It must not claim the entire account is disconnected or present a plan as completed media. "},{"slug":"api-reference/templates/list","title":"List Templates","description":"List templates","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/agents/templates","spec":"templates.json"},"searchText":"List Templates List templates Agents & Sandboxes Templates GET /api/agents/templates "},{"slug":"api-reference/templates/create","title":"Create Template","description":"Create a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/templates","spec":"templates.json"},"searchText":"Create Template Create a template Agents & Sandboxes Templates POST /api/agents/templates "},{"slug":"api-reference/templates/update","title":"Update Template","description":"Update a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/agents/templates/{id}","spec":"templates.json"},"searchText":"Update Template Update a template Agents & Sandboxes Templates PATCH /api/agents/templates/{id} "},{"slug":"api-reference/templates/delete","title":"Delete Template","description":"Delete a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/agents/templates/{id}","spec":"templates.json"},"searchText":"Delete Template Delete a template Agents & Sandboxes Templates DELETE /api/agents/templates/{id} "},{"slug":"api-reference/templates/favorite","title":"Favorite Template","description":"Toggle favorite on a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/favorite.mdx","body":"","headings":[],"api":{"method":"PUT","path":"/api/agents/templates/{id}/favorite","spec":"templates.json"},"searchText":"Favorite Template Toggle favorite on a template Agents & Sandboxes Templates PUT /api/agents/templates/{id}/favorite "},{"slug":"api-reference/tasks/get","title":"Get Tasks","description":"Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/tasks","spec":"releases.json"},"searchText":"Get Tasks Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id. Agents & Sandboxes Tasks GET /api/tasks "},{"slug":"api-reference/tasks/create","title":"Create Task","description":"Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array).","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/tasks","spec":"releases.json"},"searchText":"Create Task Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array). Agents & Sandboxes Tasks POST /api/tasks "},{"slug":"api-reference/tasks/update","title":"Update Task","description":"Update scheduled task","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/tasks","spec":"releases.json"},"searchText":"Update Task Update scheduled task Agents & Sandboxes Tasks PATCH /api/tasks "},{"slug":"api-reference/tasks/delete","title":"Delete Task","description":"Delete scheduled task","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/tasks","spec":"releases.json"},"searchText":"Delete Task Delete scheduled task Agents & Sandboxes Tasks DELETE /api/tasks "},{"slug":"api-reference/tasks/runs","title":"Get Task Runs","description":"Get task runs","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/runs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/tasks/runs","spec":"releases.json"},"searchText":"Get Task Runs Get task runs Agents & Sandboxes Tasks GET /api/tasks/runs "},{"slug":"api-reference/content-agent/webhook","title":"Slack Webhook","description":"Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread.","category":"Agents & Sandboxes","group":"Content Agent","source":"api-reference/content-agent/webhook.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content-agent/{platform}","spec":"content.json"},"searchText":"Slack Webhook Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread. Agents & Sandboxes Content Agent POST /api/content-agent/{platform} "},{"slug":"api-reference/content-agent/callback","title":"Task Callback","description":"Internal worker callback for a configured content agent. Requires the shared callback secret in x-callback-secret. Public content creation uses POST /api/content/create.","category":"Agents & Sandboxes","group":"Content Agent","source":"api-reference/content-agent/callback.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content-agent/callback","spec":"content.json"},"searchText":"Task Callback Internal worker callback for a configured content agent. Requires the shared callback secret in x-callback-secret. Public content creation uses POST /api/content/create. Agents & Sandboxes Content Agent POST /api/content-agent/callback "},{"slug":"api-reference/sandboxes/list","title":"List Sandboxes","description":"List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandboxes","spec":"content.json"},"searchText":"List Sandboxes List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes GET /api/sandboxes "},{"slug":"api-reference/sandboxes/create","title":"Create Sandbox","description":"Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes","spec":"content.json"},"searchText":"Create Sandbox Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes "},{"slug":"api-reference/sandboxes/snapshot","title":"Update Snapshot","description":"Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/snapshot.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sandboxes","spec":"content.json"},"searchText":"Update Snapshot Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files. Agents & Sandboxes Sandboxes PATCH /api/sandboxes "},{"slug":"api-reference/sandboxes/delete","title":"Delete Sandbox","description":"Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/sandboxes","spec":"content.json"},"searchText":"Delete Sandbox Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes DELETE /api/sandboxes "},{"slug":"api-reference/sandboxes/setup","title":"Setup Sandbox","description":"Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/setup.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/setup","spec":"content.json"},"searchText":"Setup Sandbox Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes/setup "},{"slug":"api-reference/sandboxes/get-file","title":"Get File Contents","description":"Read a file from the authenticated account's Git-backed repository, or an explicitly authorized target account's repository, including resolved submodule paths, on `main`. The repository comes from the [account's snapshot](/api-reference/sandboxes/list). Authenticate with `x-api-key` or an Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/get-file.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandboxes/file","spec":"content.json"},"searchText":"Get File Contents Read a file from the authenticated account's Git-backed repository, or an explicitly authorized target account's repository, including resolved submodule paths, on `main`. The repository comes from the [account's snapshot](/api-reference/sandboxes/list). Authenticate with `x-api-key` or an Authorization Bearer token. Agents & Sandboxes Sandboxes GET /api/sandboxes/file "},{"slug":"api-reference/sandboxes/stage-file","title":"Stage File","description":"Issue a presigned upload token so the browser can upload a file directly to Vercel Blob, then call `POST /api/sandboxes/files` with the resulting blob URL to commit it to the sandbox repo. Use `upload()` from `@vercel/blob/client` rather than calling this route by hand. Max file size 100MB.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/stage-file.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/staged-file","spec":"content.json"},"searchText":"Stage File Issue a presigned upload token so the browser can upload a file directly to Vercel Blob, then call `POST /api/sandboxes/files` with the resulting blob URL to commit it to the sandbox repo. Use `upload()` from `@vercel/blob/client` rather than calling this route by hand. Max file size 100MB. Agents & Sandboxes Sandboxes POST /api/sandboxes/staged-file "},{"slug":"api-reference/sandboxes/upload-files","title":"Upload Files","description":"Upload one or more files to the authenticated account's Git-backed repository. Each file URL is committed separately; paths inside a submodule resolve to that repository. Authenticate with `x-api-key` or an Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/upload-files.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/files","spec":"content.json"},"searchText":"Upload Files Upload one or more files to the authenticated account's Git-backed repository. Each file URL is committed separately; paths inside a submodule resolve to that repository. Authenticate with `x-api-key` or an Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes/files "},{"slug":"api-reference/sessions/create","title":"Create Session","description":"Create session","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions","spec":"sessions.json"},"searchText":"Create Session Create session Agents & Sandboxes Sessions POST /api/sessions "},{"slug":"api-reference/sessions/get","title":"Get Session","description":"Get session by id","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}","spec":"sessions.json"},"searchText":"Get Session Get session by id Agents & Sandboxes Sessions GET /api/sessions/{sessionId} "},{"slug":"api-reference/sessions/patch","title":"Update Session","description":"Rename a session, change lifecycle status, or update line counters.","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/patch.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sessions/{sessionId}","spec":"sessions.json"},"searchText":"Update Session Rename a session, change lifecycle status, or update line counters. Agents & Sandboxes Sessions PATCH /api/sessions/{sessionId} "},{"slug":"api-reference/sessions/list-chats","title":"List Session Chats","description":"List session chats","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/list-chats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}/chats","spec":"sessions.json"},"searchText":"List Session Chats List session chats Agents & Sandboxes Sessions GET /api/sessions/{sessionId}/chats "},{"slug":"api-reference/sessions/create-chat","title":"Create Session Chat","description":"Create session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/create-chat.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions/{sessionId}/chats","spec":"sessions.json"},"searchText":"Create Session Chat Create session chat Agents & Sandboxes Sessions POST /api/sessions/{sessionId}/chats "},{"slug":"api-reference/sessions/get-chat","title":"Get Session Chat","description":"Get session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/get-chat.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Get Session Chat Get session chat Agents & Sandboxes Sessions GET /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/patch-chat","title":"Update Session Chat","description":"Update session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/patch-chat.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Update Session Chat Update session chat Agents & Sandboxes Sessions PATCH /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/delete-chat","title":"Delete Session Chat","description":"Delete session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/delete-chat.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Delete Session Chat Delete session chat Agents & Sandboxes Sessions DELETE /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/mark-chat-read","title":"Mark Chat Read","description":"Marks a session chat as read for the authenticated account.","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/mark-chat-read.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions/{sessionId}/chats/{chatId}/read","spec":"sessions.json"},"searchText":"Mark Chat Read Marks a session chat as read for the authenticated account. Agents & Sandboxes Sessions POST /api/sessions/{sessionId}/chats/{chatId}/read "},{"slug":"api-reference/sandbox/create","title":"Create or restore session sandbox","description":"Create or restore session sandbox","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandbox","spec":"sandbox.json"},"searchText":"Create or restore session sandbox Create or restore session sandbox Agents & Sandboxes Session Sandboxes POST /api/sandbox "},{"slug":"api-reference/sandbox/status","title":"Get session sandbox status","description":"Get session sandbox status","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/status.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandbox/status","spec":"sandbox.json"},"searchText":"Get session sandbox status Get session sandbox status Agents & Sandboxes Session Sandboxes GET /api/sandbox/status "},{"slug":"api-reference/sandbox/reconnect","title":"Reconnect to session sandbox","description":"Reconnect to session sandbox","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/reconnect.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandbox/reconnect","spec":"sandbox.json"},"searchText":"Reconnect to session sandbox Reconnect to session sandbox Agents & Sandboxes Session Sandboxes GET /api/sandbox/reconnect "},{"slug":"api-reference/accounts/id","title":"Get Account ID","description":"Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/id.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/id","spec":"accounts.json"},"searchText":"Get Account ID Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId. Accounts Accounts GET /api/accounts/id "},{"slug":"api-reference/accounts/get","title":"Get Account","description":"Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}","spec":"accounts.json"},"searchText":"Get Account Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses. Accounts Accounts GET /api/accounts/{id} "},{"slug":"api-reference/accounts/create","title":"Create Account","description":"Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts","spec":"accounts.json"},"searchText":"Create Account Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits. Accounts Accounts POST /api/accounts "},{"slug":"api-reference/accounts/update","title":"Update Account","description":"Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/accounts","spec":"accounts.json"},"searchText":"Update Account Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override. Accounts Accounts PATCH /api/accounts "},{"slug":"api-reference/accounts/add-artist","title":"Add Artist to Account","description":"Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/add-artist.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/artists","spec":"accounts.json"},"searchText":"Add Artist to Account Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification. Accounts Accounts POST /api/accounts/artists "},{"slug":"api-reference/subscriptions/sessions-create","title":"Create Subscription Session","description":"Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial.","category":"Accounts","group":"Billing","source":"api-reference/subscriptions/sessions-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/subscriptions/sessions","spec":"accounts.json"},"searchText":"Create Subscription Session Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial. Accounts Billing POST /api/subscriptions/sessions "},{"slug":"api-reference/subscriptions/claim-create","title":"Claim Subscription","description":"Attach a subscription bought through [Create Subscription Session](/api-reference/subscriptions/sessions-create) (anonymous path) to the authenticated account. Needed only when the signed-in email differs from the email typed into Stripe Checkout; when they match, the webhook already linked the subscription and this call is a no-op that returns 200.","category":"Accounts","group":"Billing","source":"api-reference/subscriptions/claim-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/subscriptions/claim","spec":"accounts.json"},"searchText":"Claim Subscription Attach a subscription bought through [Create Subscription Session](/api-reference/subscriptions/sessions-create) (anonymous path) to the authenticated account. Needed only when the signed-in email differs from the email typed into Stripe Checkout; when they match, the webhook already linked the subscription and this call is a no-op that returns 200. Accounts Billing POST /api/subscriptions/claim "},{"slug":"api-reference/accounts/subscription-get","title":"Get Account Subscription","description":"Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/subscription-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/subscription","spec":"accounts.json"},"searchText":"Get Account Subscription Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/subscription "},{"slug":"api-reference/accounts/portal-create","title":"Create Billing Portal Session","description":"Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. The portal opens on the Stripe customer that owns the account's active subscription, so accounts without an active subscription get a 400 even when a tagged customer with a card exists. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with an active subscription.","category":"Accounts","group":"Billing","source":"api-reference/accounts/portal-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/{id}/portal","spec":"accounts.json"},"searchText":"Create Billing Portal Session Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. The portal opens on the Stripe customer that owns the account's active subscription, so accounts without an active subscription get a 400 even when a tagged customer with a card exists. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with an active subscription. Accounts Billing POST /api/accounts/{id}/portal "},{"slug":"api-reference/accounts/payment-method-get","title":"Get Default Payment Method","description":"Retrieve the default payment method on file for an account. An account may be tagged on more than one Stripe customer (for example an organization whose card was saved on one customer and whose invoiced plan lives on another); the card is read from the tagged customer that holds a default payment method. Returns `card: null` when the selected customer has no supported default card, including when no tagged customer exists — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline. Removing the selected card does not remove other saved cards: a later read can select a different remaining card. Auto top-up stays off after successful removal until explicitly re-enabled.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Get Default Payment Method Retrieve the default payment method on file for an account. An account may be tagged on more than one Stripe customer (for example an organization whose card was saved on one customer and whose invoiced plan lives on another); the card is read from the tagged customer that holds a default payment method. Returns `card: null` when the selected customer has no supported default card, including when no tagged customer exists — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline. Removing the selected card does not remove other saved cards: a later read can select a different remaining card. Auto top-up stays off after successful removal until explicitly re-enabled. Accounts Billing GET /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payment-method-create","title":"Save a Payment Method","description":"Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The card is saved on the account's Stripe customer that already holds a default card, or the newest tagged customer; a customer is created (and tagged with the account id) if none exists yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Save a Payment Method Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The card is saved on the account's Stripe customer that already holds a default card, or the newest tagged customer; a customer is created (and tagged with the account id) if none exists yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing POST /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payment-method-delete","title":"Remove the Payment Method","description":"Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Remove the Payment Method Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing DELETE /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payments-get","title":"List Account Payments","description":"List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payments-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/payments","spec":"accounts.json"},"searchText":"List Account Payments List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/payments "},{"slug":"api-reference/accounts/auto-top-up-get","title":"Get Auto Top-up Settings","description":"Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/auto-top-up-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/auto-top-up","spec":"accounts.json"},"searchText":"Get Auto Top-up Settings Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/auto-top-up "},{"slug":"api-reference/accounts/auto-top-up-update","title":"Update Auto Top-up Settings","description":"Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/auto-top-up-update.mdx","body":"","headings":[],"api":{"method":"PUT","path":"/api/accounts/{id}/auto-top-up","spec":"accounts.json"},"searchText":"Update Auto Top-up Settings Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing PUT /api/accounts/{id}/auto-top-up "},{"slug":"api-reference/credits/sessions-create","title":"Create Credits Top-Up Session","description":"Top up credits on the authenticated account.","category":"Accounts","group":"Billing","source":"api-reference/credits/sessions-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/credits/sessions","spec":"accounts.json"},"searchText":"Create Credits Top-Up Session Top up credits on the authenticated account. Accounts Billing POST /api/credits/sessions "},{"slug":"api-reference/accounts/credits-get","title":"Get Account Credits","description":"Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update.","category":"Accounts","group":"Billing","source":"api-reference/accounts/credits-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/credits","spec":"accounts.json"},"searchText":"Get Account Credits Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update. Accounts Billing GET /api/accounts/{id}/credits "},{"slug":"api-reference/accounts/usage-get","title":"Get Account Usage","description":"List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership.","category":"Accounts","group":"Billing","source":"api-reference/accounts/usage-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/usage","spec":"accounts.json"},"searchText":"Get Account Usage List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership. Accounts Billing GET /api/accounts/{id}/usage "},{"slug":"api-reference/pulses/update","title":"Update Pulse","description":"Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint.","category":"Accounts","group":"Pulses","source":"api-reference/pulses/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/pulses","spec":"accounts.json"},"searchText":"Update Pulse Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint. Accounts Pulses PATCH /api/pulses "},{"slug":"api-reference/pulses/list","title":"List Pulses","description":"Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations.","category":"Accounts","group":"Pulses","source":"api-reference/pulses/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/pulses","spec":"accounts.json"},"searchText":"List Pulses Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations. Accounts Pulses GET /api/pulses "},{"slug":"api-reference/organizations/list","title":"Get Organizations","description":"Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations","spec":"accounts.json"},"searchText":"Get Organizations Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to. Accounts Organizations GET /api/organizations "},{"slug":"api-reference/organizations/create","title":"Create Organization","description":"Create a new organization. The creator is automatically added as a member of the organization.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations","spec":"accounts.json"},"searchText":"Create Organization Create a new organization. The creator is automatically added as a member of the organization. Accounts Organizations POST /api/organizations "},{"slug":"api-reference/organizations/add-artist","title":"Add Artist to Organization","description":"Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-artist.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/artists","spec":"accounts.json"},"searchText":"Add Artist to Organization Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records. Accounts Organizations POST /api/organizations/artists "},{"slug":"api-reference/organizations/add-member","title":"Add Member to Organization","description":"Add a member to an organization. This endpoint is idempotent - Adding an existing member returns the existing membership.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-member.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/members","spec":"accounts.json"},"searchText":"Add Member to Organization Add a member to an organization. This endpoint is idempotent - Adding an existing member returns the existing membership. Accounts Organizations POST /api/organizations/members "},{"slug":"api-reference/organizations/remove-member","title":"Remove Member from Organization","description":"Remove a member from an organization. This endpoint is idempotent - Removing an account that is not a member succeeds without error.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/remove-member.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/organizations/members","spec":"accounts.json"},"searchText":"Remove Member from Organization Remove a member from an organization. This endpoint is idempotent - Removing an account that is not a member succeeds without error. Accounts Organizations DELETE /api/organizations/members "},{"slug":"api-reference/organizations/list-domains","title":"List Organization Domains","description":"List the email domains mapped to an organization. Accounts that sign up with an email at a mapped domain automatically join the organization.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/list-domains.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"List Organization Domains List the email domains mapped to an organization. Accounts that sign up with an email at a mapped domain automatically join the organization. Accounts Organizations GET /api/organizations/domains "},{"slug":"api-reference/organizations/add-domain","title":"Add Organization Domain","description":"Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-domain.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"Add Organization Domain Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping. Accounts Organizations POST /api/organizations/domains "},{"slug":"api-reference/organizations/remove-domain","title":"Remove Organization Domain","description":"Remove an email domain mapping from an organization. New signups at this domain will no longer auto-join the organization; existing members are not affected. This endpoint is idempotent.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/remove-domain.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"Remove Organization Domain Remove an email domain mapping from an organization. New signups at this domain will no longer auto-join the organization; existing members are not affected. This endpoint is idempotent. Accounts Organizations DELETE /api/organizations/domains "},{"slug":"api-reference/organizations/professionals","title":"List Professional Roster","description":"List professional roster","category":"Accounts","group":"Organizations","source":"api-reference/organizations/professionals.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations/professionals","spec":"accounts.json"},"searchText":"List Professional Roster List professional roster Accounts Organizations GET /api/organizations/professionals "},{"slug":"api-reference/organizations/professionals-confirm","title":"Confirm Professional Roster Addition","description":"Confirm professional roster addition","category":"Accounts","group":"Organizations","source":"api-reference/organizations/professionals-confirm.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/professionals","spec":"accounts.json"},"searchText":"Confirm Professional Roster Addition Confirm professional roster addition Accounts Organizations POST /api/organizations/professionals "},{"slug":"api-reference/admins/check","title":"Check Admin Status","description":"Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header.","category":"Accounts","group":"Admins","source":"api-reference/admins/check.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins","spec":"accounts.json"},"searchText":"Check Admin Status Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header. Accounts Admins GET /api/admins "},{"slug":"api-reference/admins/sandboxes","title":"List Account Sandboxes (Admin)","description":"Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/sandboxes.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/sandboxes","spec":"accounts.json"},"searchText":"List Account Sandboxes (Admin) Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/sandboxes "},{"slug":"api-reference/admins/sandboxes-orgs","title":"List Org Repo Stats (Admin)","description":"Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/sandboxes-orgs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/sandboxes/orgs","spec":"accounts.json"},"searchText":"List Org Repo Stats (Admin) Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/sandboxes/orgs "},{"slug":"api-reference/admins/emails","title":"List Account Emails (Admin)","description":"Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email).","category":"Accounts","group":"Admins","source":"api-reference/admins/emails.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/emails","spec":"accounts.json"},"searchText":"List Account Emails (Admin) Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email). Accounts Admins GET /api/admins/emails "},{"slug":"api-reference/admins/privy","title":"List Privy Logins (Admin)","description":"Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/privy.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/privy","spec":"accounts.json"},"searchText":"List Privy Logins (Admin) Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/privy "},{"slug":"api-reference/admins/coding-agent-slack-tags","title":"List Coding Agent Slack Tags (Admin)","description":"Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Optional tag filters by the exact, case-sensitive Slack author ID after trimming whitespace. Filtering happens after the existing period collection and before all totals are calculated; omission preserves the unfiltered report, and an unknown ID returns empty tags with zero totals. Empty or whitespace-only tag values return 400 after admin authentication. This is display filtering, not authorization or a reduction in Slack collection work. Collection retains its existing channel access, retention, history/thread pagination and partial-failure limits. No automatic caller, UI, polling, scheduled action or Slack send is added.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-agent-slack-tags.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding/slack","spec":"accounts.json"},"searchText":"List Coding Agent Slack Tags (Admin) Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Optional tag filters by the exact, case-sensitive Slack author ID after trimming whitespace. Filtering happens after the existing period collection and before all totals are calculated; omission preserves the unfiltered report, and an unknown ID returns empty tags with zero totals. Empty or whitespace-only tag values return 400 after admin authentication. This is display filtering, not authorization or a reduction in Slack collection work. Collection retains its existing channel access, retention, history/thread pagination and partial-failure limits. No automatic caller, UI, polling, scheduled action or Slack send is added. Accounts Admins GET /api/admins/coding/slack "},{"slug":"api-reference/admins/coding-agent-slack-authors","title":"List Coding Agent Slack Authors (Admin)","description":"Returns distinct authors of collected Coding Agent mentions for an admin author selector. Requires the authenticated account to be a Recoup admin, using exactly one of x-api-key or Authorization Bearer. No query parameters are defined. Each authorized request runs the existing all-period Slack collector once, then deduplicates by Slack author ID, retains the first collected profile and sorts by display name using localeCompare; identical names do not merge different IDs. The result is authors in that collected data, not a complete all-time Slack directory. Existing channel access, retention, paginated history, first-page thread replies and partial-failure limits remain; partial collection can still produce an incomplete successful result. Thrown collection failures return 500. This call is not free cached metadata: a future caller must account for scan latency and quotas. The release adds no automatic caller, UI, polling, scheduled action, new Slack scope or Slack send. Production admin access, history coverage, latency and quotas were not verified by the source contract tests.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-agent-slack-authors.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding-agent/slack-tags","spec":"accounts.json"},"searchText":"List Coding Agent Slack Authors (Admin) Returns distinct authors of collected Coding Agent mentions for an admin author selector. Requires the authenticated account to be a Recoup admin, using exactly one of x-api-key or Authorization Bearer. No query parameters are defined. Each authorized request runs the existing all-period Slack collector once, then deduplicates by Slack author ID, retains the first collected profile and sorts by display name using localeCompare; identical names do not merge different IDs. The result is authors in that collected data, not a complete all-time Slack directory. Existing channel access, retention, paginated history, first-page thread replies and partial-failure limits remain; partial collection can still produce an incomplete successful result. Thrown collection failures return 500. This call is not free cached metadata: a future caller must account for scan latency and quotas. The release adds no automatic caller, UI, polling, scheduled action, new Slack scope or Slack send. Production admin access, history coverage, latency and quotas were not verified by the source contract tests. Accounts Admins GET /api/admins/coding-agent/slack-tags "},{"slug":"api-reference/admins/coding-pr","title":"Get Coding Agent PR Merged Status (Admin)","description":"Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-pr.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding/pr","spec":"accounts.json"},"searchText":"Get Coding Agent PR Merged Status (Admin) Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/coding/pr "},{"slug":"api-reference/admins/content-slack-tags","title":"List Content Agent Slack Tags (Admin)","description":"Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/content-slack-tags.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/content/slack","spec":"accounts.json"},"searchText":"List Content Agent Slack Tags (Admin) Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/content/slack "},{"slug":"api-reference/admins/agent-signups","title":"Admin signup report availability","description":"An admin key-metadata report is available; the former signup-report URL and broader reporting outcome remain separate.","category":"Accounts","group":"Admins","source":"api-reference/admins/agent-signups.mdx","body":"`GET /api/admins/agent/signups` is not available. The new\n[admin key-metadata report](/api-reference/admins/agent-key-metadata) uses\n`GET /api/admins/agent-signups` (a different URL).\n\nA Recoup admin can use the new report to inspect key-record IDs, names, creation\ntimes and matching current `agent+…` email addresses. It never returns API-key\ncredentials or hashes. Its `total` counts the returned key records; several keys\ncan belong to one account. It does not establish where an account signed up,\nhow many unique agents signed up, which keys are active, or whether people use\nthe product. Current email associations, database visibility and server row limits\nalso prevent a guarantee of complete historical reporting.\n\n## Unfinished reporting outcome\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the\nbroader reporting decision. The bounded metadata route from\n[API #1095](https://github.com/recoupable/api/pull/1095) does not complete the original\n[API #428](https://github.com/recoupable/api/issues/428) customer outcome or restore\nthe former URL. Follow the new route's period, admin-access and collection-limit\nnotes when using it; do not treat key-record counts as signup-origin or adoption\nmeasurements.\n","headings":[{"title":"Unfinished reporting outcome","id":"unfinished-reporting-outcome"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/admins/agent/signups\"\n }), \" is not available. The new\\n\", _jsx(_components.a, {\n href: \"/api-reference/admins/agent-key-metadata\",\n children: \"admin key-metadata report\"\n }), \" uses\\n\", _jsx(_components.code, {\n children: \"GET /api/admins/agent-signups\"\n }), \" (a different URL).\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A Recoup admin can use the new report to inspect key-record IDs, names, creation\\ntimes and matching current \", _jsx(_components.code, {\n children: \"agent+…\"\n }), \" email addresses. It never returns API-key\\ncredentials or hashes. Its \", _jsx(_components.code, {\n children: \"total\"\n }), \" counts the returned key records; several keys\\ncan belong to one account. It does not establish where an account signed up,\\nhow many unique agents signed up, which keys are active, or whether people use\\nthe product. Current email associations, database visibility and server row limits\\nalso prevent a guarantee of complete historical reporting.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"unfinished-reporting-outcome\",\n children: \"Unfinished reporting outcome\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" retains the\\nbroader reporting decision. The bounded metadata route from\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/1095\",\n children: \"API #1095\"\n }), \" does not complete the original\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/issues/428\",\n children: \"API #428\"\n }), \" customer outcome or restore\\nthe former URL. Follow the new route's period, admin-access and collection-limit\\nnotes when using it; do not treat key-record counts as signup-origin or adoption\\nmeasurements.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Admin signup report availability An admin key-metadata report is available; the former signup-report URL and broader reporting outcome remain separate. Accounts Admins `GET /api/admins/agent/signups` is not available. The new [admin key-metadata report](/api-reference/admins/agent-key-metadata) uses `GET /api/admins/agent-signups` (a different URL). A Recoup admin can use the new report to inspect key-record IDs, names, creation times and matching current `agent+…` email addresses. It never returns API-key credentials or hashes. Its `total` counts the returned key records; several keys can belong to one account. It does not establish where an account signed up, how many unique agents signed up, which keys are active, or whether people use the product. Current email associations, database visibility and server row limits also prevent a guarantee of complete historical reporting. ## Unfinished reporting outcome [Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the broader reporting decision. The bounded metadata route from [API #1095](https://github.com/recoupable/api/pull/1095) does not complete the original [API #428](https://github.com/recoupable/api/issues/428) customer outcome or restore the former URL. Follow the new route's period, admin-access and collection-limit notes when using it; do not treat key-record counts as signup-origin or adoption measurements. "},{"slug":"api-reference/admins/agent-key-metadata","title":"List Agent Key Metadata (Admin)","description":"List agent-prefixed API-key metadata (Admin)","category":"Accounts","group":"Admins","source":"api-reference/admins/agent-key-metadata.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/agent-signups","spec":"accounts.json"},"searchText":"List Agent Key Metadata (Admin) List agent-prefixed API-key metadata (Admin) Accounts Admins GET /api/admins/agent-signups "},{"slug":"api-reference/admins/artists-pro","title":"List Pro Artists (Admin)","description":"Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is \"pro\" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts.","category":"Accounts","group":"Admins","source":"api-reference/admins/artists-pro.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/artists/pro","spec":"accounts.json"},"searchText":"List Pro Artists (Admin) Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is \"pro\" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts. Accounts Admins GET /api/admins/artists/pro "},{"slug":"api-reference/admins/credits-rollup","title":"Credit Usage Rollup (Admin)","description":"Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-rollup.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/credits/rollup","spec":"accounts.json"},"searchText":"Credit Usage Rollup (Admin) Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin. Accounts Admins GET /api/admins/credits/rollup "},{"slug":"api-reference/admins/credits-events","title":"Credit Usage Events (Admin)","description":"Returns the raw `usage_events` rows for a single account over the selected period, sorted by `created_at` descending. Powers the drilldown view that expands when a row in the [`/api/admins/credits/rollup`](/api-reference/admins/credits-rollup) table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and `credits_deducted` matching the wallet drop on `credits_usage` for that account.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-events.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/credits/events","spec":"accounts.json"},"searchText":"Credit Usage Events (Admin) Returns the raw `usage_events` rows for a single account over the selected period, sorted by `created_at` descending. Powers the drilldown view that expands when a row in the [`/api/admins/credits/rollup`](/api-reference/admins/credits-rollup) table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and `credits_deducted` matching the wallet drop on `credits_usage` for that account. Accounts Admins GET /api/admins/credits/events "},{"slug":"api-reference/admins/credits-grant","title":"Grant Credits (Admin)","description":"Sets an account's credit balance, and records who set it and why. Requires the authenticated account to be a Recoup admin.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-grant.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/admins/credits","spec":"accounts.json"},"searchText":"Grant Credits (Admin) Sets an account's credit balance, and records who set it and why. Requires the authenticated account to be a Recoup admin. Accounts Admins POST /api/admins/credits "},{"slug":"api-reference/emails/create","title":"Send Email","description":"Send an email to one or more recipients. Emails are sent from `Agent by Recoup `.","category":"Accounts","group":"Emails","source":"api-reference/emails/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/emails","spec":"accounts.json"},"searchText":"Send Email Send an email to one or more recipients. Emails are sent from `Agent by Recoup `. Accounts Emails POST /api/emails "},{"slug":"api-reference/projects/get","title":"Get Project","description":"Get project","category":"Accounts","group":"Projects","source":"api-reference/projects/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}","spec":"projects.json"},"searchText":"Get Project Get project Accounts Projects GET /api/projects/{projectId} "},{"slug":"api-reference/projects/task-get","title":"Get Project Task","description":"Get project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Get Project Task Get project task Accounts Projects GET /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/task-create","title":"Create Project Task","description":"Create project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/projects/{projectId}/tasks","spec":"projects.json"},"searchText":"Create Project Task Create project task Accounts Projects POST /api/projects/{projectId}/tasks "},{"slug":"api-reference/projects/task-update","title":"Update Project Task","description":"Update project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Update Project Task Update project task Accounts Projects PATCH /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/task-delete","title":"Delete Project Task","description":"Delete project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Delete Project Task Delete project task Accounts Projects DELETE /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/comments-get","title":"List Task Comments","description":"List task comments","category":"Accounts","group":"Projects","source":"api-reference/projects/comments-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}/tasks/{taskId}/comments","spec":"projects.json"},"searchText":"List Task Comments List task comments Accounts Projects GET /api/projects/{projectId}/tasks/{taskId}/comments "},{"slug":"api-reference/projects/comments-create","title":"Add Task Comment","description":"Add task comment","category":"Accounts","group":"Projects","source":"api-reference/projects/comments-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/projects/{projectId}/tasks/{taskId}/comments","spec":"projects.json"},"searchText":"Add Task Comment Add task comment Accounts Projects POST /api/projects/{projectId}/tasks/{taskId}/comments "},{"slug":"connectors/ownership","title":"Connection Ownership","description":"The connector connection-ownership and authority contract: who owns a connection, who can act through it, and why roster membership never grants execute rights.","category":"Connectors","group":"Concepts","source":"connectors/ownership.mdx","body":"## Overview\n\nConnectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the **ownership and authority contract** for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it.\n\nThis contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the [Connectors API reference](/api-reference/connectors/list).\n\n---\n\n## Association ≠ Authority\n\nArtists in Recoup are **canonical and shared**. The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections:\n\n- An artist appearing in an account's roster (`account_artist_ids`) grants **read and analytics access only**.\n- An artist appearing in an organization's roster likewise grants **read and analytics access only** to org members.\n- Neither form of association ever grants the right to authorize, execute, or disconnect a connection.\n\n\nRoster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does **not** let Account B post through that connection.\n\n\n---\n\n## Connection Scope\n\nConnections are scoped to the **relationship between an owner and an artist**, not to the bare canonical artist:\n\n| Connection type | Scoped to |\n|-----------------|-----------|\n| Personal | The `(account, artist)` pair |\n| Org-shared | The `(organization, artist)` pair |\n\nThe connection is keyed on the **join row** (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist.\n\n**Whoever establishes a connection owns it.** Ownership is set at authorization time and does not transfer through roster changes.\n\nBecause artists stay canonical and shared, **isolation lives on the connection**: sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it.\n\n---\n\n## Authority Matrix\n\n| Capability | Who has it |\n|------------|-----------|\n| Read / analytics on an artist | Any account or org member with the artist in their roster |\n| Authorize a new connection | The account (or org member, for org-shared) establishing the connection, who then owns it |\n| Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org |\n| Disconnect a connection | The owning account only; for org-shared connections, members of the owning org |\n| Admin override | Recoup staff only (admins of the Recoup internal organization) |\n\n\nThe admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection.\n\n\n---\n\n## Relationship to the Current API Reference\n\nThe [Connectors endpoint reference](/api-reference/connectors/list) currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-`(account, artist)` / per-`(organization, artist)` model defined here. Where the two disagree, **this page is the authority contract**. Endpoint docs will be updated as the re-keyed API ships.\n\nEndpoint request and response shapes for the re-keyed model are deliberately not documented here yet.\n","headings":[{"title":"Overview","id":"overview"},{"title":"Association ≠ Authority","id":"association-authority"},{"title":"Connection Scope","id":"connection-scope"},{"title":"Authority Matrix","id":"authority-matrix"},{"title":"Relationship to the Current API Reference","id":"relationship-to-the-current-api-reference"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n hr: \"hr\",\n li: \"li\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n }, {Note, Warning} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"overview\",\n children: \"Overview\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the \", _jsx(_components.strong, {\n children: \"ownership and authority contract\"\n }), \" for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors API reference\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"association-authority\",\n children: \"Association ≠ Authority\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Artists in Recoup are \", _jsx(_components.strong, {\n children: \"canonical and shared\"\n }), \". The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"An artist appearing in an account's roster (\", _jsx(_components.code, {\n children: \"account_artist_ids\"\n }), \") grants \", _jsx(_components.strong, {\n children: \"read and analytics access only\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"An artist appearing in an organization's roster likewise grants \", _jsx(_components.strong, {\n children: \"read and analytics access only\"\n }), \" to org members.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Neither form of association ever grants the right to authorize, execute, or disconnect a connection.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsxs(_components.p, {\n children: [\"Roster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does \", _jsx(_components.strong, {\n children: \"not\"\n }), \" let Account B post through that connection.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"connection-scope\",\n children: \"Connection Scope\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connections are scoped to the \", _jsx(_components.strong, {\n children: \"relationship between an owner and an artist\"\n }), \", not to the bare canonical artist:\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Connection type\"\n }), _jsx(_components.th, {\n children: \"Scoped to\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Personal\"\n }), _jsxs(_components.td, {\n children: [\"The \", _jsx(_components.code, {\n children: \"(account, artist)\"\n }), \" pair\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Org-shared\"\n }), _jsxs(_components.td, {\n children: [\"The \", _jsx(_components.code, {\n children: \"(organization, artist)\"\n }), \" pair\"]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The connection is keyed on the \", _jsx(_components.strong, {\n children: \"join row\"\n }), \" (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Whoever establishes a connection owns it.\"\n }), \" Ownership is set at authorization time and does not transfer through roster changes.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Because artists stay canonical and shared, \", _jsx(_components.strong, {\n children: \"isolation lives on the connection\"\n }), \": sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"authority-matrix\",\n children: \"Authority Matrix\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Capability\"\n }), _jsx(_components.th, {\n children: \"Who has it\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Read / analytics on an artist\"\n }), _jsx(_components.td, {\n children: \"Any account or org member with the artist in their roster\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Authorize a new connection\"\n }), _jsx(_components.td, {\n children: \"The account (or org member, for org-shared) establishing the connection, who then owns it\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Execute actions through a connection\"\n }), _jsx(_components.td, {\n children: \"The owning account only; for org-shared connections, members of the owning org\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Disconnect a connection\"\n }), _jsx(_components.td, {\n children: \"The owning account only; for org-shared connections, members of the owning org\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Admin override\"\n }), _jsx(_components.td, {\n children: \"Recoup staff only (admins of the Recoup internal organization)\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"The admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection.\"\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"relationship-to-the-current-api-reference\",\n children: \"Relationship to the Current API Reference\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors endpoint reference\"\n }), \" currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-\", _jsx(_components.code, {\n children: \"(account, artist)\"\n }), \" / per-\", _jsx(_components.code, {\n children: \"(organization, artist)\"\n }), \" model defined here. Where the two disagree, \", _jsx(_components.strong, {\n children: \"this page is the authority contract\"\n }), \". Endpoint docs will be updated as the re-keyed API ships.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Endpoint request and response shapes for the re-keyed model are deliberately not documented here yet.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Connection Ownership The connector connection-ownership and authority contract: who owns a connection, who can act through it, and why roster membership never grants execute rights. Connectors Concepts ## Overview Connectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the **ownership and authority contract** for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it. This contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the [Connectors API reference](/api-reference/connectors/list). --- ## Association ≠ Authority Artists in Recoup are **canonical and shared**. The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections: - An artist appearing in an account's roster (`account_artist_ids`) grants **read and analytics access only**. - An artist appearing in an organization's roster likewise grants **read and analytics access only** to org members. - Neither form of association ever grants the right to authorize, execute, or disconnect a connection. Roster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does **not** let Account B post through that connection. --- ## Connection Scope Connections are scoped to the **relationship between an owner and an artist**, not to the bare canonical artist: | Connection type | Scoped to | |-----------------|-----------| | Personal | The `(account, artist)` pair | | Org-shared | The `(organization, artist)` pair | The connection is keyed on the **join row** (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist. **Whoever establishes a connection owns it.** Ownership is set at authorization time and does not transfer through roster changes. Because artists stay canonical and shared, **isolation lives on the connection**: sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it. --- ## Authority Matrix | Capability | Who has it | |------------|-----------| | Read / analytics on an artist | Any account or org member with the artist in their roster | | Authorize a new connection | The account (or org member, for org-shared) establishing the connection, who then owns it | | Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org | | Disconnect a connection | The owning account only; for org-shared connections, members of the owning org | | Admin override | Recoup staff only (admins of the Recoup internal organization) | The admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection. --- ## Relationship to the Current API Reference The [Connectors endpoint reference](/api-reference/connectors/list) currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-`(account, artist)` / per-`(organization, artist)` model defined here. Where the two disagree, **this page is the authority contract**. Endpoint docs will be updated as the re-keyed API ships. Endpoint request and response shapes for the re-keyed model are deliberately not documented here yet. "},{"slug":"api-reference/connectors/list","title":"List Connectors","description":"List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok, YouTube, X (Twitter), LinkedIn) along with whether they are currently connected.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/connectors","spec":"social.json"},"searchText":"List Connectors List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok, YouTube, X (Twitter), LinkedIn) along with whether they are currently connected. Connectors Connectors GET /api/connectors "},{"slug":"api-reference/connectors/authorize","title":"Authorize Connector","description":"Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/authorize.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors","spec":"social.json"},"searchText":"Authorize Connector Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow. Connectors Connectors POST /api/connectors "},{"slug":"api-reference/connectors/disconnect","title":"Disconnect Connector","description":"Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/disconnect.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/connectors","spec":"social.json"},"searchText":"Disconnect Connector Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials. Connectors Connectors DELETE /api/connectors "},{"slug":"api-reference/connectors/list-actions","title":"List Connector Actions","description":"List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/list-actions.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/connectors/actions","spec":"social.json"},"searchText":"List Connector Actions List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors. Connectors Connectors GET /api/connectors/actions "},{"slug":"api-reference/connectors/upload-file","title":"Upload Connector File","description":"Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action).","category":"Connectors","group":"Connectors","source":"api-reference/connectors/upload-file.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors/files","spec":"social.json"},"searchText":"Upload Connector File Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action). Connectors Connectors POST /api/connectors/files "},{"slug":"api-reference/connectors/execute-action","title":"Execute Connector Action","description":"Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/execute-action.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors/actions","spec":"social.json"},"searchText":"Execute Connector Action Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor. Connectors Connectors POST /api/connectors/actions "},{"slug":"api-reference/publishing/create","title":"Create Post","description":"Create post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/posts","spec":"social.json"},"searchText":"Create Post Create post Connectors Publishing POST /api/posts "},{"slug":"api-reference/publishing/list","title":"List Posts","description":"List posts","category":"Connectors","group":"Publishing","source":"api-reference/publishing/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/posts","spec":"social.json"},"searchText":"List Posts List posts Connectors Publishing GET /api/posts "},{"slug":"api-reference/publishing/get","title":"Get Post","description":"Get post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/posts/{id}","spec":"social.json"},"searchText":"Get Post Get post Connectors Publishing GET /api/posts/{id} "},{"slug":"api-reference/publishing/stats","title":"Get Post Stats","description":"Get post stats","category":"Connectors","group":"Publishing","source":"api-reference/publishing/stats.mdx","body":"## Data coverage\n\nLinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds.\n","headings":[{"title":"Data coverage","id":"data-coverage"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"data-coverage\",\n children: \"Data coverage\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"LinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","api":{"method":"GET","path":"/api/posts/{id}/stats","spec":"social.json"},"searchText":"Get Post Stats Get post stats Connectors Publishing GET /api/posts/{id}/stats ## Data coverage LinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds. "},{"slug":"api-reference/publishing/cancel","title":"Cancel Post","description":"Cancel post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/cancel.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/posts/{id}","spec":"social.json"},"searchText":"Cancel Post Cancel post Connectors Publishing DELETE /api/posts/{id} "},{"slug":"api-reference/applications/validate-registration","title":"Check an application proposal","description":"Validate proposed app addresses in your workspace without registering or activating an application.","category":"Sites","group":"Application proposals","source":"api-reference/applications/validate-registration.mdx","body":"\n Pending coordinated release. This checks a proposal; it does not register an\n app or make its origins trusted. Discover tool availability in your connected\n host before use.\n\n\nBefore connecting an external app, check its proposed name, environment, origins\nand return URLs. A successful result means those values passed validation for\nthe selected workspace. It does not prove domain ownership.\n\n## What happens\n\nThe preflight runs after normal Recoup authentication. First-time sign-in can\nperform normal account provisioning and send its welcome email. After that,\nthis validator does not persist an application or issue application credentials.\nIt does not edit provider callbacks, create fan identities or sessions, allocate\ncapacity, or authorize purchases and spending.\n\n`workspace_id` and `billing_owner_id` come from the authenticated account or an\norganization it can access. They describe the proposed owner only. Supplying\n`organization_id` does not grant workspace access. Do not submit account or\nbilling ownership overrides, secrets or tokens in the proposal.\n\nThe result is flat and includes `status: \"validated\"`, `persisted: false` and\n`origins_verified: false`. It contains no application ID or token to install.\n\n## Addresses and environments\n\n- Choose `development` or `production` explicitly for each proposal.\n- Use exact canonical origins such as `https://music.example`, without a trailing\n slash, wildcard, path, credentials, query or fragment. Different hosts and\n ports are different origins.\n- HTTPS is required. Development also accepts HTTP on `localhost`, `127.0.0.1`\n and `[::1]`; these loopback hosts are rejected in production.\n- A return URL must be an exact canonical URL on one of the proposed origins,\n without credentials or fragments. For a bare host use its canonical trailing\n slash, such as `https://music.example/`. Query strings are retained literally.\n- Each list takes 1–32 distinct addresses, each at most 2048 characters. The name\n is trimmed and must then contain 1–120 characters. These are input limits,\n not subscription or usage allowances.\n\nMatching a return URL to a caller-proposed origin does not establish that the\ncaller owns either address. No DNS check, URL fetch or domain proof is performed.\n\n## Standard MCP\n\nOn a standard API-key MCP connection that exposes `validate_application_registration`,\nuse the same proposal fields as HTTP. Account identity comes from the connection;\ndo not add `account_id` or extract a host-managed OAuth token.\n\n```json\n{\n \"name\": \"Release companion\",\n \"environment\": \"production\",\n \"allowed_origins\": [\"https://music.example\"],\n \"return_urls\": [\"https://music.example/listen?connected=spotify\"]\n}\n```\n\nDelegated OAuth excludes this tool, including connections with `mcp:tools`.\nHTTP and standard MCP share proposal validation; their transport-specific error\nenvelopes differ. HTTP authentication errors can use `error` or `message`, while\nhandled preflight errors use `status: \"error\"` and `error`. MCP failures are tool\nerrors or SDK input-validation errors. None confirms registration or activation.\n\nSee [authentication](/authentication) and [MCP connection guidance](/mcp).\nApplication persistence, origin proof/reverification, provider configuration,\nfan bootstrap, suspension and quota policy require their own completed contracts.\n","headings":[{"title":"What happens","id":"what-happens"},{"title":"Addresses and environments","id":"addresses-and-environments"},{"title":"Standard MCP","id":"standard-mcp"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n ul: \"ul\",\n ...props.components\n }, {Warning} = _components;\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Pending coordinated release. This checks a proposal; it does not register an\\napp or make its origins trusted. Discover tool availability in your connected\\nhost before use.\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before connecting an external app, check its proposed name, environment, origins\\nand return URLs. A successful result means those values passed validation for\\nthe selected workspace. It does not prove domain ownership.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-happens\",\n children: \"What happens\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The preflight runs after normal Recoup authentication. First-time sign-in can\\nperform normal account provisioning and send its welcome email. After that,\\nthis validator does not persist an application or issue application credentials.\\nIt does not edit provider callbacks, create fan identities or sessions, allocate\\ncapacity, or authorize purchases and spending.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"workspace_id\"\n }), \" and \", _jsx(_components.code, {\n children: \"billing_owner_id\"\n }), \" come from the authenticated account or an\\norganization it can access. They describe the proposed owner only. Supplying\\n\", _jsx(_components.code, {\n children: \"organization_id\"\n }), \" does not grant workspace access. Do not submit account or\\nbilling ownership overrides, secrets or tokens in the proposal.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The result is flat and includes \", _jsx(_components.code, {\n children: \"status: \\\"validated\\\"\"\n }), \", \", _jsx(_components.code, {\n children: \"persisted: false\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"origins_verified: false\"\n }), \". It contains no application ID or token to install.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"addresses-and-environments\",\n children: \"Addresses and environments\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Choose \", _jsx(_components.code, {\n children: \"development\"\n }), \" or \", _jsx(_components.code, {\n children: \"production\"\n }), \" explicitly for each proposal.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use exact canonical origins such as \", _jsx(_components.code, {\n children: \"https://music.example\"\n }), \", without a trailing\\nslash, wildcard, path, credentials, query or fragment. Different hosts and\\nports are different origins.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"HTTPS is required. Development also accepts HTTP on \", _jsx(_components.code, {\n children: \"localhost\"\n }), \", \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \"\\nand \", _jsx(_components.code, {\n children: \"[::1]\"\n }), \"; these loopback hosts are rejected in production.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"A return URL must be an exact canonical URL on one of the proposed origins,\\nwithout credentials or fragments. For a bare host use its canonical trailing\\nslash, such as \", _jsx(_components.code, {\n children: \"https://music.example/\"\n }), \". Query strings are retained literally.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Each list takes 1–32 distinct addresses, each at most 2048 characters. The name\\nis trimmed and must then contain 1–120 characters. These are input limits,\\nnot subscription or usage allowances.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Matching a return URL to a caller-proposed origin does not establish that the\\ncaller owns either address. No DNS check, URL fetch or domain proof is performed.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"standard-mcp\",\n children: \"Standard MCP\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"On a standard API-key MCP connection that exposes \", _jsx(_components.code, {\n children: \"validate_application_registration\"\n }), \",\\nuse the same proposal fields as HTTP. Account identity comes from the connection;\\ndo not add \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" or extract a host-managed OAuth token.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"name\\\": \\\"Release companion\\\",\\n \\\"environment\\\": \\\"production\\\",\\n \\\"allowed_origins\\\": [\\\"https://music.example\\\"],\\n \\\"return_urls\\\": [\\\"https://music.example/listen?connected=spotify\\\"]\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Delegated OAuth excludes this tool, including connections with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \".\\nHTTP and standard MCP share proposal validation; their transport-specific error\\nenvelopes differ. HTTP authentication errors can use \", _jsx(_components.code, {\n children: \"error\"\n }), \" or \", _jsx(_components.code, {\n children: \"message\"\n }), \", while\\nhandled preflight errors use \", _jsx(_components.code, {\n children: \"status: \\\"error\\\"\"\n }), \" and \", _jsx(_components.code, {\n children: \"error\"\n }), \". MCP failures are tool\\nerrors or SDK input-validation errors. None confirms registration or activation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"authentication\"\n }), \" and \", _jsx(_components.a, {\n href: \"/mcp\",\n children: \"MCP connection guidance\"\n }), \".\\nApplication persistence, origin proof/reverification, provider configuration,\\nfan bootstrap, suspension and quota policy require their own completed contracts.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"POST","path":"/api/applications/registration/validate","spec":"applications.json"},"searchText":"Check an application proposal Validate proposed app addresses in your workspace without registering or activating an application. Sites Application proposals POST /api/applications/registration/validate Pending coordinated release. This checks a proposal; it does not register an app or make its origins trusted. Discover tool availability in your connected host before use. Before connecting an external app, check its proposed name, environment, origins and return URLs. A successful result means those values passed validation for the selected workspace. It does not prove domain ownership. ## What happens The preflight runs after normal Recoup authentication. First-time sign-in can perform normal account provisioning and send its welcome email. After that, this validator does not persist an application or issue application credentials. It does not edit provider callbacks, create fan identities or sessions, allocate capacity, or authorize purchases and spending. `workspace_id` and `billing_owner_id` come from the authenticated account or an organization it can access. They describe the proposed owner only. Supplying `organization_id` does not grant workspace access. Do not submit account or billing ownership overrides, secrets or tokens in the proposal. The result is flat and includes `status: \"validated\"`, `persisted: false` and `origins_verified: false`. It contains no application ID or token to install. ## Addresses and environments - Choose `development` or `production` explicitly for each proposal. - Use exact canonical origins such as `https://music.example`, without a trailing slash, wildcard, path, credentials, query or fragment. Different hosts and ports are different origins. - HTTPS is required. Development also accepts HTTP on `localhost`, `127.0.0.1` and `[::1]`; these loopback hosts are rejected in production. - A return URL must be an exact canonical URL on one of the proposed origins, without credentials or fragments. For a bare host use its canonical trailing slash, such as `https://music.example/`. Query strings are retained literally. - Each list takes 1–32 distinct addresses, each at most 2048 characters. The name is trimmed and must then contain 1–120 characters. These are input limits, not subscription or usage allowances. Matching a return URL to a caller-proposed origin does not establish that the caller owns either address. No DNS check, URL fetch or domain proof is performed. ## Standard MCP On a standard API-key MCP connection that exposes `validate_application_registration`, use the same proposal fields as HTTP. Account identity comes from the connection; do not add `account_id` or extract a host-managed OAuth token. Delegated OAuth excludes this tool, including connections with `mcp:tools`. HTTP and standard MCP share proposal validation; their transport-specific error envelopes differ. HTTP authentication errors can use `error` or `message`, while handled preflight errors use `status: \"error\"` and `error`. MCP failures are tool errors or SDK input-validation errors. None confirms registration or activation. See [authentication](/authentication) and [MCP connection guidance](/mcp). Application persistence, origin proof/reverification, provider configuration, fan bootstrap, suspension and quota policy require their own completed contracts. "},{"slug":"api-reference/sites/overview","title":"Sites","description":"Create, generate, and publish fan experiences through the API or MCP.","category":"Sites","group":"Sites","source":"api-reference/sites/overview.mdx","body":"Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a **private draft**. Generation never publishes it automatically.\n\n## Authentication\n\nPrivate HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`.\nMCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection.\n\nThe caller is derived from authentication. Do not send an `account_id`. An optional `organizationId` selects a workspace the caller can access. Omit it for the authenticated account's workspace.\n\n## Endpoints and tools\n\n| HTTP | MCP tool | Result |\n| --- | --- | --- |\n| `GET /api/sites` | `list_sites` | `{ sites: [...] }` |\n| `POST /api/sites` | `create_site` | `{ site: ... }`, HTTP 201 |\n| `GET /api/sites/{id}` | `get_site` | `{ site: ... }` |\n| `PATCH /api/sites/{id}` action `concepts` | `propose_site_concepts` | Short pitches or missing context |\n| `PATCH /api/sites/{id}` action `generate` | `generate_site` | Generate from an optional customer-selected pitch; otherwise select a concept |\n| `PATCH /api/sites/{id}` action `generation` | `get_site_generation` | Status for the specified generation token |\n| `PATCH /api/sites/{id}` action `publish` | `publish_site` | Publish the saved draft or the playable build selected by `generationToken` |\n| `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained |\n| `PATCH /api/sites/{id}` action `delete` | `delete_site` | `{ \"deleted\": true, \"id\": \"...\" }` |\n| `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 |\n| `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` |\n\nListing accepts optional `organizationId` and `artistId` query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response.\n\n## Create and generate\n\nCreate a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL.\n\n```bash\ncurl https://api.recoupable.dev/api/sites \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"releaseUrl\":\"https://open.spotify.com/track/TRACK_ID\",\"brief\":\"Build a maze game\"}'\n```\n\nOptional creation fields: `name` (120 characters), `brief` (6,000), `organizationId`, `artistId`, and `assets` (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used.\n\nRead `site.id` and `site.revision`, then start automatic generation:\n\n```json\n{\"action\":\"generate\",\"revision\":0}\n```\n\nFor Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused.\n\nTo choose a concept yourself before generation, optionally request pitches:\n\n```json\n{\"action\":\"concepts\",\"revision\":0}\n```\n\nSend this to `PATCH /api/sites/{id}`, or call MCP `propose_site_concepts` with `id` and `revision`. Optional `instruction` and `contextBriefId` apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft.\n\nThe response is `{ concepts: { status, candidates, reason }, revision }`. Status is `ready`, `needs-context`, or `no-good-concept`. Metadata and cover details alone return `needs-context`; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork.\n\nIn the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains `name`, `activity`, `fanMotivation`, `songOrArtistConnection`, and `friendHook`. Pass the selected object unchanged as `approvedConcept`:\n\n```json\n{\n \"action\": \"generate\",\n \"revision\": 0,\n \"approvedConcept\": {\n \"name\": \"CUSTOMER_SELECTED_NAME\",\n \"activity\": \"SELECTED_ACTIVITY\",\n \"fanMotivation\": \"SELECTED_MOTIVATION\",\n \"songOrArtistConnection\": \"SELECTED_CONNECTION\",\n \"friendHook\": \"SELECTED_HOOK\"\n }\n}\n```\n\nMCP `generate_site` accepts the same fields plus `id`, without `action`. A customer-authored concept is also accepted. The optional `approvedConcept` preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context.\n\nGeneration defaults to background execution and returns a generation token; poll `get_site_generation` (HTTP action `generation`) for the result. Set `background: false` only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked `needs-review`; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass.\n\nGeneration failures identify the stopped stage and leave the saved draft unchanged. A `409` means another edit changed the revision; read the site again before retrying.\n\n### Poll background generation\n\nSend this JSON body to `PATCH /api/sites/{id}` using the token returned by the\ngeneration request. MCP `get_site_generation` takes `id` and `token`, without `action`.\nPolling uses `token`; publishing and cancellation use `generationToken`.\n\n```json\n{\"action\":\"generation\",\"token\":\"TOKEN_FROM_GENERATION\"}\n```\n\nThe token is bound to its site and caller and expires. Invalid, expired or\nmismatched tokens return 404 during token verification; a missing or empty token\nis invalid input (400). A running job is not proof that a\nplayable build or a published page exists; read the returned status and progress.\n\n## Generate from saved Context Engine evidence\n\nSave a single-song `creative_direction` brief using the Context Engine `save_brief` action, then pass its snapshot ID when requesting pitches:\n\n```json\n{\n \"action\": \"concepts\",\n \"revision\": 0,\n \"contextBriefId\": \"SAVED_BRIEF_UUID\"\n}\n```\n\nPass the same `contextBriefId` with the selected `approvedConcept` to generation. It is available on both MCP `propose_site_concepts` and `generate_site`. Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied.\n\nThis path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial.\n\nGeneration still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response.\n\n## Publish\n\nAfter reviewing the intended draft or preview, publish through the same PATCH\nendpoint or MCP `publish_site`, using the site's current saved revision.\n\nPublishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports `fanConnection: \"enabled\"`.\n\nFor a custom hosted destination, HTTP callers may include `returnUrl` (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations.\n\nThe public page is `https://chat.recoupable.dev/s/{id}`.\n\n### Publish the saved draft\n\nUse the current revision from the saved site (3 in this example):\n\n```json\n{\"action\":\"publish\",\"revision\":3}\n```\n\nOmitting `generationToken` selects the saved draft, even when a background job has\na newer preview. MCP `publish_site` takes `id` and `revision`, without `action`.\n\n### Publish a working preview\n\nTo publish a specific working preview from a background generation, pass its\ntoken as `generationToken` and the site's current saved revision:\n\n```json\n{\"action\":\"publish\",\"revision\":3,\"generationToken\":\"TOKEN_FROM_GENERATION\"}\n```\n\nMCP `publish_site` uses the same fields plus `id`, without `action`. The token must\nmatch the site and caller. The selected build must contain a completed playable\nbuild step for the current site/workspace/revision; the whole generation job need\nnot already be completed. A preview that is not ready returns 400, a stale build\nreturns 409, and invalid or expired token access returns 404. A temporary saved-build\nfailure may return 503. Without `generationToken`, publication uses the saved draft;\nit does not automatically select the newest background preview.\n\n### Upgrade required\n\nAn ineligible workspace receives HTTP 402 with an error body, for example:\n\n```json\n{\"error\":\"An active paid Recoup subscription is required to publish a site. Subscribe in this site’s workspace, then publish again.\"}\n```\n\nSubscribe in the site's owning workspace before retrying the intended publish.\nThis response does not publish the site or create a checkout session.\n\n### Unpublish\n\nSend `PATCH /api/sites/{id}` with the current revision to remove the public\nsnapshot while retaining the draft. MCP `unpublish_site` takes `id` and `revision`.\n\n```json\n{\"action\":\"unpublish\",\"revision\":3}\n```\n\nAgents should publish, unpublish or delete only when explicitly instructed.\n\n## Delete and cancel generation\n\nDelete only when explicitly instructed. Send `PATCH /api/sites/{id}` with `action: \"delete\"` and the current `revision` in its JSON request body (Content-Type: application/json). Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.\n\nFor example, use the current saved revision and the token returned by a known generation:\n\n```json\n{\"action\":\"delete\",\"revision\":3,\"generationToken\":\"TOKEN_FROM_GENERATION\"}\n```\n\nOmit generationToken when no known generation needs cancellation.\n\nDeletion checks workspace access and revision, then returns `{ \"deleted\": true, \"id\": \"...\" }`. A stale revision returns 409; reload before retrying. Unpublish with `action: \"unpublish\"` when the draft should remain available.\n\n## Uploads\n\nHTTP uploads are multipart forms with a `file` field and optional `organizationId` query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature.\n\nMCP's `upload_site_asset` accepts `name`, `contentType`, `base64` file bytes, and optional `organizationId`. It uses the same validation and storage path as HTTP.\n\n## Public endpoints\n\n- `GET /api/sites/public/{id}` returns `{ snapshot: ... }` for a published site only. Drafts, account identifiers, and signup data are excluded.\n- `POST /api/sites/public/{id}/signup` accepts `{\"email\":\"fan@example.com\",\"consent\":\"yes\"}`. An optional `website` honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups.\n\nPublic pages and the browser music player render in the chat app. The API provides\nsnapshots, generation, uploads, signup persistence and the fan-connection integration\nroutes listed below.\n\n## Route coverage\n\nThe lifecycle and public snapshot/signup operations above are documented here in\nprose; they are not a complete Sites OpenAPI specification. The following existing\nroutes are accounted for as integration surfaces, outside the copyable lifecycle\nexamples. Listing them does not establish live authorization or add an MCP tool.\n\n### Authenticated integration routes\n\n| HTTP | Purpose |\n| --- | --- |\n| `GET /api/sites/{id}/fan-connection` | Read fan-connection configuration |\n| `PUT /api/sites/{id}/fan-connection` | Configure the fan connection through the authenticated integration |\n| `GET /api/sites/{id}/fans` | Fan reporting |\n| `GET /api/sites/{id}/activity` | Activity reporting |\n\n### Browser integration routes\n\n| HTTP | Purpose |\n| --- | --- |\n| `GET /api/sites/apple/config` | Browser music configuration |\n| `POST /api/sites/public/{id}/activity` | Published-site activity collection |\n| `GET /api/sites/public/{id}/spotify` | Show the fan-connection acceptance page |\n| `POST /api/sites/public/{id}/spotify` | Begin Spotify authorization after acceptance |\n\nThese browser flows are not replacements for a private lifecycle request or proof\nof a completed fan connection. Email signup and Spotify connection are distinct.\n\n### Provider callback\n\n`GET /api/sites/spotify/callback` completes the provider redirect flow. It is\nintentionally excluded from agent lifecycle examples; do not invoke it as a\nstandalone operation. OPTIONS preflight handlers are also excluded from the\noperation tables because they serve browser CORS negotiation.\n\n## Errors\n\n- `402`: publication requires an eligible paid workspace.\n\n`400` invalid input; `401` missing/invalid authentication; `403` workspace or artist access denied; `404` missing/unpublished site; `409` stale revision; `422` Spotify metadata unavailable; `503` temporary operation failure.\n","headings":[{"title":"Authentication","id":"authentication"},{"title":"Endpoints and tools","id":"endpoints-and-tools"},{"title":"Create and generate","id":"create-and-generate"},{"title":"Generate from saved Context Engine evidence","id":"generate-from-saved-context-engine-evidence"},{"title":"Publish","id":"publish"},{"title":"Delete and cancel generation","id":"delete-and-cancel-generation"},{"title":"Uploads","id":"uploads"},{"title":"Public endpoints","id":"public-endpoints"},{"title":"Route coverage","id":"route-coverage"},{"title":"Errors","id":"errors"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a \", _jsx(_components.strong, {\n children: \"private draft\"\n }), \". Generation never publishes it automatically.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication\",\n children: \"Authentication\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Private HTTP endpoints accept exactly one of \", _jsx(_components.code, {\n children: \"x-api-key: YOUR_API_KEY\"\n }), \" or \", _jsx(_components.code, {\n children: \"Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN\"\n }), \".\\nMCP uses the existing authenticated \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" connection.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The caller is derived from authentication. Do not send an \", _jsx(_components.code, {\n children: \"account_id\"\n }), \". An optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" selects a workspace the caller can access. Omit it for the authenticated account's workspace.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"endpoints-and-tools\",\n children: \"Endpoints and tools\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"MCP tool\"\n }), _jsx(_components.th, {\n children: \"Result\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"list_sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ sites: [...] }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"create_site\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"{ site: ... }\"\n }), \", HTTP 201\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ site: ... }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"concepts\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"propose_site_concepts\"\n })\n }), _jsx(_components.td, {\n children: \"Short pitches or missing context\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"generate\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"generate_site\"\n })\n }), _jsx(_components.td, {\n children: \"Generate from an optional customer-selected pitch; otherwise select a concept\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"generation\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site_generation\"\n })\n }), _jsx(_components.td, {\n children: \"Status for the specified generation token\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"publish\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"publish_site\"\n })\n }), _jsxs(_components.td, {\n children: [\"Publish the saved draft or the playable build selected by \", _jsx(_components.code, {\n children: \"generationToken\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"unpublish\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"unpublish_site\"\n })\n }), _jsx(_components.td, {\n children: \"Public snapshot removed, draft retained\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"delete\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"delete_site\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ \\\"deleted\\\": true, \\\"id\\\": \\\"...\\\" }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/signups\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site_signups\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"{ signups: [{ email, created_at }] }\"\n }), \", up to 10,000\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/assets\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"upload_site_asset\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ asset: { url, name, type } }\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Listing accepts optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" and \", _jsx(_components.code, {\n children: \"artistId\"\n }), \" query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"create-and-generate\",\n children: \"Create and generate\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Create a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL.\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl https://api.recoupable.dev/api/sites \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"releaseUrl\\\":\\\"https://open.spotify.com/track/TRACK_ID\\\",\\\"brief\\\":\\\"Build a maze game\\\"}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Optional creation fields: \", _jsx(_components.code, {\n children: \"name\"\n }), \" (120 characters), \", _jsx(_components.code, {\n children: \"brief\"\n }), \" (6,000), \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \", \", _jsx(_components.code, {\n children: \"artistId\"\n }), \", and \", _jsx(_components.code, {\n children: \"assets\"\n }), \" (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Read \", _jsx(_components.code, {\n children: \"site.id\"\n }), \" and \", _jsx(_components.code, {\n children: \"site.revision\"\n }), \", then start automatic generation:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"generate\\\",\\\"revision\\\":0}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"For Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"To choose a concept yourself before generation, optionally request pitches:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"concepts\\\",\\\"revision\\\":0}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send this to \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \", or call MCP \", _jsx(_components.code, {\n children: \"propose_site_concepts\"\n }), \" with \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \". Optional \", _jsx(_components.code, {\n children: \"instruction\"\n }), \" and \", _jsx(_components.code, {\n children: \"contextBriefId\"\n }), \" apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response is \", _jsx(_components.code, {\n children: \"{ concepts: { status, candidates, reason }, revision }\"\n }), \". Status is \", _jsx(_components.code, {\n children: \"ready\"\n }), \", \", _jsx(_components.code, {\n children: \"needs-context\"\n }), \", or \", _jsx(_components.code, {\n children: \"no-good-concept\"\n }), \". Metadata and cover details alone return \", _jsx(_components.code, {\n children: \"needs-context\"\n }), \"; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"In the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"activity\"\n }), \", \", _jsx(_components.code, {\n children: \"fanMotivation\"\n }), \", \", _jsx(_components.code, {\n children: \"songOrArtistConnection\"\n }), \", and \", _jsx(_components.code, {\n children: \"friendHook\"\n }), \". Pass the selected object unchanged as \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"action\\\": \\\"generate\\\",\\n \\\"revision\\\": 0,\\n \\\"approvedConcept\\\": {\\n \\\"name\\\": \\\"CUSTOMER_SELECTED_NAME\\\",\\n \\\"activity\\\": \\\"SELECTED_ACTIVITY\\\",\\n \\\"fanMotivation\\\": \\\"SELECTED_MOTIVATION\\\",\\n \\\"songOrArtistConnection\\\": \\\"SELECTED_CONNECTION\\\",\\n \\\"friendHook\\\": \\\"SELECTED_HOOK\\\"\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP \", _jsx(_components.code, {\n children: \"generate_site\"\n }), \" accepts the same fields plus \", _jsx(_components.code, {\n children: \"id\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \". A customer-authored concept is also accepted. The optional \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \" preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Generation defaults to background execution and returns a generation token; poll \", _jsx(_components.code, {\n children: \"get_site_generation\"\n }), \" (HTTP action \", _jsx(_components.code, {\n children: \"generation\"\n }), \") for the result. Set \", _jsx(_components.code, {\n children: \"background: false\"\n }), \" only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked \", _jsx(_components.code, {\n children: \"needs-review\"\n }), \"; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Generation failures identify the stopped stage and leave the saved draft unchanged. A \", _jsx(_components.code, {\n children: \"409\"\n }), \" means another edit changed the revision; read the site again before retrying.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"poll-background-generation\",\n children: \"Poll background generation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send this JSON body to \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" using the token returned by the\\ngeneration request. MCP \", _jsx(_components.code, {\n children: \"get_site_generation\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"token\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \".\\nPolling uses \", _jsx(_components.code, {\n children: \"token\"\n }), \"; publishing and cancellation use \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"generation\\\",\\\"token\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"The token is bound to its site and caller and expires. Invalid, expired or\\nmismatched tokens return 404 during token verification; a missing or empty token\\nis invalid input (400). A running job is not proof that a\\nplayable build or a published page exists; read the returned status and progress.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"generate-from-saved-context-engine-evidence\",\n children: \"Generate from saved Context Engine evidence\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save a single-song \", _jsx(_components.code, {\n children: \"creative_direction\"\n }), \" brief using the Context Engine \", _jsx(_components.code, {\n children: \"save_brief\"\n }), \" action, then pass its snapshot ID when requesting pitches:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"action\\\": \\\"concepts\\\",\\n \\\"revision\\\": 0,\\n \\\"contextBriefId\\\": \\\"SAVED_BRIEF_UUID\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass the same \", _jsx(_components.code, {\n children: \"contextBriefId\"\n }), \" with the selected \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \" to generation. It is available on both MCP \", _jsx(_components.code, {\n children: \"propose_site_concepts\"\n }), \" and \", _jsx(_components.code, {\n children: \"generate_site\"\n }), \". Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Generation still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"publish\",\n children: \"Publish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"After reviewing the intended draft or preview, publish through the same PATCH\\nendpoint or MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \", using the site's current saved revision.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Publishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports \", _jsx(_components.code, {\n children: \"fanConnection: \\\"enabled\\\"\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a custom hosted destination, HTTP callers may include \", _jsx(_components.code, {\n children: \"returnUrl\"\n }), \" (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The public page is \", _jsx(_components.code, {\n children: \"https://chat.recoupable.dev/s/{id}\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"publish-the-saved-draft\",\n children: \"Publish the saved draft\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the current revision from the saved site (3 in this example):\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"publish\\\",\\\"revision\\\":3}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Omitting \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" selects the saved draft, even when a background job has\\na newer preview. MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"publish-a-working-preview\",\n children: \"Publish a working preview\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To publish a specific working preview from a background generation, pass its\\ntoken as \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" and the site's current saved revision:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"publish\\\",\\\"revision\\\":3,\\\"generationToken\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \" uses the same fields plus \", _jsx(_components.code, {\n children: \"id\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \". The token must\\nmatch the site and caller. The selected build must contain a completed playable\\nbuild step for the current site/workspace/revision; the whole generation job need\\nnot already be completed. A preview that is not ready returns 400, a stale build\\nreturns 409, and invalid or expired token access returns 404. A temporary saved-build\\nfailure may return 503. Without \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \", publication uses the saved draft;\\nit does not automatically select the newest background preview.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"upgrade-required\",\n children: \"Upgrade required\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"An ineligible workspace receives HTTP 402 with an error body, for example:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"error\\\":\\\"An active paid Recoup subscription is required to publish a site. Subscribe in this site’s workspace, then publish again.\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Subscribe in the site's owning workspace before retrying the intended publish.\\nThis response does not publish the site or create a checkout session.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"unpublish\",\n children: \"Unpublish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" with the current revision to remove the public\\nsnapshot while retaining the draft. MCP \", _jsx(_components.code, {\n children: \"unpublish_site\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"unpublish\\\",\\\"revision\\\":3}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Agents should publish, unpublish or delete only when explicitly instructed.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"delete-and-cancel-generation\",\n children: \"Delete and cancel generation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Delete only when explicitly instructed. Send \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" with \", _jsx(_components.code, {\n children: \"action: \\\"delete\\\"\"\n }), \" and the current \", _jsx(_components.code, {\n children: \"revision\"\n }), \" in its JSON request body (Content-Type: application/json). Include \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For example, use the current saved revision and the token returned by a known generation:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"delete\\\",\\\"revision\\\":3,\\\"generationToken\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Omit generationToken when no known generation needs cancellation.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Deletion checks workspace access and revision, then returns \", _jsx(_components.code, {\n children: \"{ \\\"deleted\\\": true, \\\"id\\\": \\\"...\\\" }\"\n }), \". A stale revision returns 409; reload before retrying. Unpublish with \", _jsx(_components.code, {\n children: \"action: \\\"unpublish\\\"\"\n }), \" when the draft should remain available.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"uploads\",\n children: \"Uploads\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP uploads are multipart forms with a \", _jsx(_components.code, {\n children: \"file\"\n }), \" field and optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP's \", _jsx(_components.code, {\n children: \"upload_site_asset\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"contentType\"\n }), \", \", _jsx(_components.code, {\n children: \"base64\"\n }), \" file bytes, and optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \". It uses the same validation and storage path as HTTP.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"public-endpoints\",\n children: \"Public endpoints\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{id}\"\n }), \" returns \", _jsx(_components.code, {\n children: \"{ snapshot: ... }\"\n }), \" for a published site only. Drafts, account identifiers, and signup data are excluded.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/signup\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{\\\"email\\\":\\\"fan@example.com\\\",\\\"consent\\\":\\\"yes\\\"}\"\n }), \". An optional \", _jsx(_components.code, {\n children: \"website\"\n }), \" honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Public pages and the browser music player render in the chat app. The API provides\\nsnapshots, generation, uploads, signup persistence and the fan-connection integration\\nroutes listed below.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"route-coverage\",\n children: \"Route coverage\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The lifecycle and public snapshot/signup operations above are documented here in\\nprose; they are not a complete Sites OpenAPI specification. The following existing\\nroutes are accounted for as integration surfaces, outside the copyable lifecycle\\nexamples. Listing them does not establish live authorization or add an MCP tool.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"authenticated-integration-routes\",\n children: \"Authenticated integration routes\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"Purpose\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/fan-connection\"\n })\n }), _jsx(_components.td, {\n children: \"Read fan-connection configuration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"PUT /api/sites/{id}/fan-connection\"\n })\n }), _jsx(_components.td, {\n children: \"Configure the fan connection through the authenticated integration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/fans\"\n })\n }), _jsx(_components.td, {\n children: \"Fan reporting\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/activity\"\n })\n }), _jsx(_components.td, {\n children: \"Activity reporting\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"browser-integration-routes\",\n children: \"Browser integration routes\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"Purpose\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/apple/config\"\n })\n }), _jsx(_components.td, {\n children: \"Browser music configuration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/activity\"\n })\n }), _jsx(_components.td, {\n children: \"Published-site activity collection\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/public/{id}/spotify\"\n })\n }), _jsx(_components.td, {\n children: \"Show the fan-connection acceptance page\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/spotify\"\n })\n }), _jsx(_components.td, {\n children: \"Begin Spotify authorization after acceptance\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"These browser flows are not replacements for a private lifecycle request or proof\\nof a completed fan connection. Email signup and Spotify connection are distinct.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"provider-callback\",\n children: \"Provider callback\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/spotify/callback\"\n }), \" completes the provider redirect flow. It is\\nintentionally excluded from agent lifecycle examples; do not invoke it as a\\nstandalone operation. OPTIONS preflight handlers are also excluded from the\\noperation tables because they serve browser CORS negotiation.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"errors\",\n children: \"Errors\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"402\"\n }), \": publication requires an eligible paid workspace.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"400\"\n }), \" invalid input; \", _jsx(_components.code, {\n children: \"401\"\n }), \" missing/invalid authentication; \", _jsx(_components.code, {\n children: \"403\"\n }), \" workspace or artist access denied; \", _jsx(_components.code, {\n children: \"404\"\n }), \" missing/unpublished site; \", _jsx(_components.code, {\n children: \"409\"\n }), \" stale revision; \", _jsx(_components.code, {\n children: \"422\"\n }), \" Spotify metadata unavailable; \", _jsx(_components.code, {\n children: \"503\"\n }), \" temporary operation failure.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Sites Create, generate, and publish fan experiences through the API or MCP. Sites Sites Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a **private draft**. Generation never publishes it automatically. ## Authentication Private HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`. MCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection. The caller is derived from authentication. Do not send an `account_id`. An optional `organizationId` selects a workspace the caller can access. Omit it for the authenticated account's workspace. ## Endpoints and tools | HTTP | MCP tool | Result | | --- | --- | --- | | `GET /api/sites` | `list_sites` | `{ sites: [...] }` | | `POST /api/sites` | `create_site` | `{ site: ... }`, HTTP 201 | | `GET /api/sites/{id}` | `get_site` | `{ site: ... }` | | `PATCH /api/sites/{id}` action `concepts` | `propose_site_concepts` | Short pitches or missing context | | `PATCH /api/sites/{id}` action `generate` | `generate_site` | Generate from an optional customer-selected pitch; otherwise select a concept | | `PATCH /api/sites/{id}` action `generation` | `get_site_generation` | Status for the specified generation token | | `PATCH /api/sites/{id}` action `publish` | `publish_site` | Publish the saved draft or the playable build selected by `generationToken` | | `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained | | `PATCH /api/sites/{id}` action `delete` | `delete_site` | `{ \"deleted\": true, \"id\": \"...\" }` | | `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 | | `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` | Listing accepts optional `organizationId` and `artistId` query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response. ## Create and generate Create a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL. Optional creation fields: `name` (120 characters), `brief` (6,000), `organizationId`, `artistId`, and `assets` (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used. Read `site.id` and `site.revision`, then start automatic generation: For Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused. To choose a concept yourself before generation, optionally request pitches: Send this to `PATCH /api/sites/{id}`, or call MCP `propose_site_concepts` with `id` and `revision`. Optional `instruction` and `contextBriefId` apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft. The response is `{ concepts: { status, candidates, reason }, revision }`. Status is `ready`, `needs-context`, or `no-good-concept`. Metadata and cover details alone return `needs-context`; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork. In the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains `name`, `activity`, `fanMotivation`, `songOrArtistConnection`, and `friendHook`. Pass the selected object unchanged as `approvedConcept`: MCP `generate_site` accepts the same fields plus `id`, without `action`. A customer-authored concept is also accepted. The optional `approvedConcept` preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context. Generation defaults to background execution and returns a generation token; poll `get_site_generation` (HTTP action `generation`) for the result. Set `background: false` only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked `needs-review`; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass. Generation failures identify the stopped stage and leave the saved draft unchanged. A `409` means another edit changed the revision; read the site again before retrying. ### Poll background generation Send this JSON body to `PATCH /api/sites/{id}` using the token returned by the generation request. MCP `get_site_generation` takes `id` and `token`, without `action`. Polling uses `token`; publishing and cancellation use `generationToken`. The token is bound to its site and caller and expires. Invalid, expired or mismatched tokens return 404 during token verification; a missing or empty token is invalid input (400). A running job is not proof that a playable build or a published page exists; read the returned status and progress. ## Generate from saved Context Engine evidence Save a single-song `creative_direction` brief using the Context Engine `save_brief` action, then pass its snapshot ID when requesting pitches: Pass the same `contextBriefId` with the selected `approvedConcept` to generation. It is available on both MCP `propose_site_concepts` and `generate_site`. Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied. This path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial. Generation still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response. ## Publish After reviewing the intended draft or preview, publish through the same PATCH endpoint or MCP `publish_site`, using the site's current saved revision. Publishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports `fanConnection: \"enabled\"`. For a custom hosted destination, HTTP callers may include `returnUrl` (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations. The public page is `https://chat.recoupable.dev/s/{id}`. ### Publish the saved draft Use the current revision from the saved site (3 in this example): Omitting `generationToken` selects the saved draft, even when a background job has a newer preview. MCP `publish_site` takes `id` and `revision`, without `action`. ### Publish a working preview To publish a specific working preview from a background generation, pass its token as `generationToken` and the site's current saved revision: MCP `publish_site` uses the same fields plus `id`, without `action`. The token must match the site and caller. The selected build must contain a completed playable build step for the current site/workspace/revision; the whole generation job need not already be completed. A preview that is not ready returns 400, a stale build returns 409, and invalid or expired token access returns 404. A temporary saved-build failure may return 503. Without `generationToken`, publication uses the saved draft; it does not automatically select the newest background preview. ### Upgrade required An ineligible workspace receives HTTP 402 with an error body, for example: Subscribe in the site's owning workspace before retrying the intended publish. This response does not publish the site or create a checkout session. ### Unpublish Send `PATCH /api/sites/{id}` with the current revision to remove the public snapshot while retaining the draft. MCP `unpublish_site` takes `id` and `revision`. Agents should publish, unpublish or delete only when explicitly instructed. ## Delete and cancel generation Delete only when explicitly instructed. Send `PATCH /api/sites/{id}` with `action: \"delete\"` and the current `revision` in its JSON request body (Content-Type: application/json). Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job. For example, use the current saved revision and the token returned by a known generation: Omit generationToken when no known generation needs cancellation. Deletion checks workspace access and revision, then returns `{ \"deleted\": true, \"id\": \"...\" }`. A stale revision returns 409; reload before retrying. Unpublish with `action: \"unpublish\"` when the draft should remain available. ## Uploads HTTP uploads are multipart forms with a `file` field and optional `organizationId` query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature. MCP's `upload_site_asset` accepts `name`, `contentType`, `base64` file bytes, and optional `organizationId`. It uses the same validation and storage path as HTTP. ## Public endpoints - `GET /api/sites/public/{id}` returns `{ snapshot: ... }` for a published site only. Drafts, account identifiers, and signup data are excluded. - `POST /api/sites/public/{id}/signup` accepts `{\"email\":\"fan@example.com\",\"consent\":\"yes\"}`. An optional `website` honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups. Public pages and the browser music player render in the chat app. The API provides snapshots, generation, uploads, signup persistence and the fan-connection integration routes listed below. ## Route coverage The lifecycle and public snapshot/signup operations above are documented here in prose; they are not a complete Sites OpenAPI specification. The following existing routes are accounted for as integration surfaces, outside the copyable lifecycle examples. Listing them does not establish live authorization or add an MCP tool. ### Authenticated integration routes | HTTP | Purpose | | --- | --- | | `GET /api/sites/{id}/fan-connection` | Read fan-connection configuration | | `PUT /api/sites/{id}/fan-connection` | Configure the fan connection through the authenticated integration | | `GET /api/sites/{id}/fans` | Fan reporting | | `GET /api/sites/{id}/activity` | Activity reporting | ### Browser integration routes | HTTP | Purpose | | --- | --- | | `GET /api/sites/apple/config` | Browser music configuration | | `POST /api/sites/public/{id}/activity` | Published-site activity collection | | `GET /api/sites/public/{id}/spotify` | Show the fan-connection acceptance page | | `POST /api/sites/public/{id}/spotify` | Begin Spotify authorization after acceptance | These browser flows are not replacements for a private lifecycle request or proof of a completed fan connection. Email signup and Spotify connection are distinct. ### Provider callback `GET /api/sites/spotify/callback` completes the provider redirect flow. It is intentionally excluded from agent lifecycle examples; do not invoke it as a standalone operation. OPTIONS preflight handlers are also excluded from the operation tables because they serve browser CORS negotiation. ## Errors - `402`: publication requires an eligible paid workspace. `400` invalid input; `401` missing/invalid authentication; `403` workspace or artist access denied; `404` missing/unpublished site; `409` stale revision; `422` Spotify metadata unavailable; `503` temporary operation failure. "},{"slug":"essentials/site-fan-connection","title":"Connect Spotify fans to a site","description":"Configure paid fan connection from an artist agent and retrieve fans attributed to its site.","category":"Sites","group":"Sites","source":"essentials/site-fan-connection.mdx","body":"Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: `https://api.recoupable.dev`.\n\nPrivate calls use `x-api-key: $RECOUP_API_KEY` (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key.\n\n## Customer and site\n\n- `GET /api/accounts/id`: verify the current credential.\n- `POST /api/agents/signup` with `{ \"email\": \"customer@example.com\" }`: request email verification.\n- `POST /api/agents/verify` with `{ \"email\": \"customer@example.com\", \"code\": \"123456\" }`: receive `api_key`; never echo it.\n- `GET /api/artists`: inspect the caller's roster and choose the artist's account ID.\n- `GET /api/sites`: inspect existing site records.\n- `POST /api/sites` with `{ \"name\": \"Release experience\", \"artistId\": \"ARTIST_ACCOUNT_UUID\", \"releaseUrl\": \"https://open.spotify.com/track/TRACK_ID\" }`: register a site. Add `organizationId` only for a selected authorized workspace. Read the returned `site.id`. Omit owner/account ID fields; ownership comes from authentication.\n\n## Configure\n\n`GET /api/sites/{siteId}/fan-connection` returns:\n\n```json\n{\n \"siteId\": \"SITE_UUID\",\n \"ownerId\": \"WORKSPACE_ACCOUNT_UUID\",\n \"artistId\": \"ARTIST_ACCOUNT_UUID\",\n \"config\": null,\n \"connectUrl\": null\n}\n```\n\nExisting `config` contains `site_id`, `return_url`, `marketing_text`, `enabled` and `revision`. Update with `PUT /api/sites/{siteId}/fan-connection`:\n\n```json\n{\n \"returnUrl\": \"https://artist.example/release\",\n \"marketingText\": \"I agree to receive release announcements and offers by email from Example Artist.\",\n \"enabled\": true,\n \"revision\": 0\n}\n```\n\nUse the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public `connectUrl`; always use that returned URL.\n\n- 400: invalid input or missing artist attribution.\n- 401/403: reconnect the customer or select an authorized workspace.\n- 402: no eligible paid subscription for the site's owning account.\n- 404: missing site or API not deployed; inspect the actual response.\n- 409: another configuration update won; reload and reconcile before retry.\n- 503: provider, billing or storage unavailable; surface the dependency.\n\nSpotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing `POST /api/subscriptions/sessions` accepts `{plan: \"starter\" | \"pro\", successUrl, cancelUrl?}` and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature.\n\n## Public fan journey\n\n`GET /api/sites/public/{siteId}/spotify` displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's `/api/sites/spotify/callback`; Recoup then returns to the configured site URL with `recoup_spotify=connected`, `cancelled` or `failed`.\n\nOnly a successful provider exchange with `user-read-email` and `user-read-private` creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site.\n\n## Read fans\n\n`GET /api/sites/{siteId}/fans?offset=0&limit=50` (private):\n\n```json\n{\n \"fans\": [],\n \"total\": 0,\n \"offset\": 0,\n \"limit\": 50\n}\n```\n\nEach fan has `id`, `site_id`, `spotify_id`, `display_name`, `email`, first/last connection timestamps and nested `site_fan_connections` with `site_fan_permissions` and `site_fan_marketing_consents`. Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data.\n\nStarter Checkout can return HTTP 400 `starter_unavailable` when its price is not\nconfigured. Explain the unavailable option and use a configured plan; do not retry\nit as a transient provider failure.\n\n## Recoup operator setup\n\nOperators must apply `20260928010000_site_fan_connections.sql`, configure `SITES_SPOTIFY_CLIENT_ID`, register an HTTPS callback ending `/api/sites/spotify/callback`, set `SITES_FAN_SPOTIFY_REDIRECT_URI`. This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate.\n\n## Activity reporting\n\n`GET /api/sites/{siteId}/activity` returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. `POST /api/sites/public/{siteId}/activity` accepts `{id: EVENT_UUID, visitId: VISIT_UUID, event: \"visit\" | \"start\" | \"complete\" | \"replay\" | \"share\"}`. Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history.\n\nRecoup-hosted generated sites use the trusted host bridge: `window.recoup.track(event)` reports approved events; `window.recoup.join()` reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server.\n\n## Playback for Premium and Free listeners\n\nThe hosted player reads the connected Spotify profile's `product` field. Premium listeners use the Spotify Web Playback SDK. Free (`free` or `open`) listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording.\n\n`GET /api/sites/public/{siteId}` includes `playbackAudioUrl`, a fresh signed audio URL valid for one hour, or `null` when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans.\n\nFile playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable.\n","headings":[{"title":"Customer and site","id":"customer-and-site"},{"title":"Configure","id":"configure"},{"title":"Public fan journey","id":"public-fan-journey"},{"title":"Read fans","id":"read-fans"},{"title":"Recoup operator setup","id":"recoup-operator-setup"},{"title":"Activity reporting","id":"activity-reporting"},{"title":"Playback for Premium and Free listeners","id":"playback-for-premium-and-free-listeners"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Private calls use \", _jsx(_components.code, {\n children: \"x-api-key: $RECOUP_API_KEY\"\n }), \" (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"customer-and-site\",\n children: \"Customer and site\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n }), \": verify the current credential.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"email\\\": \\\"customer@example.com\\\" }\"\n }), \": request email verification.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"email\\\": \\\"customer@example.com\\\", \\\"code\\\": \\\"123456\\\" }\"\n }), \": receive \", _jsx(_components.code, {\n children: \"api_key\"\n }), \"; never echo it.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/artists\"\n }), \": inspect the caller's roster and choose the artist's account ID.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites\"\n }), \": inspect existing site records.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/sites\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"name\\\": \\\"Release experience\\\", \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\", \\\"releaseUrl\\\": \\\"https://open.spotify.com/track/TRACK_ID\\\" }\"\n }), \": register a site. Add \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" only for a selected authorized workspace. Read the returned \", _jsx(_components.code, {\n children: \"site.id\"\n }), \". Omit owner/account ID fields; ownership comes from authentication.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"configure\",\n children: \"Configure\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/fan-connection\"\n }), \" returns:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"siteId\\\": \\\"SITE_UUID\\\",\\n \\\"ownerId\\\": \\\"WORKSPACE_ACCOUNT_UUID\\\",\\n \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\",\\n \\\"config\\\": null,\\n \\\"connectUrl\\\": null\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Existing \", _jsx(_components.code, {\n children: \"config\"\n }), \" contains \", _jsx(_components.code, {\n children: \"site_id\"\n }), \", \", _jsx(_components.code, {\n children: \"return_url\"\n }), \", \", _jsx(_components.code, {\n children: \"marketing_text\"\n }), \", \", _jsx(_components.code, {\n children: \"enabled\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \". Update with \", _jsx(_components.code, {\n children: \"PUT /api/sites/{siteId}/fan-connection\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"returnUrl\\\": \\\"https://artist.example/release\\\",\\n \\\"marketingText\\\": \\\"I agree to receive release announcements and offers by email from Example Artist.\\\",\\n \\\"enabled\\\": true,\\n \\\"revision\\\": 0\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public \", _jsx(_components.code, {\n children: \"connectUrl\"\n }), \"; always use that returned URL.\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"400: invalid input or missing artist attribution.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"401/403: reconnect the customer or select an authorized workspace.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"402: no eligible paid subscription for the site's owning account.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"404: missing site or API not deployed; inspect the actual response.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"409: another configuration update won; reload and reconcile before retry.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"503: provider, billing or storage unavailable; surface the dependency.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Spotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing \", _jsx(_components.code, {\n children: \"POST /api/subscriptions/sessions\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{plan: \\\"starter\\\" | \\\"pro\\\", successUrl, cancelUrl?}\"\n }), \" and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"public-fan-journey\",\n children: \"Public fan journey\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{siteId}/spotify\"\n }), \" displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's \", _jsx(_components.code, {\n children: \"/api/sites/spotify/callback\"\n }), \"; Recoup then returns to the configured site URL with \", _jsx(_components.code, {\n children: \"recoup_spotify=connected\"\n }), \", \", _jsx(_components.code, {\n children: \"cancelled\"\n }), \" or \", _jsx(_components.code, {\n children: \"failed\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Only a successful provider exchange with \", _jsx(_components.code, {\n children: \"user-read-email\"\n }), \" and \", _jsx(_components.code, {\n children: \"user-read-private\"\n }), \" creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"read-fans\",\n children: \"Read fans\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/fans?offset=0&limit=50\"\n }), \" (private):\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"fans\\\": [],\\n \\\"total\\\": 0,\\n \\\"offset\\\": 0,\\n \\\"limit\\\": 50\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each fan has \", _jsx(_components.code, {\n children: \"id\"\n }), \", \", _jsx(_components.code, {\n children: \"site_id\"\n }), \", \", _jsx(_components.code, {\n children: \"spotify_id\"\n }), \", \", _jsx(_components.code, {\n children: \"display_name\"\n }), \", \", _jsx(_components.code, {\n children: \"email\"\n }), \", first/last connection timestamps and nested \", _jsx(_components.code, {\n children: \"site_fan_connections\"\n }), \" with \", _jsx(_components.code, {\n children: \"site_fan_permissions\"\n }), \" and \", _jsx(_components.code, {\n children: \"site_fan_marketing_consents\"\n }), \". Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Starter Checkout can return HTTP 400 \", _jsx(_components.code, {\n children: \"starter_unavailable\"\n }), \" when its price is not\\nconfigured. Explain the unavailable option and use a configured plan; do not retry\\nit as a transient provider failure.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"recoup-operator-setup\",\n children: \"Recoup operator setup\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Operators must apply \", _jsx(_components.code, {\n children: \"20260928010000_site_fan_connections.sql\"\n }), \", configure \", _jsx(_components.code, {\n children: \"SITES_SPOTIFY_CLIENT_ID\"\n }), \", register an HTTPS callback ending \", _jsx(_components.code, {\n children: \"/api/sites/spotify/callback\"\n }), \", set \", _jsx(_components.code, {\n children: \"SITES_FAN_SPOTIFY_REDIRECT_URI\"\n }), \". This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"activity-reporting\",\n children: \"Activity reporting\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/activity\"\n }), \" returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. \", _jsx(_components.code, {\n children: \"POST /api/sites/public/{siteId}/activity\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{id: EVENT_UUID, visitId: VISIT_UUID, event: \\\"visit\\\" | \\\"start\\\" | \\\"complete\\\" | \\\"replay\\\" | \\\"share\\\"}\"\n }), \". Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Recoup-hosted generated sites use the trusted host bridge: \", _jsx(_components.code, {\n children: \"window.recoup.track(event)\"\n }), \" reports approved events; \", _jsx(_components.code, {\n children: \"window.recoup.join()\"\n }), \" reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"playback-for-premium-and-free-listeners\",\n children: \"Playback for Premium and Free listeners\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The hosted player reads the connected Spotify profile's \", _jsx(_components.code, {\n children: \"product\"\n }), \" field. Premium listeners use the Spotify Web Playback SDK. Free (\", _jsx(_components.code, {\n children: \"free\"\n }), \" or \", _jsx(_components.code, {\n children: \"open\"\n }), \") listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{siteId}\"\n }), \" includes \", _jsx(_components.code, {\n children: \"playbackAudioUrl\"\n }), \", a fresh signed audio URL valid for one hour, or \", _jsx(_components.code, {\n children: \"null\"\n }), \" when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"File playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Connect Spotify fans to a site Configure paid fan connection from an artist agent and retrieve fans attributed to its site. Sites Sites Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: `https://api.recoupable.dev`. Private calls use `x-api-key: $RECOUP_API_KEY` (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key. ## Customer and site - `GET /api/accounts/id`: verify the current credential. - `POST /api/agents/signup` with `{ \"email\": \"customer@example.com\" }`: request email verification. - `POST /api/agents/verify` with `{ \"email\": \"customer@example.com\", \"code\": \"123456\" }`: receive `api_key`; never echo it. - `GET /api/artists`: inspect the caller's roster and choose the artist's account ID. - `GET /api/sites`: inspect existing site records. - `POST /api/sites` with `{ \"name\": \"Release experience\", \"artistId\": \"ARTIST_ACCOUNT_UUID\", \"releaseUrl\": \"https://open.spotify.com/track/TRACK_ID\" }`: register a site. Add `organizationId` only for a selected authorized workspace. Read the returned `site.id`. Omit owner/account ID fields; ownership comes from authentication. ## Configure `GET /api/sites/{siteId}/fan-connection` returns: Existing `config` contains `site_id`, `return_url`, `marketing_text`, `enabled` and `revision`. Update with `PUT /api/sites/{siteId}/fan-connection`: Use the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public `connectUrl`; always use that returned URL. - 400: invalid input or missing artist attribution. - 401/403: reconnect the customer or select an authorized workspace. - 402: no eligible paid subscription for the site's owning account. - 404: missing site or API not deployed; inspect the actual response. - 409: another configuration update won; reload and reconcile before retry. - 503: provider, billing or storage unavailable; surface the dependency. Spotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing `POST /api/subscriptions/sessions` accepts `{plan: \"starter\" | \"pro\", successUrl, cancelUrl?}` and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature. ## Public fan journey `GET /api/sites/public/{siteId}/spotify` displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's `/api/sites/spotify/callback`; Recoup then returns to the configured site URL with `recoup_spotify=connected`, `cancelled` or `failed`. Only a successful provider exchange with `user-read-email` and `user-read-private` creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site. ## Read fans `GET /api/sites/{siteId}/fans?offset=0&limit=50` (private): Each fan has `id`, `site_id`, `spotify_id`, `display_name`, `email`, first/last connection timestamps and nested `site_fan_connections` with `site_fan_permissions` and `site_fan_marketing_consents`. Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data. Starter Checkout can return HTTP 400 `starter_unavailable` when its price is not configured. Explain the unavailable option and use a configured plan; do not retry it as a transient provider failure. ## Recoup operator setup Operators must apply `20260928010000_site_fan_connections.sql`, configure `SITES_SPOTIFY_CLIENT_ID`, register an HTTPS callback ending `/api/sites/spotify/callback`, set `SITES_FAN_SPOTIFY_REDIRECT_URI`. This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate. ## Activity reporting `GET /api/sites/{siteId}/activity` returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. `POST /api/sites/public/{siteId}/activity` accepts `{id: EVENT_UUID, visitId: VISIT_UUID, event: \"visit\" | \"start\" | \"complete\" | \"replay\" | \"share\"}`. Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history. Recoup-hosted generated sites use the trusted host bridge: `window.recoup.track(event)` reports approved events; `window.recoup.join()` reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server. ## Playback for Premium and Free listeners The hosted player reads the connected Spotify profile's `product` field. Premium listeners use the Spotify Web Playback SDK. Free (`free` or `open`) listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording. `GET /api/sites/public/{siteId}` includes `playbackAudioUrl`, a fresh signed audio URL valid for one hour, or `null` when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans. File playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable. "},{"slug":"essentials/release-player","title":"One player for every release","description":"Create a listening page or embed Spotify and Apple Music playback on your artist website.","category":"Players","group":"Release players","source":"essentials/release-player.mdx","body":"Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.\n\n## Create and publish\n\nUse the [Recoup API](/api-reference/players/create) or the `create_release_player` MCP tool. Choose an artist you can access, name the player, and provide a `spotifyUrl`, an `appleUrl`, or both. Use `organizationId` to create it in your organization workspace.\n\nFor website embeds, add the exact website origins to `allowedOrigins`. An origin includes the scheme, hostname and any non-default port, such as `https://artist.example:8443`. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.\n\nExample create request:\n\n```json\n{\n \"artistId\": \"ARTIST_ACCOUNT_UUID\",\n \"organizationId\": \"ORGANIZATION_UUID\",\n \"name\": \"Release title\",\n \"spotifyUrl\": \"https://open.spotify.com/album/ALBUM_ID\",\n \"appleUrl\": \"https://music.apple.com/us/album/release/APPLE_ID\",\n \"allowedOrigins\": [\"https://artist.example\", \"https://www.artist.example\"]\n}\n```\n\nNew players start unpublished. Review the music links, then publish with `update_release_player`, passing `id`, the current `revision`, and `enabled: true`. Publishing requires an active paid Recoup workspace.\n\nUse the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.\n\nSee [update a release player](/api-reference/players/update) for the REST request and fields.\n\n## Share a listening page\n\nUse the returned `listenUrl` as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.\n\nTo track campaign traffic, add `source`, `medium`, `campaign`, and `content` query parameters. The listening page also accepts `utm_source`, `utm_medium`, `utm_campaign`, and `utm_content`. Use campaign labels, such as `instagram` and `release`; keep personal information out of links.\n\n## Embed on your website\n\nUse the returned `spotifyEmbedUrl` or `appleEmbedUrl` for each configured service. The `parent` parameter must match an approved website origin.\n\n```html\n\n```\n\nKeep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.\n\nFor Spotify Free handoffs, the embed sends a `recoup:open-dsp` message with `provider: \"spotify\"`. Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.\n\n## What fans can play\n\nSpotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.\n\nSpotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.\n\nApple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.\n\n## Optional uploaded audio for Spotify Free fans\n\nYou can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set `freePlayback: \"audio\"` and provide `audioUrl`. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.\n\nUpload an MP3 or WAV through `POST /api/sites/assets` in the same workspace, then use the returned `asset.url`. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.\n\nMCP arguments for `update_release_player`:\n\n```json\n{\n \"id\": \"PLAYER_UUID\",\n \"revision\": 1,\n \"freePlayback\": \"audio\",\n \"audioUrl\": \"WORKSPACE_UPLOADED_ASSET_URL\"\n}\n```\n\nFor REST, send `PATCH /api/players/PLAYER_UUID` with the same body except `id`; the player ID belongs in the URL.\n\nAudio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.\n\nTo restore the Spotify handoff, set `freePlayback: \"spotify\"`. You can also clear `audioUrl` by setting it to `null`.\n\n## Fan contacts belong to your workspace\n\nSpotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.\n\nIf that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.\n\n- Use `get_workspace_player_fans` or [read workspace player fans](/api-reference/players/workspace-fans) to list contacts and their artist relationships.\n- Use `get_release_player_fans` or [read artist player fans](/api-reference/players/fans) to list fan relationships across that artist's players in the workspace.\n\n`contact_id` identifies the workspace contact. Each artist relationship has its own `id`; activity records refer to that relationship as `fan_id`.\n\nSpotify sign-in does **not** grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.\n\n## Measure listening activity\n\nUse `get_release_player_activity` or [read listening activity](/api-reference/players/activity) for 30-day campaign totals and individual track, play, pause and skip events.\n\nThese reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are **not confirmed music-service stream counts** and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.\n\n## Check your fan journey\n\nBefore promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.\n","headings":[{"title":"Create and publish","id":"create-and-publish"},{"title":"Share a listening page","id":"share-a-listening-page"},{"title":"Embed on your website","id":"embed-on-your-website"},{"title":"What fans can play","id":"what-fans-can-play"},{"title":"Optional uploaded audio for Spotify Free fans","id":"optional-uploaded-audio-for-spotify-free-fans"},{"title":"Fan contacts belong to your workspace","id":"fan-contacts-belong-to-your-workspace"},{"title":"Measure listening activity","id":"measure-listening-activity"},{"title":"Check your fan journey","id":"check-your-fan-journey"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"create-and-publish\",\n children: \"Create and publish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the \", _jsx(_components.a, {\n href: \"/api-reference/players/create\",\n children: \"Recoup API\"\n }), \" or the \", _jsx(_components.code, {\n children: \"create_release_player\"\n }), \" MCP tool. Choose an artist you can access, name the player, and provide a \", _jsx(_components.code, {\n children: \"spotifyUrl\"\n }), \", an \", _jsx(_components.code, {\n children: \"appleUrl\"\n }), \", or both. Use \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" to create it in your organization workspace.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For website embeds, add the exact website origins to \", _jsx(_components.code, {\n children: \"allowedOrigins\"\n }), \". An origin includes the scheme, hostname and any non-default port, such as \", _jsx(_components.code, {\n children: \"https://artist.example:8443\"\n }), \". Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Example create request:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\",\\n \\\"organizationId\\\": \\\"ORGANIZATION_UUID\\\",\\n \\\"name\\\": \\\"Release title\\\",\\n \\\"spotifyUrl\\\": \\\"https://open.spotify.com/album/ALBUM_ID\\\",\\n \\\"appleUrl\\\": \\\"https://music.apple.com/us/album/release/APPLE_ID\\\",\\n \\\"allowedOrigins\\\": [\\\"https://artist.example\\\", \\\"https://www.artist.example\\\"]\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"New players start unpublished. Review the music links, then publish with \", _jsx(_components.code, {\n children: \"update_release_player\"\n }), \", passing \", _jsx(_components.code, {\n children: \"id\"\n }), \", the current \", _jsx(_components.code, {\n children: \"revision\"\n }), \", and \", _jsx(_components.code, {\n children: \"enabled: true\"\n }), \". Publishing requires an active paid Recoup workspace.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/players/update\",\n children: \"update a release player\"\n }), \" for the REST request and fields.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"share-a-listening-page\",\n children: \"Share a listening page\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the returned \", _jsx(_components.code, {\n children: \"listenUrl\"\n }), \" as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To track campaign traffic, add \", _jsx(_components.code, {\n children: \"source\"\n }), \", \", _jsx(_components.code, {\n children: \"medium\"\n }), \", \", _jsx(_components.code, {\n children: \"campaign\"\n }), \", and \", _jsx(_components.code, {\n children: \"content\"\n }), \" query parameters. The listening page also accepts \", _jsx(_components.code, {\n children: \"utm_source\"\n }), \", \", _jsx(_components.code, {\n children: \"utm_medium\"\n }), \", \", _jsx(_components.code, {\n children: \"utm_campaign\"\n }), \", and \", _jsx(_components.code, {\n children: \"utm_content\"\n }), \". Use campaign labels, such as \", _jsx(_components.code, {\n children: \"instagram\"\n }), \" and \", _jsx(_components.code, {\n children: \"release\"\n }), \"; keep personal information out of links.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"embed-on-your-website\",\n children: \"Embed on your website\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the returned \", _jsx(_components.code, {\n children: \"spotifyEmbedUrl\"\n }), \" or \", _jsx(_components.code, {\n children: \"appleEmbedUrl\"\n }), \" for each configured service. The \", _jsx(_components.code, {\n children: \"parent\"\n }), \" parameter must match an approved website origin.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-html\",\n children: \"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For Spotify Free handoffs, the embed sends a \", _jsx(_components.code, {\n children: \"recoup:open-dsp\"\n }), \" message with \", _jsx(_components.code, {\n children: \"provider: \\\"spotify\\\"\"\n }), \". Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-fans-can-play\",\n children: \"What fans can play\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"optional-uploaded-audio-for-spotify-free-fans\",\n children: \"Optional uploaded audio for Spotify Free fans\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set \", _jsx(_components.code, {\n children: \"freePlayback: \\\"audio\\\"\"\n }), \" and provide \", _jsx(_components.code, {\n children: \"audioUrl\"\n }), \". This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Upload an MP3 or WAV through \", _jsx(_components.code, {\n children: \"POST /api/sites/assets\"\n }), \" in the same workspace, then use the returned \", _jsx(_components.code, {\n children: \"asset.url\"\n }), \". The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP arguments for \", _jsx(_components.code, {\n children: \"update_release_player\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"id\\\": \\\"PLAYER_UUID\\\",\\n \\\"revision\\\": 1,\\n \\\"freePlayback\\\": \\\"audio\\\",\\n \\\"audioUrl\\\": \\\"WORKSPACE_UPLOADED_ASSET_URL\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For REST, send \", _jsx(_components.code, {\n children: \"PATCH /api/players/PLAYER_UUID\"\n }), \" with the same body except \", _jsx(_components.code, {\n children: \"id\"\n }), \"; the player ID belongs in the URL.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To restore the Spotify handoff, set \", _jsx(_components.code, {\n children: \"freePlayback: \\\"spotify\\\"\"\n }), \". You can also clear \", _jsx(_components.code, {\n children: \"audioUrl\"\n }), \" by setting it to \", _jsx(_components.code, {\n children: \"null\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"fan-contacts-belong-to-your-workspace\",\n children: \"Fan contacts belong to your workspace\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_workspace_player_fans\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/workspace-fans\",\n children: \"read workspace player fans\"\n }), \" to list contacts and their artist relationships.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_release_player_fans\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/fans\",\n children: \"read artist player fans\"\n }), \" to list fan relationships across that artist's players in the workspace.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"contact_id\"\n }), \" identifies the workspace contact. Each artist relationship has its own \", _jsx(_components.code, {\n children: \"id\"\n }), \"; activity records refer to that relationship as \", _jsx(_components.code, {\n children: \"fan_id\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Spotify sign-in does \", _jsx(_components.strong, {\n children: \"not\"\n }), \" grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"measure-listening-activity\",\n children: \"Measure listening activity\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_release_player_activity\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/activity\",\n children: \"read listening activity\"\n }), \" for 30-day campaign totals and individual track, play, pause and skip events.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are \", _jsx(_components.strong, {\n children: \"not confirmed music-service stream counts\"\n }), \" and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"check-your-fan-journey\",\n children: \"Check your fan journey\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"One player for every release Create a listening page or embed Spotify and Apple Music playback on your artist website. Players Release players Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting. ## Create and publish Use the [Recoup API](/api-reference/players/create) or the `create_release_player` MCP tool. Choose an artist you can access, name the player, and provide a `spotifyUrl`, an `appleUrl`, or both. Use `organizationId` to create it in your organization workspace. For website embeds, add the exact website origins to `allowedOrigins`. An origin includes the scheme, hostname and any non-default port, such as `https://artist.example:8443`. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page. Example create request: New players start unpublished. Review the music links, then publish with `update_release_player`, passing `id`, the current `revision`, and `enabled: true`. Publishing requires an active paid Recoup workspace. Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect. See [update a release player](/api-reference/players/update) for the REST request and fields. ## Share a listening page Use the returned `listenUrl` as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player. To track campaign traffic, add `source`, `medium`, `campaign`, and `content` query parameters. The listening page also accepts `utm_source`, `utm_medium`, `utm_campaign`, and `utm_content`. Use campaign labels, such as `instagram` and `release`; keep personal information out of links. ## Embed on your website Use the returned `spotifyEmbedUrl` or `appleEmbedUrl` for each configured service. The `parent` parameter must match an approved website origin. Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable. For Spotify Free handoffs, the embed sends a `recoup:open-dsp` message with `provider: \"spotify\"`. Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message. ## What fans can play Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify. Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free. Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup. ## Optional uploaded audio for Spotify Free fans You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set `freePlayback: \"audio\"` and provide `audioUrl`. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify. Upload an MP3 or WAV through `POST /api/sites/assets` in the same workspace, then use the returned `asset.url`. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback. MCP arguments for `update_release_player`: For REST, send `PATCH /api/players/PLAYER_UUID` with the same body except `id`; the player ID belongs in the URL. Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link. To restore the Spotify handoff, set `freePlayback: \"spotify\"`. You can also clear `audioUrl` by setting it to `null`. ## Fan contacts belong to your workspace Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace. If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans. - Use `get_workspace_player_fans` or [read workspace player fans](/api-reference/players/workspace-fans) to list contacts and their artist relationships. - Use `get_release_player_fans` or [read artist player fans](/api-reference/players/fans) to list fan relationships across that artist's players in the workspace. `contact_id` identifies the workspace contact. Each artist relationship has its own `id`; activity records refer to that relationship as `fan_id`. Spotify sign-in does **not** grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts. ## Measure listening activity Use `get_release_player_activity` or [read listening activity](/api-reference/players/activity) for 30-day campaign totals and individual track, play, pause and skip events. These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are **not confirmed music-service stream counts** and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance. ## Check your fan journey Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace. "},{"slug":"api-reference/players/create","title":"Create a release player","description":"Create a release player","category":"Players","group":"Release players","source":"api-reference/players/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/players","spec":"players.json"},"searchText":"Create a release player Create a release player Players Release players POST /api/players "},{"slug":"api-reference/players/list","title":"List release players","description":"List release players","category":"Players","group":"Release players","source":"api-reference/players/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players","spec":"players.json"},"searchText":"List release players List release players Players Release players GET /api/players "},{"slug":"api-reference/players/get","title":"Read a release player","description":"Read a release player","category":"Players","group":"Release players","source":"api-reference/players/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}","spec":"players.json"},"searchText":"Read a release player Read a release player Players Release players GET /api/players/{id} "},{"slug":"api-reference/players/update","title":"Update a release player","description":"Update a release player","category":"Players","group":"Release players","source":"api-reference/players/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/players/{id}","spec":"players.json"},"searchText":"Update a release player Update a release player Players Release players PATCH /api/players/{id} "},{"slug":"api-reference/players/activity","title":"Read listening activity","description":"Read player listening activity","category":"Players","group":"Release players","source":"api-reference/players/activity.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}/activity","spec":"players.json"},"searchText":"Read listening activity Read player listening activity Players Release players GET /api/players/{id}/activity "},{"slug":"api-reference/players/fans","title":"Read artist player fans","description":"Read artist player fans","category":"Players","group":"Release players","source":"api-reference/players/fans.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}/fans","spec":"players.json"},"searchText":"Read artist player fans Read artist player fans Players Release players GET /api/players/{id}/fans "},{"slug":"api-reference/players/workspace-fans","title":"Read workspace player fans","description":"Read workspace player fans","category":"Players","group":"Release players","source":"api-reference/players/workspace-fans.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/fans","spec":"players.json"},"searchText":"Read workspace player fans Read workspace player fans Players Release players GET /api/players/fans "},{"slug":"api-reference/complete/content/post-content-packs","title":"POST /api/content/packs","description":"Release rollout pending; discover current host capabilities before execution. Prepare a resumable pack brief. No artist profile or GitHub repository required; no paid generation.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs","spec":"content.json"},"searchText":"POST /api/content/packs Release rollout pending; discover current host capabilities before execution. Prepare a resumable pack brief. No artist profile or GitHub repository required; no paid generation."},{"slug":"api-reference/complete/content/get-content-packs-id","title":"GET /api/content/packs/{id}","description":"Release rollout pending; discover current host capabilities before execution. Read current owned job, assets, gaps and next action.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"GET","path":"/api/content/packs/{id}","spec":"content.json"},"searchText":"GET /api/content/packs/{id} Release rollout pending; discover current host capabilities before execution. Read current owned job, assets, gaps and next action."},{"slug":"api-reference/complete/content/patch-content-packs-id","title":"PATCH /api/content/packs/{id}","description":"Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"PATCH","path":"/api/content/packs/{id}","spec":"content.json"},"searchText":"PATCH /api/content/packs/{id} Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes."},{"slug":"api-reference/complete/content/post-content-packs-id-estimate","title":"POST /api/content/packs/{id}/estimate","description":"Release rollout pending; discover current host capabilities before execution. Quote complete scope at existing house image/video rates. Caption, inspection and composition are included at no additional customer charge.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/estimate","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/estimate Release rollout pending; discover current host capabilities before execution. Quote complete scope at existing house image/video rates. Caption, inspection and composition are included at no additional customer charge."},{"slug":"api-reference/complete/content/post-content-packs-id-generate","title":"POST /api/content/packs/{id}/generate","description":"Release rollout pending; discover current host capabilities before execution. Approve the current quote and budget ceiling. Start or resume the same job without duplicate submission.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/generate","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/generate Release rollout pending; discover current host capabilities before execution. Approve the current quote and budget ceiling. Start or resume the same job without duplicate submission."},{"slug":"api-reference/complete/content/post-content-packs-id-retry","title":"POST /api/content/packs/{id}/retry","description":"Release rollout pending; discover current host capabilities before execution. Retry only the selected failed asset within approved scope and ceiling; retain successful work.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/retry","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/retry Release rollout pending; discover current host capabilities before execution. Retry only the selected failed asset within approved scope and ceiling; retain successful work."},{"slug":"api-reference/complete/content/post-content-packs-assets","title":"POST /api/content/packs/assets","description":"Release rollout pending; discover current host capabilities before execution. Upload explicitly selected audio or reference artwork to owned private storage; return a temporary locator.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/assets","spec":"content.json"},"searchText":"POST /api/content/packs/assets Release rollout pending; discover current host capabilities before execution. Upload explicitly selected audio or reference artwork to owned private storage; return a temporary locator."},{"slug":"api-reference/complete/content/get-content-packs-id-export","title":"GET /api/content/packs/{id}/export","description":"Release rollout pending; discover current host capabilities before execution. Retrieve an authenticated JSON manifest with captions, gaps and refreshed signed file URLs. Does not publish.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"GET","path":"/api/content/packs/{id}/export","spec":"content.json"},"searchText":"GET /api/content/packs/{id}/export Release rollout pending; discover current host capabilities before execution. Retrieve an authenticated JSON manifest with captions, gaps and refreshed signed file URLs. Does not publish."},{"slug":"api-reference/complete/players/get-players-public-id","title":"Read public player metadata without creating a session","description":"Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"GET","path":"/api/players/public/{id}","spec":"players.json"},"searchText":"GET /api/players/public/{id} Read public player metadata without creating a session Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials."},{"slug":"api-reference/complete/players/post-players-events","title":"Record reported listening","description":"Internal trusted Recoup player transport. Requires its Origin plus signed flow; browser-facing same-origin app proxy forwards to API. Provider and fan attribution come from the stored session. Event UUID makes retries idempotent, listenedMs is capped at 30 seconds and checked against elapsed server time. Recording failures do not stop music.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/events","spec":"players.json"},"searchText":"POST /api/players/events Record reported listening Internal trusted Recoup player transport. Requires its Origin plus signed flow; browser-facing same-origin app proxy forwards to API. Provider and fan attribution come from the stored session. Event UUID makes retries idempotent, listenedMs is capped at 30 seconds and checked against elapsed server time. Recording failures do not stop music."},{"slug":"api-reference/complete/players/post-players-spotify-session","title":"Exchange player Spotify authorization","description":"Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/spotify/session","spec":"players.json"},"searchText":"POST /api/players/spotify/session Exchange player Spotify authorization Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent."},{"slug":"api-reference/complete/players/post-players-public-id-session","title":"Acquire or resume a registered player session","description":"Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/public/{id}/session","spec":"players.json"},"searchText":"POST /api/players/public/{id}/session Acquire or resume a registered player session Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials."}] \ No newline at end of file +[{"slug":"","title":"Recoup API Documentation","description":"Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints.","category":"Quickstart","group":"Getting started","source":"index.mdx","body":"These guides cover the authenticated music-platform API. For anonymous search,\nreading, and website tools, use the separate [public website API](/public-website-api)\nand its [OpenAPI specification](https://recoupable.dev/openapi.json).\n\n## Connect your account\n\nFor an AI host, start with [MCP OAuth](/mcp-oauth): sign in to your real account,\napprove the intended scope and verify access with a read. For REST integrations,\ncreate an API key in your [account settings](https://chat.recoupable.dev/keys), or\nfollow the [verified email/PIN flow](/agents). Keep credentials in a secret facility.\nAn empty roster can be valid; do not create a disposable account to recover access.\n\n## What is Recoup?\n\nRecoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.\n\nThis is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.\n\n## Platform base URL\n\nPlatform API requests should be made to:\n\n```bash\nhttps://api.recoupable.dev/api\n```\n\n## Authentication\n\nMost API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key.\n\n1. Navigate to the [API Keys Management Page](https://chat.recoupable.dev/keys)\n2. Sign in with your account\n3. Create a new API key and copy it immediately (it's only shown once)\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/artists?accountId=YOUR_ACCOUNT_ID\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n\nKeep your API key secure. Do not share it publicly or commit it to version control.\n\n\n## Get Started\n\n\n \n Verify your email and obtain a separate REST API key.\n \n \n Get your API key and make your first request in minutes.\n \n \n Install and use the Recoup CLI to interact with the platform from your terminal.\n \n \n Connect Claude to Recoup through MCP OAuth, then add optional workflow skills.\n \n \n Connect Recoup to AI assistants via the Model Context Protocol.\n \n\n\n## API Sections\n\nThe API includes these major sections. Use these links to jump to the right area.\n\n\n \n Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements.\n \n \n Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.\n \n \n Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.\n \n \n Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.\n \n \n Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.\n \n \n Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools.\n \n \n Hosted listening pages, embeddable players, event reporting and fan connections.\n \n\n\n## Agents\n\n\n \n Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.\n \n \n API key authentication, account-scoped access, and organization-level permissions.\n \n\n\n## Quick Reference for LLMs\n\nIf you are an LLM navigating these docs, here is a summary of the endpoint structure:\n\n- **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile)\n- **`/api/research/*`** — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits.\n- **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)\n- **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact)\n- **Songs and catalogs** — Read songs with `/api/songs`; import songs into an accessible catalog with `/api/catalogs/songs`. Analysis, catalog management and catalog-song reads/deletes have their own references. [Standalone song creation is not available](/api-reference/songs/create).\n- **`/api/tasks/*`** — Task automation (get, create, update, delete, runs)\n- **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album)\n- **`/api/instagram/*`** — Instagram (comments, profiles)\n- **`/api/x/*`** — X/Twitter (search, trends)\n- **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect)\n- **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist)\n- **`/api/organizations/*`** — Organizations (list, create, add-artist)\n- **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload)\n- **`/api/players/*`** — Release Players (list, create, update, activity and fans)\n- **`/api/content-agent/*`** — Content agent webhooks (webhook, callback)\n- **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required\n\nBase URL: `https://api.recoupable.dev/api`\n\n[OpenAPI Specification](https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi)\n\n## Need Help?\n\n\n Reach out to our team at agent@recoupable.dev for assistance with the Recoup API.\n\n","headings":[{"title":"Connect your account","id":"connect-your-account"},{"title":"What is Recoup?","id":"what-is-recoup"},{"title":"Platform base URL","id":"platform-base-url"},{"title":"Authentication","id":"authentication"},{"title":"Get Started","id":"get-started"},{"title":"API Sections","id":"api-sections"},{"title":"Agents","id":"agents"},{"title":"Quick Reference for LLMs","id":"quick-reference-for-llms"},{"title":"Need Help?","id":"need-help"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n }, {Card, CardGroup, Warning} = _components;\n if (!Card) _missingMdxReference(\"Card\", true);\n if (!CardGroup) _missingMdxReference(\"CardGroup\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"These guides cover the authenticated music-platform API. For anonymous search,\\nreading, and website tools, use the separate \", _jsx(_components.a, {\n href: \"/public-website-api\",\n children: \"public website API\"\n }), \"\\nand its \", _jsx(_components.a, {\n href: \"https://recoupable.dev/openapi.json\",\n children: \"OpenAPI specification\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"connect-your-account\",\n children: \"Connect your account\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For an AI host, start with \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \": sign in to your real account,\\napprove the intended scope and verify access with a read. For REST integrations,\\ncreate an API key in your \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"account settings\"\n }), \", or\\nfollow the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"verified email/PIN flow\"\n }), \". Keep credentials in a secret facility.\\nAn empty roster can be valid; do not create a disposable account to recover access.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-is-recoup\",\n children: \"What is Recoup?\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"platform-base-url\",\n children: \"Platform base URL\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Platform API requests should be made to:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"https://api.recoupable.dev/api\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication\",\n children: \"Authentication\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Most API endpoints are authenticated using an API key passed in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header. The only exceptions are the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"agent onboarding\"\n }), \" endpoints — \", _jsx(_components.a, {\n href: \"/api-reference/agents/signup\",\n children: _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/agents/verify\",\n children: _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n })\n }), \" — which are intentionally unauthenticated so agents can obtain their first API key.\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys Management Page\"\n })]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Sign in with your account\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Create a new API key and copy it immediately (it's only shown once)\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/artists?accountId=YOUR_ACCOUNT_ID\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Keep your API key secure. Do not share it publicly or commit it to version control.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"get-started\",\n children: \"Get Started\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Agent Signup\",\n icon: \"user-plus\",\n href: \"/agents\",\n children: _jsx(_components.p, {\n children: \"Verify your email and obtain a separate REST API key.\"\n })\n }), _jsx(Card, {\n title: \"Quickstart\",\n icon: \"rocket\",\n href: \"/quickstart\",\n children: _jsx(_components.p, {\n children: \"Get your API key and make your first request in minutes.\"\n })\n }), _jsx(Card, {\n title: \"CLI\",\n icon: \"terminal\",\n href: \"/cli\",\n children: _jsx(_components.p, {\n children: \"Install and use the Recoup CLI to interact with the platform from your terminal.\"\n })\n }), _jsx(Card, {\n title: \"Claude\",\n icon: \"sparkles\",\n href: \"/claude\",\n children: _jsx(_components.p, {\n children: \"Connect Claude to Recoup through MCP OAuth, then add optional workflow skills.\"\n })\n }), _jsx(Card, {\n title: \"MCP Server\",\n icon: \"plug\",\n href: \"/mcp\",\n children: _jsx(_components.p, {\n children: \"Connect Recoup to AI assistants via the Model Context Protocol.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"api-sections\",\n children: \"API Sections\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The API includes these major sections. Use these links to jump to the right area.\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Research\",\n icon: \"magnifying-glass-chart\",\n href: \"/api-reference/research/search\",\n children: _jsx(_components.p, {\n children: \"Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements.\"\n })\n }), _jsx(Card, {\n title: \"Content Creation\",\n icon: \"wand-magic-sparkles\",\n href: \"/api-reference/content/create\",\n children: _jsx(_components.p, {\n children: \"Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.\"\n })\n }), _jsx(Card, {\n title: \"Chat\",\n icon: \"comments\",\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.p, {\n children: \"Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.\"\n })\n }), _jsx(Card, {\n title: \"Social Media\",\n icon: \"share-nodes\",\n href: \"/api-reference/connectors/list\",\n children: _jsx(_components.p, {\n children: \"Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.\"\n })\n }), _jsx(Card, {\n title: \"Releases\",\n icon: \"music\",\n href: \"/api-reference/songs/songs\",\n children: _jsx(_components.p, {\n children: \"Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.\"\n })\n }), _jsx(Card, {\n title: \"Accounts\",\n icon: \"building\",\n href: \"/api-reference/pulses/update\",\n children: _jsx(_components.p, {\n children: \"Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools.\"\n })\n }), _jsx(Card, {\n title: \"Release Players\",\n icon: \"play\",\n href: \"/essentials/release-player\",\n children: _jsx(_components.p, {\n children: \"Hosted listening pages, embeddable players, event reporting and fan connections.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"agents\",\n children: \"Agents\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Content Agent\",\n icon: \"robot\",\n href: \"/content-agent\",\n children: _jsx(_components.p, {\n children: \"Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.\"\n })\n }), _jsx(Card, {\n title: \"Authentication\",\n icon: \"key\",\n href: \"/authentication\",\n children: _jsx(_components.p, {\n children: \"API key authentication, account-scoped access, and organization-level permissions.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"quick-reference-for-llms\",\n children: \"Quick Reference for LLMs\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you are an LLM navigating these docs, here is a summary of the endpoint structure:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/artists/*\"\n })\n }), \" — Artist management (list, create, socials, socials-scrape, profile)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/research/*\"\n })\n }), \" — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/content/*\"\n })\n }), \" — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/chat/*\"\n })\n }), \" — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Songs and catalogs\"\n }), \" — Read songs with \", _jsx(_components.code, {\n children: \"/api/songs\"\n }), \"; import songs into an accessible catalog with \", _jsx(_components.code, {\n children: \"/api/catalogs/songs\"\n }), \". Analysis, catalog management and catalog-song reads/deletes have their own references. \", _jsx(_components.a, {\n href: \"/api-reference/songs/create\",\n children: \"Standalone song creation is not available\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/tasks/*\"\n })\n }), \" — Task automation (get, create, update, delete, runs)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/spotify/*\"\n })\n }), \" — Spotify (search, artist, artist-albums, artist-top-tracks, album)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/instagram/*\"\n })\n }), \" — Instagram (comments, profiles)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/x/*\"\n })\n }), \" — X/Twitter (search, trends)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/connectors/*\"\n })\n }), \" — OAuth connectors (list, authorize, disconnect)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/accounts/*\"\n })\n }), \" — Accounts (get, id, create, update, add-artist)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/organizations/*\"\n })\n }), \" — Organizations (list, create, add-artist)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/sandboxes/*\"\n })\n }), \" — Sandboxes (list, create, snapshot, delete, setup, file, upload)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/players/*\"\n })\n }), \" — Release Players (list, create, update, activity and fans)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/content-agent/*\"\n })\n }), \" — Content agent webhooks (webhook, callback)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/agents/*\"\n })\n }), \" — Agent onboarding (signup, verify) — no auth required\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Base URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/api\"\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi\",\n children: \"OpenAPI Specification\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"need-help\",\n children: \"Need Help?\"\n }), \"\\n\", _jsx(Card, {\n title: \"Contact Support\",\n icon: \"envelope\",\n href: \"mailto:agent@recoupable.dev\",\n children: _jsxs(_components.p, {\n children: [\"Reach out to our team at \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \" for assistance with the Recoup API.\"]\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Recoup API Documentation Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints. Quickstart Getting started These guides cover the authenticated music-platform API. For anonymous search, reading, and website tools, use the separate [public website API](/public-website-api) and its [OpenAPI specification](https://recoupable.dev/openapi.json). ## Connect your account For an AI host, start with [MCP OAuth](/mcp-oauth): sign in to your real account, approve the intended scope and verify access with a read. For REST integrations, create an API key in your [account settings](https://chat.recoupable.dev/keys), or follow the [verified email/PIN flow](/agents). Keep credentials in a secret facility. An empty roster can be valid; do not create a disposable account to recover access. ## What is Recoup? Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools. This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. ## Platform base URL Platform API requests should be made to: ## Authentication Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key. 1. Navigate to the [API Keys Management Page](https://chat.recoupable.dev/keys) 2. Sign in with your account 3. Create a new API key and copy it immediately (it's only shown once) Keep your API key secure. Do not share it publicly or commit it to version control. ## Get Started Verify your email and obtain a separate REST API key. Get your API key and make your first request in minutes. Install and use the Recoup CLI to interact with the platform from your terminal. Connect Claude to Recoup through MCP OAuth, then add optional workflow skills. Connect Recoup to AI assistants via the Model Context Protocol. ## API Sections The API includes these major sections. Use these links to jump to the right area. Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements. Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs. Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history. Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors. Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation. Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools. Hosted listening pages, embeddable players, event reporting and fan connections. ## Agents Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically. API key authentication, account-scoped access, and organization-level permissions. ## Quick Reference for LLMs If you are an LLM navigating these docs, here is a summary of the endpoint structure: - **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile) - **`/api/research/*`** — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits. - **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate) - **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact) - **Songs and catalogs** — Read songs with `/api/songs`; import songs into an accessible catalog with `/api/catalogs/songs`. Analysis, catalog management and catalog-song reads/deletes have their own references. [Standalone song creation is not available](/api-reference/songs/create). - **`/api/tasks/*`** — Task automation (get, create, update, delete, runs) - **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album) - **`/api/instagram/*`** — Instagram (comments, profiles) - **`/api/x/*`** — X/Twitter (search, trends) - **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect) - **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist) - **`/api/organizations/*`** — Organizations (list, create, add-artist) - **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload) - **`/api/players/*`** — Release Players (list, create, update, activity and fans) - **`/api/content-agent/*`** — Content agent webhooks (webhook, callback) - **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required Base URL: `https://api.recoupable.dev/api` [OpenAPI Specification](https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi) ## Need Help? Reach out to our team at agent@recoupable.dev for assistance with the Recoup API. "},{"slug":"quickstart","title":"Quickstart","description":"Connect your real account and make your first authenticated request.","category":"Quickstart","group":"Getting started","source":"quickstart.mdx","body":"## Connect first\n\nUse [MCP OAuth](/mcp-oauth) for a supported AI host. For the REST examples below,\ncreate a personal API key in [account settings](https://chat.recoupable.dev/keys)\nor follow the [Agents email verification guide](/agents). Store the key as\n`RECOUP_API_KEY` through your secret facility or an approved environment file.\nNever paste credentials into agent instructions or create a disposable account\nto access an existing customer's data.\n\nVerify the REST credential before continuing:\n\n```bash\ncurl --fail-with-body -sS -H \"x-api-key: $RECOUP_API_KEY\" \\\n https://api.recoupable.dev/api/accounts/id\n```\n\n## Base URL\n\nFor a language client, use the [Recoup SDK guide](/sdks). It includes the\npublished Go package, Python source installation, and the Node CLI.\n\nAll API requests should be made to:\n\n```bash\nhttps://api.recoupable.dev/api\n```\n\n## Your First Request\n\nOnce you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks:\n\n\n\n```bash cURL\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n```python Python\nimport requests\n\nheaders = {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\"\n}\n\nresponse = requests.get(\n \"https://api.recoupable.dev/api/tasks\",\n headers=headers\n)\nprint(response.json())\n```\n\n```javascript JavaScript\nconst response = await fetch(\"https://api.recoupable.dev/api/tasks\", {\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\",\n },\n});\nconst data = await response.json();\nconsole.log(data);\n```\n\n```typescript TypeScript\ninterface Task {\n id: string;\n title: string;\n prompt: string;\n schedule: string;\n account_id: string;\n artist_account_id: string;\n enabled: boolean;\n}\n\ninterface TasksResponse {\n status: \"success\" | \"error\";\n tasks: Task[];\n}\n\nconst response = await fetch(\"https://api.recoupable.dev/api/tasks\", {\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\",\n },\n});\nconst data: TasksResponse = await response.json();\nconsole.log(data.tasks);\n```\n\n\n\n**Example Response:**\n\n```json\n{\n \"status\": \"success\",\n \"tasks\": [\n {\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"title\": \"Daily Fan Report\",\n \"prompt\": \"Generate a summary of new fans from the past 24 hours\",\n \"schedule\": \"0 9 * * *\",\n \"account_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"artist_account_id\": \"987fcdeb-51a2-3b4c-d5e6-789012345678\",\n \"enabled\": true\n }\n ]\n}\n```\n\n\nFor full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get).\n\n\n## Prefer the dashboard?\n\nIf you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:\n\n1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.dev/keys)\n2. Sign in with your account\n3. Enter a descriptive name (e.g. \"Production Server\")\n4. Click **Create API Key**\n\n\nCopy and securely store your API key immediately — it will only be shown once.\n\n\n## Next Steps\n\nWith your API key ready, you can now:\n\n\n \n Fetch artists' social accounts and follower counts.\n \n \n Access fan data across all connected social platforms.\n \n \n Build AI-powered conversations with artist context.\n \n \n Schedule and automate recurring tasks.\n \n\n\n## Support\n\nIf you need help or have questions about the API, please contact our support team at [agent@recoupable.dev](mailto:agent@recoupable.dev).\n","headings":[{"title":"Connect first","id":"connect-first"},{"title":"Base URL","id":"base-url"},{"title":"Your First Request","id":"your-first-request"},{"title":"Prefer the dashboard?","id":"prefer-the-dashboard"},{"title":"Next Steps","id":"next-steps"},{"title":"Support","id":"support"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ...props.components\n }, {Card, CardGroup, CodeGroup, Info, Warning} = _components;\n if (!Card) _missingMdxReference(\"Card\", true);\n if (!CardGroup) _missingMdxReference(\"CardGroup\", true);\n if (!CodeGroup) _missingMdxReference(\"CodeGroup\", true);\n if (!Info) _missingMdxReference(\"Info\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"connect-first\",\n children: \"Connect first\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for a supported AI host. For the REST examples below,\\ncreate a personal API key in \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"account settings\"\n }), \"\\nor follow the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents email verification guide\"\n }), \". Store the key as\\n\", _jsx(_components.code, {\n children: \"RECOUP_API_KEY\"\n }), \" through your secret facility or an approved environment file.\\nNever paste credentials into agent instructions or create a disposable account\\nto access an existing customer's data.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Verify the REST credential before continuing:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl --fail-with-body -sS -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n https://api.recoupable.dev/api/accounts/id\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"base-url\",\n children: \"Base URL\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a language client, use the \", _jsx(_components.a, {\n href: \"/sdks\",\n children: \"Recoup SDK guide\"\n }), \". It includes the\\npublished Go package, Python source installation, and the Node CLI.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"All API requests should be made to:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"https://api.recoupable.dev/api\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"your-first-request\",\n children: \"Your First Request\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once you have an API key, include it in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header on every request. Here's a simple call that retrieves your scheduled tasks:\"]\n }), \"\\n\", _jsxs(CodeGroup, {\n children: [_jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-python\",\n children: \"import requests\\n\\nheaders = {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\"\\n}\\n\\nresponse = requests.get(\\n \\\"https://api.recoupable.dev/api/tasks\\\",\\n headers=headers\\n)\\nprint(response.json())\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-javascript\",\n children: \"const response = await fetch(\\\"https://api.recoupable.dev/api/tasks\\\", {\\n headers: {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\",\\n },\\n});\\nconst data = await response.json();\\nconsole.log(data);\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-typescript\",\n children: \"interface Task {\\n id: string;\\n title: string;\\n prompt: string;\\n schedule: string;\\n account_id: string;\\n artist_account_id: string;\\n enabled: boolean;\\n}\\n\\ninterface TasksResponse {\\n status: \\\"success\\\" | \\\"error\\\";\\n tasks: Task[];\\n}\\n\\nconst response = await fetch(\\\"https://api.recoupable.dev/api/tasks\\\", {\\n headers: {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\",\\n },\\n});\\nconst data: TasksResponse = await response.json();\\nconsole.log(data.tasks);\\n\"\n })\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"Example Response:\"\n })\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"status\\\": \\\"success\\\",\\n \\\"tasks\\\": [\\n {\\n \\\"id\\\": \\\"550e8400-e29b-41d4-a716-446655440000\\\",\\n \\\"title\\\": \\\"Daily Fan Report\\\",\\n \\\"prompt\\\": \\\"Generate a summary of new fans from the past 24 hours\\\",\\n \\\"schedule\\\": \\\"0 9 * * *\\\",\\n \\\"account_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\\n \\\"artist_account_id\\\": \\\"987fcdeb-51a2-3b4c-d5e6-789012345678\\\",\\n \\\"enabled\\\": true\\n }\\n ]\\n}\\n\"\n })\n }), \"\\n\", _jsx(Info, {\n children: _jsxs(_components.p, {\n children: [\"For full documentation on the Tasks API including filtering options, see the \", _jsx(_components.a, {\n href: \"/api-reference/tasks/get\",\n children: \"Tasks API Reference\"\n }), \".\"]\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"prefer-the-dashboard\",\n children: \"Prefer the dashboard?\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"Recoup API Keys Management Page\"\n })]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Sign in with your account\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Enter a descriptive name (e.g. \\\"Production Server\\\")\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Click \", _jsx(_components.strong, {\n children: \"Create API Key\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Copy and securely store your API key immediately — it will only be shown once.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"next-steps\",\n children: \"Next Steps\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"With your API key ready, you can now:\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Artist Data\",\n icon: \"user\",\n href: \"/api-reference/artists/socials\",\n children: _jsx(_components.p, {\n children: \"Fetch artists' social accounts and follower counts.\"\n })\n }), _jsx(Card, {\n title: \"Fan Analytics\",\n icon: \"users\",\n href: \"/api-reference/fans/get\",\n children: _jsx(_components.p, {\n children: \"Access fan data across all connected social platforms.\"\n })\n }), _jsx(Card, {\n title: \"Chat API\",\n icon: \"comments\",\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.p, {\n children: \"Build AI-powered conversations with artist context.\"\n })\n }), _jsx(Card, {\n title: \"Task Management\",\n icon: \"list-check\",\n href: \"/api-reference/tasks/get\",\n children: _jsx(_components.p, {\n children: \"Schedule and automate recurring tasks.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"support\",\n children: \"Support\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you need help or have questions about the API, please contact our support team at \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Quickstart Connect your real account and make your first authenticated request. Quickstart Getting started ## Connect first Use [MCP OAuth](/mcp-oauth) for a supported AI host. For the REST examples below, create a personal API key in [account settings](https://chat.recoupable.dev/keys) or follow the [Agents email verification guide](/agents). Store the key as `RECOUP_API_KEY` through your secret facility or an approved environment file. Never paste credentials into agent instructions or create a disposable account to access an existing customer's data. Verify the REST credential before continuing: ## Base URL For a language client, use the [Recoup SDK guide](/sdks). It includes the published Go package, Python source installation, and the Node CLI. All API requests should be made to: ## Your First Request Once you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks: **Example Response:** For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). ## Prefer the dashboard? If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint: 1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.dev/keys) 2. Sign in with your account 3. Enter a descriptive name (e.g. \"Production Server\") 4. Click **Create API Key** Copy and securely store your API key immediately — it will only be shown once. ## Next Steps With your API key ready, you can now: Fetch artists' social accounts and follower counts. Access fan data across all connected social platforms. Build AI-powered conversations with artist context. Schedule and automate recurring tasks. ## Support If you need help or have questions about the API, please contact our support team at [agent@recoupable.dev](mailto:agent@recoupable.dev). "},{"slug":"sdks","title":"Recoup SDKs: Go and Python clients for the music API","description":"Install the official Recoup Python SDK from PyPI, the Go SDK from its module registry, and the Node CLI from npm. Includes authentication, response handling, and package links.","category":"Quickstart","group":"Getting started","source":"sdks.mdx","body":"Use the official Recoup clients to call the platform's JSON API from your application.\nBoth SDKs support an API key or an existing Bearer token, bounded responses,\nstructured HTTP errors, and an account-identity helper. Their licenses are MIT.\n\n## Packages\n\n| Language | Package | Availability |\n| --- | --- | --- |\n| Go 1.23+ | [github.com/recoupable/marketing/sdk/go](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) | Version `v0.1.0` is published and indexed. |\n| Python 3.10+ | [recoupable on PyPI](https://pypi.org/project/recoupable/0.1.0/) | Version `0.1.0` is published. |\n| Node.js CLI | [@recoupable/cli on npm](https://www.npmjs.com/package/@recoupable/cli) | The terminal client is published. See the [CLI guide](/cli) for supported commands. |\n\nThe Go and Python SDKs handle JSON endpoints. They do not implement streaming,\nmultipart uploads, OAuth login, automatic pagination, or generated methods for\nevery endpoint. Use each endpoint's reference to check its availability, required\npermissions, request shape, and response type. A package installation does not\ngrant account access.\n\n## Go\n\nInstall the published version:\n\n```sh\ngo get github.com/recoupable/marketing/sdk/go@v0.1.0\n```\n\nRead an existing API key from your application's secret environment:\n\n```go\npackage main\n\nimport (\n \"context\"\n \"log\"\n \"os\"\n\n recoupable \"github.com/recoupable/marketing/sdk/go\"\n)\n\nfunc main() {\n client, err := recoupable.New(recoupable.Options{\n APIKey: os.Getenv(\"RECOUP_API_KEY\"),\n })\n if err != nil { log.Fatal(err) }\n account, err := client.GetAccountID(context.Background())\n if err != nil { log.Fatal(err) }\n log.Print(account.AccountID)\n}\n```\n\nUse `Options{AccessToken: ...}` for an existing Bearer token. The generic\n`Request(ctx, method, path, query, body, out)` method supports other documented\nJSON endpoints. Pass query parameters as `url.Values` and an unencoded `/api/` path.\nSee the [Go package reference](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0)\nfor method signatures and error types.\n\n## Python\n\nInstall the published version:\n\n```sh\npython -m pip install recoupable==0.1.0\n```\n\n```python\nimport os\nfrom recoupable import Client\n\nclient = Client(api_key=os.environ[\"RECOUP_API_KEY\"])\naccount = client.get_account_id()\nprint(account[\"accountId\"])\n```\n\nUse `Client(access_token=...)` for an existing Bearer token. The generic\n`request(method, path, query=..., body=...)` method returns decoded JSON or `None`\nfor an empty successful response. Read the [Python client reference](https://github.com/recoupable/marketing/tree/main/sdk/python)\nfor configuration and error handling.\n\n## Authentication and response handling\n\nSupply exactly one credential. Create a key in [Recoup account settings](https://chat.recoupable.dev/keys),\nor follow the [authentication guide](/authentication) for supported access methods.\nThe default API origin is `https://api.recoupable.dev`. A custom HTTPS origin is\nan explicit destination for your credential. Redirects are not followed.\n\nBoth clients cap responses at 16 MiB by default and accept empty successful\nresponses. Python uses a 30-second timeout per blocking socket operation; Go\nuses a 30-second total request deadline and supports earlier context deadlines.\nThese limits are configurable.\n\nHTTP errors retain their status and headers, including `Retry-After`; oversized\nerror bodies are truncated. Inspect the error's fields when deciding what to do.\nError messages omit credentials and response bodies. Treat a response body as\npotentially private if you log it.\n\nThe SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent\nrequest on a reused connection. A transport failure can occur after a write has\ncompleted; check the operation's outcome before repeating it.\n","headings":[{"title":"Packages","id":"packages"},{"title":"Go","id":"go"},{"title":"Python","id":"python"},{"title":"Authentication and response handling","id":"authentication-and-response-handling"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Use the official Recoup clients to call the platform's JSON API from your application.\\nBoth SDKs support an API key or an existing Bearer token, bounded responses,\\nstructured HTTP errors, and an account-identity helper. Their licenses are MIT.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"packages\",\n children: \"Packages\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Language\"\n }), _jsx(_components.th, {\n children: \"Package\"\n }), _jsx(_components.th, {\n children: \"Availability\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Go 1.23+\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0\",\n children: \"github.com/recoupable/marketing/sdk/go\"\n })\n }), _jsxs(_components.td, {\n children: [\"Version \", _jsx(_components.code, {\n children: \"v0.1.0\"\n }), \" is published and indexed.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Python 3.10+\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://pypi.org/project/recoupable/0.1.0/\",\n children: \"recoupable on PyPI\"\n })\n }), _jsxs(_components.td, {\n children: [\"Version \", _jsx(_components.code, {\n children: \"0.1.0\"\n }), \" is published.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Node.js CLI\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://www.npmjs.com/package/@recoupable/cli\",\n children: \"@recoupable/cli on npm\"\n })\n }), _jsxs(_components.td, {\n children: [\"The terminal client is published. See the \", _jsx(_components.a, {\n href: \"/cli\",\n children: \"CLI guide\"\n }), \" for supported commands.\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The Go and Python SDKs handle JSON endpoints. They do not implement streaming,\\nmultipart uploads, OAuth login, automatic pagination, or generated methods for\\nevery endpoint. Use each endpoint's reference to check its availability, required\\npermissions, request shape, and response type. A package installation does not\\ngrant account access.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"go\",\n children: \"Go\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Install the published version:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-sh\",\n children: \"go get github.com/recoupable/marketing/sdk/go@v0.1.0\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Read an existing API key from your application's secret environment:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-go\",\n children: \"package main\\n\\nimport (\\n \\\"context\\\"\\n \\\"log\\\"\\n \\\"os\\\"\\n\\n recoupable \\\"github.com/recoupable/marketing/sdk/go\\\"\\n)\\n\\nfunc main() {\\n client, err := recoupable.New(recoupable.Options{\\n APIKey: os.Getenv(\\\"RECOUP_API_KEY\\\"),\\n })\\n if err != nil { log.Fatal(err) }\\n account, err := client.GetAccountID(context.Background())\\n if err != nil { log.Fatal(err) }\\n log.Print(account.AccountID)\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"Options{AccessToken: ...}\"\n }), \" for an existing Bearer token. The generic\\n\", _jsx(_components.code, {\n children: \"Request(ctx, method, path, query, body, out)\"\n }), \" method supports other documented\\nJSON endpoints. Pass query parameters as \", _jsx(_components.code, {\n children: \"url.Values\"\n }), \" and an unencoded \", _jsx(_components.code, {\n children: \"/api/\"\n }), \" path.\\nSee the \", _jsx(_components.a, {\n href: \"https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0\",\n children: \"Go package reference\"\n }), \"\\nfor method signatures and error types.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"python\",\n children: \"Python\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Install the published version:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-sh\",\n children: \"python -m pip install recoupable==0.1.0\\n\"\n })\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-python\",\n children: \"import os\\nfrom recoupable import Client\\n\\nclient = Client(api_key=os.environ[\\\"RECOUP_API_KEY\\\"])\\naccount = client.get_account_id()\\nprint(account[\\\"accountId\\\"])\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"Client(access_token=...)\"\n }), \" for an existing Bearer token. The generic\\n\", _jsx(_components.code, {\n children: \"request(method, path, query=..., body=...)\"\n }), \" method returns decoded JSON or \", _jsx(_components.code, {\n children: \"None\"\n }), \"\\nfor an empty successful response. Read the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketing/tree/main/sdk/python\",\n children: \"Python client reference\"\n }), \"\\nfor configuration and error handling.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication-and-response-handling\",\n children: \"Authentication and response handling\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Supply exactly one credential. Create a key in \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"Recoup account settings\"\n }), \",\\nor follow the \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"authentication guide\"\n }), \" for supported access methods.\\nThe default API origin is \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \". A custom HTTPS origin is\\nan explicit destination for your credential. Redirects are not followed.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Both clients cap responses at 16 MiB by default and accept empty successful\\nresponses. Python uses a 30-second timeout per blocking socket operation; Go\\nuses a 30-second total request deadline and supports earlier context deadlines.\\nThese limits are configurable.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP errors retain their status and headers, including \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \"; oversized\\nerror bodies are truncated. Inspect the error's fields when deciding what to do.\\nError messages omit credentials and response bodies. Treat a response body as\\npotentially private if you log it.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent\\nrequest on a reused connection. A transport failure can occur after a write has\\ncompleted; check the operation's outcome before repeating it.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Recoup SDKs: Go and Python clients for the music API Install the official Recoup Python SDK from PyPI, the Go SDK from its module registry, and the Node CLI from npm. Includes authentication, response handling, and package links. Quickstart Getting started Use the official Recoup clients to call the platform's JSON API from your application. Both SDKs support an API key or an existing Bearer token, bounded responses, structured HTTP errors, and an account-identity helper. Their licenses are MIT. ## Packages | Language | Package | Availability | | --- | --- | --- | | Go 1.23+ | [github.com/recoupable/marketing/sdk/go](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) | Version `v0.1.0` is published and indexed. | | Python 3.10+ | [recoupable on PyPI](https://pypi.org/project/recoupable/0.1.0/) | Version `0.1.0` is published. | | Node.js CLI | [@recoupable/cli on npm](https://www.npmjs.com/package/@recoupable/cli) | The terminal client is published. See the [CLI guide](/cli) for supported commands. | The Go and Python SDKs handle JSON endpoints. They do not implement streaming, multipart uploads, OAuth login, automatic pagination, or generated methods for every endpoint. Use each endpoint's reference to check its availability, required permissions, request shape, and response type. A package installation does not grant account access. ## Go Install the published version: Read an existing API key from your application's secret environment: Use `Options{AccessToken: ...}` for an existing Bearer token. The generic `Request(ctx, method, path, query, body, out)` method supports other documented JSON endpoints. Pass query parameters as `url.Values` and an unencoded `/api/` path. See the [Go package reference](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) for method signatures and error types. ## Python Install the published version: Use `Client(access_token=...)` for an existing Bearer token. The generic `request(method, path, query=..., body=...)` method returns decoded JSON or `None` for an empty successful response. Read the [Python client reference](https://github.com/recoupable/marketing/tree/main/sdk/python) for configuration and error handling. ## Authentication and response handling Supply exactly one credential. Create a key in [Recoup account settings](https://chat.recoupable.dev/keys), or follow the [authentication guide](/authentication) for supported access methods. The default API origin is `https://api.recoupable.dev`. A custom HTTPS origin is an explicit destination for your credential. Redirects are not followed. Both clients cap responses at 16 MiB by default and accept empty successful responses. Python uses a 30-second timeout per blocking socket operation; Go uses a 30-second total request deadline and supports earlier context deadlines. These limits are configurable. HTTP errors retain their status and headers, including `Retry-After`; oversized error bodies are truncated. Inspect the error's fields when deciding what to do. Error messages omit credentials and response bodies. Treat a response body as potentially private if you log it. The SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent request on a reused connection. A transport failure can occur after a write has completed; check the operation's outcome before repeating it. "},{"slug":"public-website-api","title":"Recoup public website API","description":"Search and read public Recoup content, use bounded website tools, and batch independent operations without an account.","category":"Quickstart","group":"Getting started","source":"public-website-api.mdx","body":"The public website API searches and reads published Recoup pages, calculates\nworkflow scenarios from supplied inputs, and prepares unsubmitted project briefs.\nIt is free and requires no account, API key, or payment method.\n\nMusic-platform operations use the separate authenticated\n[platform API](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot\nread account data, manage artists, publish content, or send an inquiry.\n\n## Specification and first request\n\nThe [website OpenAPI specification](https://recoupable.dev/openapi.json) defines\nevery HTTP operation, its input and response schemas, and typed errors.\nThe [API catalog](https://recoupable.dev/.well-known/api-catalog) links this\nspecification alongside the platform specifications.\n\n```bash\ncurl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'\n```\n\nThe response contains `results`, `total`, and `nextCursor`. An empty result list\nis a successful search. Use a returned content ID with\n`GET /agent-api/v1/read?id=CONTENT_ID`; continue at the returned `nextOffset`\nuntil it is null. The reader accepts registry IDs, never arbitrary private URLs.\n\nUse `GET /agent-api/v1/markdown?path=/blog` for a complete public page as Markdown.\nThe [website agent guide](https://recoupable.dev/agents.md) explains all five tools,\npagination, draft behavior, and the browser interface.\n\n## Batch independent operations\n\n`POST https://recoupable.dev/agent-api/v1/batch` accepts one to ten operations.\n\n```bash\ncurl 'https://recoupable.dev/agent-api/v1/batch' \\\n -H 'Content-Type: application/json' \\\n --data '{\"operations\":[{\"name\":\"search_recoup\",\"arguments\":{\"query\":\"royalty\",\"limit\":1}},{\"name\":\"read_recoup_page\",\"arguments\":{\"id\":\"page:/services\",\"maxLength\":500}}]}'\n```\n\nThe `results` array preserves input order. Each entry has its own `status` and\n`result` or `error`. An individual failure does not cancel successful reads.\nThe batch is not a transaction. Its entire request body must fit within 16 KB.\nDraft operations return `submitted: false`; nothing is sent or saved as a lead.\n\n## Hosted quotas and errors\n\nHTTP and MCP website tools share a limit of 120 requests per 60-second fixed\nwindow, per IP address and serving region. A batch counts as one request.\n`RateLimit-Limit` and `RateLimit-Policy` describe that enforced policy on live\nresponses. Regional counters are not a global account allowance.\n\nOn HTTP 429, wait the `Retry-After` duration before retrying. HTTP 503 means the\nrequest could not be completed; retry later. JSON tool endpoints return structured\nerrors with a code, message, and recovery guidance for invalid arguments or missing content.\nLocal development does not enforce the hosted quota.\n\n## Versioning and deprecation\n\nWebsite HTTP operations use `/agent-api/v1`. Additive response fields are\ncompatible; clients should ignore fields they do not recognize. Incompatible\nchanges require a new major URL version.\n\nNo v1 deprecation or sunset is scheduled. A future retirement will be announced\nin the [agent guide](https://recoupable.dev/agents.md) with a migration guide and\n`Deprecation`, `Sunset`, and `Link` response headers when dates are known.\nThis policy applies to the public website API.\n\n## MCP connection\n\nConnect to `https://recoupable.dev/mcp` over Streamable HTTP without credentials.\nThe [public manifest](https://recoupable.dev/.well-known/mcp.json) identifies\nthe server. Its five tools share the website HTTP capabilities and hosted quota.\nTo use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead.\n","headings":[{"title":"Specification and first request","id":"specification-and-first-request"},{"title":"Batch independent operations","id":"batch-independent-operations"},{"title":"Hosted quotas and errors","id":"hosted-quotas-and-errors"},{"title":"Versioning and deprecation","id":"versioning-and-deprecation"},{"title":"MCP connection","id":"mcp-connection"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"The public website API searches and reads published Recoup pages, calculates\\nworkflow scenarios from supplied inputs, and prepares unsubmitted project briefs.\\nIt is free and requires no account, API key, or payment method.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Music-platform operations use the separate authenticated\\n\", _jsx(_components.a, {\n href: \"/quickstart\",\n children: \"platform API\"\n }), \" and \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"platform MCP\"\n }), \". Website tools cannot\\nread account data, manage artists, publish content, or send an inquiry.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"specification-and-first-request\",\n children: \"Specification and first request\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"https://recoupable.dev/openapi.json\",\n children: \"website OpenAPI specification\"\n }), \" defines\\nevery HTTP operation, its input and response schemas, and typed errors.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/.well-known/api-catalog\",\n children: \"API catalog\"\n }), \" links this\\nspecification alongside the platform specifications.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response contains \", _jsx(_components.code, {\n children: \"results\"\n }), \", \", _jsx(_components.code, {\n children: \"total\"\n }), \", and \", _jsx(_components.code, {\n children: \"nextCursor\"\n }), \". An empty result list\\nis a successful search. Use a returned content ID with\\n\", _jsx(_components.code, {\n children: \"GET /agent-api/v1/read?id=CONTENT_ID\"\n }), \"; continue at the returned \", _jsx(_components.code, {\n children: \"nextOffset\"\n }), \"\\nuntil it is null. The reader accepts registry IDs, never arbitrary private URLs.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"GET /agent-api/v1/markdown?path=/blog\"\n }), \" for a complete public page as Markdown.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/agents.md\",\n children: \"website agent guide\"\n }), \" explains all five tools,\\npagination, draft behavior, and the browser interface.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"batch-independent-operations\",\n children: \"Batch independent operations\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST https://recoupable.dev/agent-api/v1/batch\"\n }), \" accepts one to ten operations.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl 'https://recoupable.dev/agent-api/v1/batch' \\\\\\n -H 'Content-Type: application/json' \\\\\\n --data '{\\\"operations\\\":[{\\\"name\\\":\\\"search_recoup\\\",\\\"arguments\\\":{\\\"query\\\":\\\"royalty\\\",\\\"limit\\\":1}},{\\\"name\\\":\\\"read_recoup_page\\\",\\\"arguments\\\":{\\\"id\\\":\\\"page:/services\\\",\\\"maxLength\\\":500}}]}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.code, {\n children: \"results\"\n }), \" array preserves input order. Each entry has its own \", _jsx(_components.code, {\n children: \"status\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"result\"\n }), \" or \", _jsx(_components.code, {\n children: \"error\"\n }), \". An individual failure does not cancel successful reads.\\nThe batch is not a transaction. Its entire request body must fit within 16 KB.\\nDraft operations return \", _jsx(_components.code, {\n children: \"submitted: false\"\n }), \"; nothing is sent or saved as a lead.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hosted-quotas-and-errors\",\n children: \"Hosted quotas and errors\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP and MCP website tools share a limit of 120 requests per 60-second fixed\\nwindow, per IP address and serving region. A batch counts as one request.\\n\", _jsx(_components.code, {\n children: \"RateLimit-Limit\"\n }), \" and \", _jsx(_components.code, {\n children: \"RateLimit-Policy\"\n }), \" describe that enforced policy on live\\nresponses. Regional counters are not a global account allowance.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"On HTTP 429, wait the \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" duration before retrying. HTTP 503 means the\\nrequest could not be completed; retry later. JSON tool endpoints return structured\\nerrors with a code, message, and recovery guidance for invalid arguments or missing content.\\nLocal development does not enforce the hosted quota.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"versioning-and-deprecation\",\n children: \"Versioning and deprecation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Website HTTP operations use \", _jsx(_components.code, {\n children: \"/agent-api/v1\"\n }), \". Additive response fields are\\ncompatible; clients should ignore fields they do not recognize. Incompatible\\nchanges require a new major URL version.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"No v1 deprecation or sunset is scheduled. A future retirement will be announced\\nin the \", _jsx(_components.a, {\n href: \"https://recoupable.dev/agents.md\",\n children: \"agent guide\"\n }), \" with a migration guide and\\n\", _jsx(_components.code, {\n children: \"Deprecation\"\n }), \", \", _jsx(_components.code, {\n children: \"Sunset\"\n }), \", and \", _jsx(_components.code, {\n children: \"Link\"\n }), \" response headers when dates are known.\\nThis policy applies to the public website API.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"mcp-connection\",\n children: \"MCP connection\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connect to \", _jsx(_components.code, {\n children: \"https://recoupable.dev/mcp\"\n }), \" over Streamable HTTP without credentials.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/.well-known/mcp.json\",\n children: \"public manifest\"\n }), \" identifies\\nthe server. Its five tools share the website HTTP capabilities and hosted quota.\\nTo use your music-platform account, follow \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" instead.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Recoup public website API Search and read public Recoup content, use bounded website tools, and batch independent operations without an account. Quickstart Getting started The public website API searches and reads published Recoup pages, calculates workflow scenarios from supplied inputs, and prepares unsubmitted project briefs. It is free and requires no account, API key, or payment method. Music-platform operations use the separate authenticated [platform API](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot read account data, manage artists, publish content, or send an inquiry. ## Specification and first request The [website OpenAPI specification](https://recoupable.dev/openapi.json) defines every HTTP operation, its input and response schemas, and typed errors. The [API catalog](https://recoupable.dev/.well-known/api-catalog) links this specification alongside the platform specifications. The response contains `results`, `total`, and `nextCursor`. An empty result list is a successful search. Use a returned content ID with `GET /agent-api/v1/read?id=CONTENT_ID`; continue at the returned `nextOffset` until it is null. The reader accepts registry IDs, never arbitrary private URLs. Use `GET /agent-api/v1/markdown?path=/blog` for a complete public page as Markdown. The [website agent guide](https://recoupable.dev/agents.md) explains all five tools, pagination, draft behavior, and the browser interface. ## Batch independent operations `POST https://recoupable.dev/agent-api/v1/batch` accepts one to ten operations. The `results` array preserves input order. Each entry has its own `status` and `result` or `error`. An individual failure does not cancel successful reads. The batch is not a transaction. Its entire request body must fit within 16 KB. Draft operations return `submitted: false`; nothing is sent or saved as a lead. ## Hosted quotas and errors HTTP and MCP website tools share a limit of 120 requests per 60-second fixed window, per IP address and serving region. A batch counts as one request. `RateLimit-Limit` and `RateLimit-Policy` describe that enforced policy on live responses. Regional counters are not a global account allowance. On HTTP 429, wait the `Retry-After` duration before retrying. HTTP 503 means the request could not be completed; retry later. JSON tool endpoints return structured errors with a code, message, and recovery guidance for invalid arguments or missing content. Local development does not enforce the hosted quota. ## Versioning and deprecation Website HTTP operations use `/agent-api/v1`. Additive response fields are compatible; clients should ignore fields they do not recognize. Incompatible changes require a new major URL version. No v1 deprecation or sunset is scheduled. A future retirement will be announced in the [agent guide](https://recoupable.dev/agents.md) with a migration guide and `Deprecation`, `Sunset`, and `Link` response headers when dates are known. This policy applies to the public website API. ## MCP connection Connect to `https://recoupable.dev/mcp` over Streamable HTTP without credentials. The [public manifest](https://recoupable.dev/.well-known/mcp.json) identifies the server. Its five tools share the website HTTP capabilities and hosted quota. To use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead. "},{"slug":"cli","title":"CLI","description":"Install the Recoup CLI and interact with the platform from your terminal.","category":"Quickstart","group":"Getting started","source":"cli.mdx","body":"The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.\n\n\n**The CLI is in beta.** The reference below follows the v0.1.15 source command set. Check `recoup --version` and `--help` for the package installed in your environment. For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up.\n\n**Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.\n\n\n## Install\n\n```bash\nnpm install -g @recoupable/cli\n```\n\n## Authenticate\n\nSet your API key as an environment variable:\n\n```bash\nexport RECOUP_API_KEY=your-api-key\n```\n\nVerify it works:\n\n```bash\nrecoup whoami\n```\n\n\nGet an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) for instant key generation.\n\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `RECOUP_API_KEY` | Yes | — | Your Recoup API key |\n| `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override; set `https://api.recoupable.dev` to use the canonical API domain |\n\nAll commands support `--json` for machine-readable output and `--help` for usage info.\n\n---\n\n## Commands\n\n### whoami\n\nShow the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id).\n\n```bash\nrecoup whoami\nrecoup whoami --json\n```\n\n### orgs\n\nList organizations. See [`GET /api/organizations`](/api-reference/organizations/list).\n\n```bash\nrecoup orgs list\nrecoup orgs list --account \n```\n\n### artists\n\nList artists. See [`GET /api/artists`](/api-reference/artists/list).\n\n```bash\nrecoup artists list\nrecoup artists list --org \nrecoup artists list --account \n```\n\n### emails\n\nSend an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create).\n\n```bash\nrecoup emails --subject \"Pulse Report\" --text \"Here's your weekly summary.\"\nrecoup emails --subject \"Update\" --html \"

Report

Details here.

\"\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--subject ` | No | Email subject line; defaults from the body when omitted |\n| `--text ` | No | Plain text or Markdown body |\n| `--html ` | No | Raw HTML body (takes precedence over `--text`) |\n| `--cc ` | No | CC recipient (repeatable) |\n| `--chat-id ` | No | Chat ID for a chat link in the email footer |\n| `--account ` | No | Send to a specific account (org keys only) |\n\n### chats\n\nManage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create).\n\n```bash\nrecoup chats list\nrecoup chats create --name \"My Topic\"\nrecoup chats create --name \"My Topic\" --artist \n```\n\n### sandboxes\n\nManage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create).\n\n```bash\nrecoup sandboxes list\nrecoup sandboxes create\nrecoup sandboxes create --command \"ls -la\"\n```\n\n### tasks\n\nCheck background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs).\n\n```bash\nrecoup tasks status --run \n```\n\n### songs\n\nRun AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets).\n\n```bash\nrecoup songs presets\nrecoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3\nrecoup songs analyze --prompt \"Describe the production style\" --audio https://example.com/track.mp3\n```\n\nExactly one of `--preset` or `--prompt` is required, together with `--audio`. The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API.\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. |\n| `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. |\n| `--audio ` | Yes | Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported. |\n| `--max-tokens ` | No | Max tokens to generate (default 512). |\n\n---\n\n## content\n\nContent creation pipeline — generate AI-powered social videos for artists.\n\n### List templates\n\n```bash\nrecoup content templates\n```\n\n### Validate an artist\n\nCheck that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate).\n\n```bash\nrecoup content validate --artist \n```\n\n### Estimate cost\n\nPreview estimated cost and duration before kicking off the pipeline. See [`GET /api/content/estimate`](/api-reference/content/estimate).\n\n```bash\nrecoup content estimate\nrecoup content estimate --lipsync --batch 2 --compare\n```\n\n### Create content\n\nRun the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create).\n\n```bash\nrecoup content create --artist \nrecoup content create --artist --template --lipsync --upscale\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--artist ` | Yes | Artist account ID |\n| `--template ` | No | Template name (default: random) |\n| `--lipsync` | No | Enable lipsync mode |\n| `--upscale` | No | Enable upscaling |\n| `--caption-length ` | No | Max caption length in characters |\n\n\nFor finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands.\n\n","headings":[{"title":"Install","id":"install"},{"title":"Authenticate","id":"authenticate"},{"title":"Configuration","id":"configuration"},{"title":"Commands","id":"commands"},{"title":"content","id":"content"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n }, {Note, Tip} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Tip) _missingMdxReference(\"Tip\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"The Recoup CLI (\", _jsx(_components.code, {\n children: \"@recoupable/cli\"\n }), \") wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.\"]\n }), \"\\n\", _jsxs(Note, {\n children: [_jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"The CLI is in beta.\"\n }), \" The reference below follows the v0.1.15 source command set. Check \", _jsx(_components.code, {\n children: \"recoup --version\"\n }), \" and \", _jsx(_components.code, {\n children: \"--help\"\n }), \" for the package installed in your environment. For research workflows and most content operations, call the \", _jsx(_components.a, {\n href: \"/api-reference\",\n children: \"REST API\"\n }), \" directly — the CLI is gradually catching up.\"]\n }), _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Agents:\"\n }), \" if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.\"]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"install\",\n children: \"Install\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"npm install -g @recoupable/cli\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authenticate\",\n children: \"Authenticate\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Set your API key as an environment variable:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"export RECOUP_API_KEY=your-api-key\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Verify it works:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup whoami\\n\"\n })\n }), \"\\n\", _jsx(Tip, {\n children: _jsxs(_components.p, {\n children: [\"Get an API key from the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys page\"\n }), \" or use the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"agent signup\"\n }), \" for instant key generation.\"]\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"configuration\",\n children: \"Configuration\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Variable\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Default\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"RECOUP_API_KEY\"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"—\"\n }), _jsx(_components.td, {\n children: \"Your Recoup API key\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"RECOUP_API_URL\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"https://recoup-api.vercel.app\"\n })\n }), _jsxs(_components.td, {\n children: [\"API base URL override; set \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \" to use the canonical API domain\"]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"All commands support \", _jsx(_components.code, {\n children: \"--json\"\n }), \" for machine-readable output and \", _jsx(_components.code, {\n children: \"--help\"\n }), \" for usage info.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"commands\",\n children: \"Commands\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"whoami\",\n children: \"whoami\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Show the authenticated account. See \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup whoami\\nrecoup whoami --json\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"orgs\",\n children: \"orgs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"List organizations. See \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/organizations\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup orgs list\\nrecoup orgs list --account \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"artists\",\n children: \"artists\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"List artists. See \", _jsx(_components.a, {\n href: \"/api-reference/artists/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/artists\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup artists list\\nrecoup artists list --org \\nrecoup artists list --account \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"emails\",\n children: \"emails\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send an email to the authenticated account. See \", _jsx(_components.a, {\n href: \"/api-reference/emails/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/emails\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup emails --subject \\\"Pulse Report\\\" --text \\\"Here's your weekly summary.\\\"\\nrecoup emails --subject \\\"Update\\\" --html \\\"

Report

Details here.

\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--subject \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Email subject line; defaults from the body when omitted\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--text \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Plain text or Markdown body\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--html \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsxs(_components.td, {\n children: [\"Raw HTML body (takes precedence over \", _jsx(_components.code, {\n children: \"--text\"\n }), \")\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--cc \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"CC recipient (repeatable)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--chat-id \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Chat ID for a chat link in the email footer\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--account \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Send to a specific account (org keys only)\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"chats\",\n children: \"chats\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Manage chats. See \", _jsx(_components.a, {\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.code, {\n children: \"GET /api/chats\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/chat/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/chats\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup chats list\\nrecoup chats create --name \\\"My Topic\\\"\\nrecoup chats create --name \\\"My Topic\\\" --artist \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"sandboxes\",\n children: \"sandboxes\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Manage sandboxes. See \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/sandboxes\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup sandboxes list\\nrecoup sandboxes create\\nrecoup sandboxes create --command \\\"ls -la\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"tasks\",\n children: \"tasks\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Check background task status. See \", _jsx(_components.a, {\n href: \"/api-reference/tasks/runs\",\n children: _jsx(_components.code, {\n children: \"GET /api/tasks/runs\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup tasks status --run \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"songs\",\n children: \"songs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Run AI music analysis. See \", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze-presets\",\n children: _jsx(_components.code, {\n children: \"GET /api/songs/analyze/presets\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup songs presets\\nrecoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3\\nrecoup songs analyze --prompt \\\"Describe the production style\\\" --audio https://example.com/track.mp3\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Exactly one of \", _jsx(_components.code, {\n children: \"--preset\"\n }), \" or \", _jsx(_components.code, {\n children: \"--prompt\"\n }), \" is required, together with \", _jsx(_components.code, {\n children: \"--audio\"\n }), \". The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--preset \"\n })\n }), _jsx(_components.td, {\n children: \"Conditional\"\n }), _jsxs(_components.td, {\n children: [\"Curated analysis preset. Required when \", _jsx(_components.code, {\n children: \"--prompt\"\n }), \" is omitted.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--prompt \"\n })\n }), _jsx(_components.td, {\n children: \"Conditional\"\n }), _jsxs(_components.td, {\n children: [\"Custom text prompt. Required when \", _jsx(_components.code, {\n children: \"--preset\"\n }), \" is omitted.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--audio \"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--max-tokens \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Max tokens to generate (default 512).\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"content\",\n children: \"content\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Content creation pipeline — generate AI-powered social videos for artists.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"list-templates\",\n children: \"List templates\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content templates\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"validate-an-artist\",\n children: \"Validate an artist\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Check that an artist has the required assets before creating content. See \", _jsx(_components.a, {\n href: \"/api-reference/content/validate\",\n children: _jsx(_components.code, {\n children: \"GET /api/content/validate\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content validate --artist \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"estimate-cost\",\n children: \"Estimate cost\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Preview estimated cost and duration before kicking off the pipeline. See \", _jsx(_components.a, {\n href: \"/api-reference/content/estimate\",\n children: _jsx(_components.code, {\n children: \"GET /api/content/estimate\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content estimate\\nrecoup content estimate --lipsync --batch 2 --compare\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"create-content\",\n children: \"Create content\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Run the full content-creation pipeline for an artist. See \", _jsx(_components.a, {\n href: \"/api-reference/content/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/content/create\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content create --artist \\nrecoup content create --artist --template --lipsync --upscale\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--artist \"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Artist account ID\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--template \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Template name (default: random)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--lipsync\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Enable lipsync mode\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--upscale\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Enable upscaling\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--caption-length \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Max caption length in characters\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(Tip, {\n children: _jsxs(_components.p, {\n children: [\"For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the \", _jsx(_components.a, {\n href: \"/api-reference/content/generate-image\",\n children: \"content REST endpoints\"\n }), \" directly. Those primitives aren't yet exposed as individual CLI subcommands.\"]\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"CLI Install the Recoup CLI and interact with the platform from your terminal. Quickstart Getting started The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments. **The CLI is in beta.** The reference below follows the v0.1.15 source command set. Check `recoup --version` and `--help` for the package installed in your environment. For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up. **Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command. ## Install ## Authenticate Set your API key as an environment variable: Verify it works: Get an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) for instant key generation. ## Configuration | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `RECOUP_API_KEY` | Yes | — | Your Recoup API key | | `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override; set `https://api.recoupable.dev` to use the canonical API domain | All commands support `--json` for machine-readable output and `--help` for usage info. --- ## Commands ### whoami Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id). ### orgs List organizations. See [`GET /api/organizations`](/api-reference/organizations/list). ### artists List artists. See [`GET /api/artists`](/api-reference/artists/list). ### emails Send an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create). | Flag | Required | Description | |------|----------|-------------| | `--subject ` | No | Email subject line; defaults from the body when omitted | | `--text ` | No | Plain text or Markdown body | | `--html ` | No | Raw HTML body (takes precedence over `--text`) | | `--cc ` | No | CC recipient (repeatable) | | `--chat-id ` | No | Chat ID for a chat link in the email footer | | `--account ` | No | Send to a specific account (org keys only) | ### chats Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create). ### sandboxes Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create). ### tasks Check background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs). ### songs Run AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets). Exactly one of `--preset` or `--prompt` is required, together with `--audio`. The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API. | Flag | Required | Description | |------|----------|-------------| | `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. | | `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. | | `--audio ` | Yes | Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported. | | `--max-tokens ` | No | Max tokens to generate (default 512). | --- ## content Content creation pipeline — generate AI-powered social videos for artists. ### List templates ### Validate an artist Check that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate). ### Estimate cost Preview estimated cost and duration before kicking off the pipeline. See [`GET /api/content/estimate`](/api-reference/content/estimate). ### Create content Run the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create). | Flag | Required | Description | |------|----------|-------------| | `--artist ` | Yes | Artist account ID | | `--template ` | No | Template name (default: random) | | `--lipsync` | No | Enable lipsync mode | | `--upscale` | No | Enable upscaling | | `--caption-length ` | No | Max caption length in characters | For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands. "},{"slug":"claude","title":"Claude","description":"Connect Claude to Recoup and install optional workflow instructions.","category":"Quickstart","group":"Getting started","source":"claude.mdx","body":"Add `https://api.recoupable.dev/mcp` in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See [MCP OAuth](/mcp-oauth) for the dated client verification record and troubleshooting.\n\nAfter connecting, refresh tools and call the discovered `list_artists` tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account.\n\nFor workflow instructions, install the consolidated Recoup package from the [Recoup marketplace](https://github.com/recoupable/marketplace), using the manifest/package name shown there. Skills-only installation with `npx skills add recoupable/skills` does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed.\n\nMCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access.\n\nStart a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow.\n","headings":[],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Add \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for the dated client verification record and troubleshooting.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"After connecting, refresh tools and call the discovered \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For workflow instructions, install the consolidated Recoup package from the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketplace\",\n children: \"Recoup marketplace\"\n }), \", using the manifest/package name shown there. Skills-only installation with \", _jsx(_components.code, {\n children: \"npx skills add recoupable/skills\"\n }), \" does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"MCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Start a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Claude Connect Claude to Recoup and install optional workflow instructions. Quickstart Getting started Add `https://api.recoupable.dev/mcp` in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See [MCP OAuth](/mcp-oauth) for the dated client verification record and troubleshooting. After connecting, refresh tools and call the discovered `list_artists` tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account. For workflow instructions, install the consolidated Recoup package from the [Recoup marketplace](https://github.com/recoupable/marketplace), using the manifest/package name shown there. Skills-only installation with `npx skills add recoupable/skills` does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed. MCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access. Start a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow. "},{"slug":"mcp","title":"MCP","description":"Connect an agent to Recoup through OAuth and discover its authorized tools.","category":"Quickstart","group":"Getting started","source":"mcp.mdx","body":"Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](/mcp-oauth).\n\nUse `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result.\n\n`mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.\n\nSandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](/api-reference/sandboxes/create) with a separate authorized credential when required.\n\nFor an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.\n\n## Context results\n\nThe [Context reference](/api-reference/context/operate) pairs each supported action\nwith its success status, response model and synthetic request/result examples.\nUse the status declared for that action: `ingest` returns 202, while the specific\ncatalog, artist, release and text ingestion actions return 200. A 202 verification\nreceipt means queued after existing readiness checks, not completed work.\nHTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt;\ndelegated OAuth omits it. The examples do not verify hosted access or enable collection.\n\n## Plan a catalog lookup\n\nA catalog manager with an existing catalog Context request can plan a lookup for\nits current expanded recording members. Standard MCP uses `context` with\n`action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research`\nwith the same input fields and no `action`. Discover the tool in the connected\nclient before use; this source mapping does not prove hosted availability.\n\nChoose `recording_candidates`, `recording_work_candidates` or `platform_metadata`.\nThese plan possible recording matches, linked works or platform track information.\nThe response preserves the existing module values and node IDs, returns each node\nblocked and has `collectionPermitted: false`. It does not fetch data, verify rights,\nstart collection or grant spending permission. The [Context reference](/api-reference/context/operate)\nlists all accepted compatibility values, required IDs, page cursors and the complete response.\n\n## Continue a catalog case\n\nThe source contract adds `save_catalog_case`, `read_catalog_case` and\n`list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the\ntools in the connected host before using them. They also use the `context` tool\nwith the corresponding `action`. The catalog-case database and API release must\nbe deployed before this source contract is available.\n\nA case keeps versioned sources, assessments, findings, proposed actions, attempts\nand outcomes for the authorized workspace. No artist or ingestion request is\nrequired. The stored snapshot is `customer_assertion` evidence and always returns\n`external_actions: unsupported`: saving a record does not submit a registration,\nsend a claim, confirm a provider decision or verify a bank receipt.\n\nFor a new case, save with `expected_revision: 0` and `snapshot.revision: 0`.\nFor subsequent saves, use the current revision. Supply a unique idempotency key\nfor each new save. After an uncertain response, retry the unchanged payload with\nthe same key and expected revision.\nReads can withhold withdrawn evidence and its dependent records; explicitly\nreassemble a partial snapshot before another save. The [Context reference](/api-reference/context/operate)\ndefines the complete bounded schema, historical-source rules, revision conflicts,\nresponse fields and list pagination.\n\n## Check an application proposal\n\nThe pending standard MCP tool `validate_application_registration` checks an\nauthorized workspace's proposed name, environment, exact origins and return URLs.\nIt returns `persisted: false` and `origins_verified: false`; it does not register\nan application, prove domain ownership or issue application credentials.\nDelegated OAuth excludes this tool, including grants with `mcp:tools`. Discover\nit in a standard connection before use. See the [proposal preflight reference](/api-reference/applications/validate-registration)\nfor inputs, normal authentication effects and the limits of a successful result.\n\n## Release Packs\n\nWhen deployed and exposed by the current grant, the pack catalog includes\n`prepare_release_pack`, `get_release_pack`, `estimate_release_pack`,\n`generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and\n`export_release_pack`. These use the same account ownership, brief revisions,\ncomplete quotes and budget limits as REST. No existing artist or GitHub workspace\nis required. Use returned schemas and identifiers; preparation does not authorize\npaid generation. See [Release Packs](/release-packs) for first use and upload limits.\n","headings":[{"title":"Context results","id":"context-results"},{"title":"Plan a catalog lookup","id":"plan-a-catalog-lookup"},{"title":"Continue a catalog case","id":"continue-a-catalog-case"},{"title":"Check an application proposal","id":"check-an-application-proposal"},{"title":"Release Packs","id":"release-packs"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Connect your host to \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"OAuth setup guide\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"tools/list\"\n }), \" after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" and call it with its returned schema to verify access. An empty roster is a valid result.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sandbox command tools previously shown on this page are absent from the current registry. Do not call \", _jsx(_components.code, {\n children: \"prompt_sandbox\"\n }), \", \", _jsx(_components.code, {\n children: \"run_sandbox_command\"\n }), \", or infer that every REST endpoint is exposed as MCP. Use documented \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/create\",\n children: \"REST sandbox operations\"\n }), \" with a separate authorized credential when required.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For an API-key MCP connection, configure \", _jsx(_components.code, {\n children: \"Authorization: Bearer YOUR_RECOUP_API_KEY\"\n }), \" in the client's secret settings. The \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header is for \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"REST requests\"\n }), \". Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"context-results\",\n children: \"Context results\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \" pairs each supported action\\nwith its success status, response model and synthetic request/result examples.\\nUse the status declared for that action: \", _jsx(_components.code, {\n children: \"ingest\"\n }), \" returns 202, while the specific\\ncatalog, artist, release and text ingestion actions return 200. A 202 verification\\nreceipt means queued after existing readiness checks, not completed work.\\nHTTP/standard MCP \", _jsx(_components.code, {\n children: \"read\"\n }), \" may include a metadata-only \", _jsx(_components.code, {\n children: \"material_evidence\"\n }), \" receipt;\\ndelegated OAuth omits it. The examples do not verify hosted access or enable collection.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"plan-a-catalog-lookup\",\n children: \"Plan a catalog lookup\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A catalog manager with an existing catalog Context request can plan a lookup for\\nits current expanded recording members. Standard MCP uses \", _jsx(_components.code, {\n children: \"context\"\n }), \" with\\n\", _jsx(_components.code, {\n children: \"action: plan_catalog_members\"\n }), \"; delegated OAuth uses \", _jsx(_components.code, {\n children: \"plan_music_catalog_research\"\n }), \"\\nwith the same input fields and no \", _jsx(_components.code, {\n children: \"action\"\n }), \". Discover the tool in the connected\\nclient before use; this source mapping does not prove hosted availability.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Choose \", _jsx(_components.code, {\n children: \"recording_candidates\"\n }), \", \", _jsx(_components.code, {\n children: \"recording_work_candidates\"\n }), \" or \", _jsx(_components.code, {\n children: \"platform_metadata\"\n }), \".\\nThese plan possible recording matches, linked works or platform track information.\\nThe response preserves the existing module values and node IDs, returns each node\\nblocked and has \", _jsx(_components.code, {\n children: \"collectionPermitted: false\"\n }), \". It does not fetch data, verify rights,\\nstart collection or grant spending permission. The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \"\\nlists all accepted compatibility values, required IDs, page cursors and the complete response.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"continue-a-catalog-case\",\n children: \"Continue a catalog case\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The source contract adds \", _jsx(_components.code, {\n children: \"save_catalog_case\"\n }), \", \", _jsx(_components.code, {\n children: \"read_catalog_case\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"list_catalog_cases\"\n }), \" to standard MCP; delegated OAuth excludes them. Discover the\\ntools in the connected host before using them. They also use the \", _jsx(_components.code, {\n children: \"context\"\n }), \" tool\\nwith the corresponding \", _jsx(_components.code, {\n children: \"action\"\n }), \". The catalog-case database and API release must\\nbe deployed before this source contract is available.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A case keeps versioned sources, assessments, findings, proposed actions, attempts\\nand outcomes for the authorized workspace. No artist or ingestion request is\\nrequired. The stored snapshot is \", _jsx(_components.code, {\n children: \"customer_assertion\"\n }), \" evidence and always returns\\n\", _jsx(_components.code, {\n children: \"external_actions: unsupported\"\n }), \": saving a record does not submit a registration,\\nsend a claim, confirm a provider decision or verify a bank receipt.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a new case, save with \", _jsx(_components.code, {\n children: \"expected_revision: 0\"\n }), \" and \", _jsx(_components.code, {\n children: \"snapshot.revision: 0\"\n }), \".\\nFor subsequent saves, use the current revision. Supply a unique idempotency key\\nfor each new save. After an uncertain response, retry the unchanged payload with\\nthe same key and expected revision.\\nReads can withhold withdrawn evidence and its dependent records; explicitly\\nreassemble a partial snapshot before another save. The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \"\\ndefines the complete bounded schema, historical-source rules, revision conflicts,\\nresponse fields and list pagination.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"check-an-application-proposal\",\n children: \"Check an application proposal\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The pending standard MCP tool \", _jsx(_components.code, {\n children: \"validate_application_registration\"\n }), \" checks an\\nauthorized workspace's proposed name, environment, exact origins and return URLs.\\nIt returns \", _jsx(_components.code, {\n children: \"persisted: false\"\n }), \" and \", _jsx(_components.code, {\n children: \"origins_verified: false\"\n }), \"; it does not register\\nan application, prove domain ownership or issue application credentials.\\nDelegated OAuth excludes this tool, including grants with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \". Discover\\nit in a standard connection before use. See the \", _jsx(_components.a, {\n href: \"/api-reference/applications/validate-registration\",\n children: \"proposal preflight reference\"\n }), \"\\nfor inputs, normal authentication effects and the limits of a successful result.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"release-packs\",\n children: \"Release Packs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"When deployed and exposed by the current grant, the pack catalog includes\\n\", _jsx(_components.code, {\n children: \"prepare_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"get_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"estimate_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"generate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"retry_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"upload_release_pack_asset\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"export_release_pack\"\n }), \". These use the same account ownership, brief revisions,\\ncomplete quotes and budget limits as REST. No existing artist or GitHub workspace\\nis required. Use returned schemas and identifiers; preparation does not authorize\\npaid generation. See \", _jsx(_components.a, {\n href: \"/release-packs\",\n children: \"Release Packs\"\n }), \" for first use and upload limits.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"MCP Connect an agent to Recoup through OAuth and discover its authorized tools. Quickstart Getting started Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](/mcp-oauth). Use `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result. `mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access. Sandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](/api-reference/sandboxes/create) with a separate authorized credential when required. For an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST. ## Context results The [Context reference](/api-reference/context/operate) pairs each supported action with its success status, response model and synthetic request/result examples. Use the status declared for that action: `ingest` returns 202, while the specific catalog, artist, release and text ingestion actions return 200. A 202 verification receipt means queued after existing readiness checks, not completed work. HTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt; delegated OAuth omits it. The examples do not verify hosted access or enable collection. ## Plan a catalog lookup A catalog manager with an existing catalog Context request can plan a lookup for its current expanded recording members. Standard MCP uses `context` with `action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research` with the same input fields and no `action`. Discover the tool in the connected client before use; this source mapping does not prove hosted availability. Choose `recording_candidates`, `recording_work_candidates` or `platform_metadata`. These plan possible recording matches, linked works or platform track information. The response preserves the existing module values and node IDs, returns each node blocked and has `collectionPermitted: false`. It does not fetch data, verify rights, start collection or grant spending permission. The [Context reference](/api-reference/context/operate) lists all accepted compatibility values, required IDs, page cursors and the complete response. ## Continue a catalog case The source contract adds `save_catalog_case`, `read_catalog_case` and `list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the tools in the connected host before using them. They also use the `context` tool with the corresponding `action`. The catalog-case database and API release must be deployed before this source contract is available. A case keeps versioned sources, assessments, findings, proposed actions, attempts and outcomes for the authorized workspace. No artist or ingestion request is required. The stored snapshot is `customer_assertion` evidence and always returns `external_actions: unsupported`: saving a record does not submit a registration, send a claim, confirm a provider decision or verify a bank receipt. For a new case, save with `expected_revision: 0` and `snapshot.revision: 0`. For subsequent saves, use the current revision. Supply a unique idempotency key for each new save. After an uncertain response, retry the unchanged payload with the same key and expected revision. Reads can withhold withdrawn evidence and its dependent records; explicitly reassemble a partial snapshot before another save. The [Context reference](/api-reference/context/operate) defines the complete bounded schema, historical-source rules, revision conflicts, response fields and list pagination. ## Check an application proposal The pending standard MCP tool `validate_application_registration` checks an authorized workspace's proposed name, environment, exact origins and return URLs. It returns `persisted: false` and `origins_verified: false`; it does not register an application, prove domain ownership or issue application credentials. Delegated OAuth excludes this tool, including grants with `mcp:tools`. Discover it in a standard connection before use. See the [proposal preflight reference](/api-reference/applications/validate-registration) for inputs, normal authentication effects and the limits of a successful result. ## Release Packs When deployed and exposed by the current grant, the pack catalog includes `prepare_release_pack`, `get_release_pack`, `estimate_release_pack`, `generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and `export_release_pack`. These use the same account ownership, brief revisions, complete quotes and budget limits as REST. No existing artist or GitHub workspace is required. Use returned schemas and identifiers; preparation does not authorize paid generation. See [Release Packs](/release-packs) for first use and upload limits. "},{"slug":"mcp-oauth","title":"Connect an agent","description":"Connect an MCP client to Recoup with OAuth and account-authorized tools.","category":"Quickstart","group":"Getting started","source":"mcp-oauth.mdx","body":"Use this URL in your agent's remote MCP settings:\n\n```text\nhttps://api.recoupable.dev/mcp\n```\n\nSelect **OAuth**. Recoup supports [published client metadata (CIMD)](/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.\n\n## What your agent can do\n\nRequest **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.\n\nThe consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.\n\n| Permission | Access |\n| --- | --- |\n| `mcp:tools` | Full business-tool catalog across accessible workspaces |\n| `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` |\n| `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` |\n\nExisting limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience.\n\nOAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.\n\nEmail uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.\n\nThe platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.\n\nNew connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately.\n\nConnections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.\n\n## Claude\n\n1. Open **Customize → Connectors → Add custom connector**.\n2. Name it **Recoup** and enter the MCP URL above.\n3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR.\n4. Connect, sign in to Recoup, and select **Allow access**.\n5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.\n\nClaude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.\n\nClaude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).\n\n## ChatGPT\n\nIn the interface tested on October 7, 2026:\n\n1. Open **Plugins → Add → Add custom MCP server**.\n2. Enter **Recoup**, the MCP URL, and **OAuth**.\n3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access.\n4. Create the plugin, connect it, and complete Recoup consent.\n5. Start a chat with Recoup enabled and request an artist list.\n\nChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).\n\n## Codex\n\n```bash\ncodex mcp add recoup --url https://api.recoupable.dev/mcp\ncodex mcp login recoup --scopes mcp:tools\n```\n\nComplete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp).\n\n## Cursor\n\nAdd a remote server to your project's `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"recoup\": {\n \"url\": \"https://api.recoupable.dev/mcp\"\n }\n }\n}\n```\n\nOpen Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions.\n\n## Other agents and callbacks\n\nUse a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:\n\n- Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp`\n- Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth`\n- Resource: `https://api.recoupable.dev/mcp`\n\nRegister the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration.\n\nA generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.\n\n### Additional client setup paths\n\nThe following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.\n\n| Client | Setup and callback guidance |\n| --- | --- |\n| [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. |\n| [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. |\n| [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. |\n| [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost:/oauth/callback` unless configured otherwise. |\n| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. |\n| [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. |\n| [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. |\n| [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. |\n\nDocumented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.\n\n## Disconnect\n\nOpen [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.\n\n## Troubleshooting\n\n| Symptom | What to do |\n| --- | --- |\n| Custom connector option missing | Check your client's plan and workspace-admin permissions. |\n| Published identity / CIMD unavailable or fails | Check the [metadata requirements](/mcp-cimd), or choose automatic registration / DCR if your client offers it. |\n| Connection request expired | Restart Connect from the client; do not reuse an old consent URL. |\n| Wrong Recoup account | Use Switch before approving. |\n| Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. |\n| Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. |\n| Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. |\n| `401` after disconnect | Expected: reconnect and approve a new grant. |\n| `429` | Respect `Retry-After`; avoid repeated registration attempts. |\n| `503` | Retry later; do not weaken authentication or callback checks. |\n| Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. |\n\nFor clients without OAuth, [API-key authentication](/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.\n\nFor help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys.\n\nFull OAuth MCP calls currently share account-level limits of 120 calls per minute\nand 30 calls per tool per minute across connected clients. See the\n[pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts).\nThe `compact_chats` MCP tool accepts up to 50 chats per call under the\n[pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts);\nthis is an MCP limit, not a claimed REST request limit.\n","headings":[{"title":"What your agent can do","id":"what-your-agent-can-do"},{"title":"Claude","id":"claude"},{"title":"ChatGPT","id":"chatgpt"},{"title":"Codex","id":"codex"},{"title":"Cursor","id":"cursor"},{"title":"Other agents and callbacks","id":"other-agents-and-callbacks"},{"title":"Disconnect","id":"disconnect"},{"title":"Troubleshooting","id":"troubleshooting"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Use this URL in your agent's remote MCP settings:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-text\",\n children: \"https://api.recoupable.dev/mcp\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Select \", _jsx(_components.strong, {\n children: \"OAuth\"\n }), \". Recoup supports \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"published client metadata (CIMD)\"\n }), \" and \", _jsx(_components.strong, {\n children: \"automatic registration\"\n }), \" (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-your-agent-can-do\",\n children: \"What your agent can do\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Request \", _jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"mcp:tools\"\n })\n }), \" for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Permission\"\n }), _jsx(_components.th, {\n children: \"Access\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:tools\"\n })\n }), _jsx(_components.td, {\n children: \"Full business-tool catalog across accessible workspaces\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:read\"\n })\n }), _jsxs(_components.td, {\n children: [\"Original personal-only \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \", \", _jsx(_components.code, {\n children: \"get_artist_socials\"\n }), \", \", _jsx(_components.code, {\n children: \"get_chats\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:write\"\n })\n }), _jsxs(_components.td, {\n children: [\"Original personal-only \", _jsx(_components.code, {\n children: \"create_new_artist\"\n }), \", \", _jsx(_components.code, {\n children: \"update_account_info\"\n })]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Existing limited grants do \", _jsx(_components.strong, {\n children: \"not\"\n }), \" expand automatically. Reconnect with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \", review the broader permission, and refresh your client's tool catalog. Clients requesting the \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" + \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" pair keep the five-tool experience.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"OAuth never exposes \", _jsx(_components.code, {\n children: \"get_api_key\"\n }), \": it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. \", _jsx(_components.code, {\n children: \"create_knowledge_base\"\n }), \" and \", _jsx(_components.code, {\n children: \"generate_txt_file\"\n }), \" publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound \", _jsx(_components.code, {\n children: \"id\"\n }), \"; pass that entire value as \", _jsx(_components.code, {\n children: \"video_id\"\n }), \" to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/oauth/connections\",\n children: \"Connected agents\"\n }), \" to revoke its access and refresh tokens immediately.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"claude\",\n children: \"Claude\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Open \", _jsx(_components.strong, {\n children: \"Customize → Connectors → Add custom connector\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Name it \", _jsx(_components.strong, {\n children: \"Recoup\"\n }), \" and enter the MCP URL above.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Choose \", _jsx(_components.strong, {\n children: \"Sign in now\"\n }), \". \", _jsx(_components.strong, {\n children: \"Register automatically\"\n }), \" uses DCR; \", _jsx(_components.strong, {\n children: \"published identity\"\n }), \" uses CIMD. The production client tests below used DCR.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Connect, sign in to Recoup, and select \", _jsx(_components.strong, {\n children: \"Allow access\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See \", _jsx(_components.a, {\n href: \"https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp\",\n children: \"Claude's remote connector guide\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"chatgpt\",\n children: \"ChatGPT\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"In the interface tested on October 7, 2026:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Open \", _jsx(_components.strong, {\n children: \"Plugins → Add → Add custom MCP server\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Enter \", _jsx(_components.strong, {\n children: \"Recoup\"\n }), \", the MCP URL, and \", _jsx(_components.strong, {\n children: \"OAuth\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Under advanced OAuth settings, confirm \", _jsx(_components.strong, {\n children: \"Dynamic Client Registration (DCR)\"\n }), \" and request \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for full access.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Create the plugin, connect it, and complete Recoup consent.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Start a chat with Recoup enabled and request an artist list.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see \", _jsx(_components.a, {\n href: \"https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt\",\n children: \"OpenAI's MCP setup documentation\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"codex\",\n children: \"Codex\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"codex mcp add recoup --url https://api.recoupable.dev/mcp\\ncodex mcp login recoup --scopes mcp:tools\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See \", _jsx(_components.a, {\n href: \"https://developers.openai.com/codex/mcp\",\n children: \"Codex MCP configuration\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"cursor\",\n children: \"Cursor\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Add a remote server to your project's \", _jsx(_components.code, {\n children: \".cursor/mcp.json\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"mcpServers\\\": {\\n \\\"recoup\\\": {\\n \\\"url\\\": \\\"https://api.recoupable.dev/mcp\\\"\\n }\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See \", _jsx(_components.a, {\n href: \"https://cursor.com/docs/mcp\",\n children: \"Cursor's MCP guide\"\n }), \" for the current setup and workspace restrictions.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"other-agents-and-callbacks\",\n children: \"Other agents and callbacks\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Resource metadata: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Authorization-server metadata: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Resource: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute \", _jsx(_components.code, {\n children: \"localhost\"\n }), \" for \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \" or edit a callback after registration.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"CIMD requirements and verification status\"\n }), \". Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"additional-client-setup-paths\",\n children: \"Additional client setup paths\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The following paths were reviewed in official client documentation on October 7, 2026. \", _jsx(_components.strong, {\n children: \"They have not been tested end to end against Recoup.\"\n }), \" Use automatic registration and request \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for full access, or \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" / \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Client\"\n }), _jsx(_components.th, {\n children: \"Setup and callback guidance\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors\",\n children: \"Perplexity\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are \", _jsx(_components.code, {\n children: \"https://www.perplexity.ai/rest/connections/oauth_callback\"\n }), \" and, for enterprise, \", _jsx(_components.code, {\n children: \"https://enterprise.perplexity.ai/rest/connections/oauth_callback\"\n }), \".\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://code.claude.com/docs/en/mcp\",\n children: \"Claude Code\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add Recoup as an HTTP server and authenticate through \", _jsx(_components.code, {\n children: \"/mcp\"\n }), \" inside Claude Code. Automatic registration uses a localhost callback; \", _jsx(_components.code, {\n children: \"--callback-port\"\n }), \" can fix its port when required.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization\",\n children: \"VS Code\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add an HTTP server in \", _jsx(_components.code, {\n children: \".vscode/mcp.json\"\n }), \". OAuth supports DCR; documented callbacks include \", _jsx(_components.code, {\n children: \"http://127.0.0.1:33418\"\n }), \" and \", _jsx(_components.code, {\n children: \"https://vscode.dev/redirect\"\n }), \". Preserve the callback supplied by your VS Code surface.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://geminicli.com/docs/tools/mcp-server/\",\n children: \"Gemini CLI\"\n })\n }), _jsxs(_components.td, {\n children: [\"Configure the MCP URL as \", _jsx(_components.code, {\n children: \"httpUrl\"\n }), \" and authenticate with \", _jsx(_components.code, {\n children: \"/mcp auth recoup\"\n }), \" inside the Gemini CLI chat. DCR uses \", _jsx(_components.code, {\n children: \"http://localhost:/oauth/callback\"\n }), \" unless configured otherwise.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://opencode.ai/docs/mcp-servers/\",\n children: \"OpenCode\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add a remote MCP server and run \", _jsx(_components.code, {\n children: \"opencode mcp auth recoup\"\n }), \". OAuth supports automatic registration. Let the client supply its callback.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://kiro.dev/docs/mcp/configuration/\",\n children: \"Kiro\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add the remote MCP URL and use DCR. Set \", _jsx(_components.code, {\n children: \"oauth.oauthScopes\"\n }), \" to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://docs.n8n.io/integrations/builtin/credentials/mcp/\",\n children: \"n8n\"\n })\n }), _jsxs(_components.td, {\n children: [\"Create an MCP OAuth credential with \", _jsx(_components.strong, {\n children: \"Use Dynamic Client Registration\"\n }), \" enabled. Use the exact callback shown by your n8n instance.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent\",\n children: \"Copilot Studio\"\n })\n }), _jsx(_components.td, {\n children: \"Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio.\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"disconnect\",\n children: \"Disconnect\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Open \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/oauth/connections\",\n children: \"Connected agents\"\n }), \" and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"troubleshooting\",\n children: \"Troubleshooting\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Symptom\"\n }), _jsx(_components.th, {\n children: \"What to do\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Custom connector option missing\"\n }), _jsx(_components.td, {\n children: \"Check your client's plan and workspace-admin permissions.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Published identity / CIMD unavailable or fails\"\n }), _jsxs(_components.td, {\n children: [\"Check the \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"metadata requirements\"\n }), \", or choose automatic registration / DCR if your client offers it.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Connection request expired\"\n }), _jsx(_components.td, {\n children: \"Restart Connect from the client; do not reuse an old consent URL.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Wrong Recoup account\"\n }), _jsx(_components.td, {\n children: \"Use Switch before approving.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Still seeing only five tools\"\n }), _jsxs(_components.td, {\n children: [\"Reconnect requesting \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \", approve full access, then refresh the client tool catalog.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Connected but no tool access\"\n }), _jsx(_components.td, {\n children: \"Check selected scopes, individual tool approvals, and whether the grant expired or was revoked.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Organization artist missing\"\n }), _jsxs(_components.td, {\n children: [\"Reconnect with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" and verify your organization membership.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"401\"\n }), \" after disconnect\"]\n }), _jsx(_components.td, {\n children: \"Expected: reconnect and approve a new grant.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"429\"\n })\n }), _jsxs(_components.td, {\n children: [\"Respect \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \"; avoid repeated registration attempts.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"503\"\n })\n }), _jsx(_components.td, {\n children: \"Retry later; do not weaken authentication or callback checks.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Write timed out\"\n }), _jsx(_components.td, {\n children: \"Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate.\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For clients without OAuth, \", _jsx(_components.a, {\n href: \"/mcp\",\n children: \"API-key authentication\"\n }), \" remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For help, contact \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \". Include the client name, time, and error text; never include tokens, passwords, or API keys.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Full OAuth MCP calls currently share account-level limits of 120 calls per minute\\nand 30 calls per tool per minute across connected clients. See the\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts\",\n children: \"pinned rate-limit implementation\"\n }), \".\\nThe \", _jsx(_components.code, {\n children: \"compact_chats\"\n }), \" MCP tool accepts up to 50 chats per call under the\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts\",\n children: \"pinned MCP guard\"\n }), \";\\nthis is an MCP limit, not a claimed REST request limit.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Connect an agent Connect an MCP client to Recoup with OAuth and account-authorized tools. Quickstart Getting started Use this URL in your agent's remote MCP settings: Select **OAuth**. Recoup supports [published client metadata (CIMD)](/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied. ## What your agent can do Request **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support. The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound. | Permission | Access | | --- | --- | | `mcp:tools` | Full business-tool catalog across accessible workspaces | | `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` | | `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` | Existing limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience. OAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog. Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs. The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification. New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately. Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected. ## Claude 1. Open **Customize → Connectors → Add custom connector**. 2. Name it **Recoup** and enter the MCP URL above. 3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR. 4. Connect, sign in to Recoup, and select **Allow access**. 5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted. Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward. Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). ## ChatGPT In the interface tested on October 7, 2026: 1. Open **Plugins → Add → Add custom MCP server**. 2. Enter **Recoup**, the MCP URL, and **OAuth**. 3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access. 4. Create the plugin, connect it, and complete Recoup consent. 5. Start a chat with Recoup enabled and request an artist list. ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt). ## Codex Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp). ## Cursor Add a remote server to your project's `.cursor/mcp.json`: Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions. ## Other agents and callbacks Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes: - Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp` - Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth` - Resource: `https://api.recoupable.dev/mcp` Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration. A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only. ### Additional client setup paths The following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist. | Client | Setup and callback guidance | | --- | --- | | [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. | | [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. | | [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. | | [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost: /oauth/callback` unless configured otherwise. | | [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. | | [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. | | [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. | | [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. | Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access. ## Disconnect Open [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again. ## Troubleshooting | Symptom | What to do | | --- | --- | | Custom connector option missing | Check your client's plan and workspace-admin permissions. | | Published identity / CIMD unavailable or fails | Check the [metadata requirements](/mcp-cimd), or choose automatic registration / DCR if your client offers it. | | Connection request expired | Restart Connect from the client; do not reuse an old consent URL. | | Wrong Recoup account | Use Switch before approving. | | Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. | | Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. | | Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. | | `401` after disconnect | Expected: reconnect and approve a new grant. | | `429` | Respect `Retry-After`; avoid repeated registration attempts. | | `503` | Retry later; do not weaken authentication or callback checks. | | Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. | For clients without OAuth, [API-key authentication](/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command. For help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys. Full OAuth MCP calls currently share account-level limits of 120 calls per minute and 30 calls per tool per minute across connected clients. See the [pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts). The `compact_chats` MCP tool accepts up to 50 chats per call under the [pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts); this is an MCP limit, not a claimed REST request limit. "},{"slug":"mcp-cimd","title":"Published client metadata (CIMD)","description":"Connect using an HTTPS client identity without dynamic registration.","category":"Quickstart","group":"Getting started","source":"mcp-cimd.mdx","body":"Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth `client_id`. Recoup retrieves that document and validates the client's callbacks before asking you to approve access.\n\nUse the same MCP server URL: `https://api.recoupable.dev/mcp`. A compatible client can discover CIMD through `client_id_metadata_document_supported: true` in Recoup's [authorization-server metadata](https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth). No vendor-specific registration or callback allowlist is needed.\n\n## Access and trust\n\nCIMD uses the same [permissions and consent](/mcp-oauth) as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work.\n\nA client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account.\n\n## Client requirements\n\n- Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected.\n- Set `client_id` to the exact document URL and include `client_name` and `redirect_uris`.\n- Use a document URL with an explicit path and without credentials, fragments, or dot path segments.\n- Use authorization code flow with PKCE S256 and `mcp:tools` for the full Recoup catalog, or `mcp:read` / `mcp:write` for the original limited personal tools.\n- Public clients should set `token_endpoint_auth_method` to `none`. Never publish client secrets or private keys.\n- Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. `localhost` and `127.0.0.1` remain different hosts.\n\nRecoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy.\n\nMetadata caching respects freshness headers up to five minutes. `no-store`, `no-cache`, absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata.\n\n## Verification status\n\nThe implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits.\n\nA local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on [Connect an agent](/mcp-oauth) were obtained using DCR.\n\nProduction verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified.\n\nIf a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored.\n\nSee the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and [CIMD draft 02](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html). CIMD remains a draft specification; Recoup's provider currently implements draft 02.\n","headings":[{"title":"Access and trust","id":"access-and-trust"},{"title":"Client requirements","id":"client-requirements"},{"title":"Verification status","id":"verification-status"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth \", _jsx(_components.code, {\n children: \"client_id\"\n }), \". Recoup retrieves that document and validates the client's callbacks before asking you to approve access.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the same MCP server URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \". A compatible client can discover CIMD through \", _jsx(_components.code, {\n children: \"client_id_metadata_document_supported: true\"\n }), \" in Recoup's \", _jsx(_components.a, {\n href: \"https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth\",\n children: \"authorization-server metadata\"\n }), \". No vendor-specific registration or callback allowlist is needed.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"access-and-trust\",\n children: \"Access and trust\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"CIMD uses the same \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"permissions and consent\"\n }), \" as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"client-requirements\",\n children: \"Client requirements\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Set \", _jsx(_components.code, {\n children: \"client_id\"\n }), \" to the exact document URL and include \", _jsx(_components.code, {\n children: \"client_name\"\n }), \" and \", _jsx(_components.code, {\n children: \"redirect_uris\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Use a document URL with an explicit path and without credentials, fragments, or dot path segments.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use authorization code flow with PKCE S256 and \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for the full Recoup catalog, or \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" / \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" for the original limited personal tools.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Public clients should set \", _jsx(_components.code, {\n children: \"token_endpoint_auth_method\"\n }), \" to \", _jsx(_components.code, {\n children: \"none\"\n }), \". Never publish client secrets or private keys.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. \", _jsx(_components.code, {\n children: \"localhost\"\n }), \" and \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \" remain different hosts.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Recoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Metadata caching respects freshness headers up to five minutes. \", _jsx(_components.code, {\n children: \"no-store\"\n }), \", \", _jsx(_components.code, {\n children: \"no-cache\"\n }), \", absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"verification-status\",\n children: \"Verification status\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"Connect an agent\"\n }), \" were obtained using DCR.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Production verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See the \", _jsx(_components.a, {\n href: \"https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization\",\n children: \"MCP authorization specification\"\n }), \" and \", _jsx(_components.a, {\n href: \"https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html\",\n children: \"CIMD draft 02\"\n }), \". CIMD remains a draft specification; Recoup's provider currently implements draft 02.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Published client metadata (CIMD) Connect using an HTTPS client identity without dynamic registration. Quickstart Getting started Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth `client_id`. Recoup retrieves that document and validates the client's callbacks before asking you to approve access. Use the same MCP server URL: `https://api.recoupable.dev/mcp`. A compatible client can discover CIMD through `client_id_metadata_document_supported: true` in Recoup's [authorization-server metadata](https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth). No vendor-specific registration or callback allowlist is needed. ## Access and trust CIMD uses the same [permissions and consent](/mcp-oauth) as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work. A client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account. ## Client requirements - Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected. - Set `client_id` to the exact document URL and include `client_name` and `redirect_uris`. - Use a document URL with an explicit path and without credentials, fragments, or dot path segments. - Use authorization code flow with PKCE S256 and `mcp:tools` for the full Recoup catalog, or `mcp:read` / `mcp:write` for the original limited personal tools. - Public clients should set `token_endpoint_auth_method` to `none`. Never publish client secrets or private keys. - Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. `localhost` and `127.0.0.1` remain different hosts. Recoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy. Metadata caching respects freshness headers up to five minutes. `no-store`, `no-cache`, absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata. ## Verification status The implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits. A local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on [Connect an agent](/mcp-oauth) were obtained using DCR. Production verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified. If a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored. See the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and [CIMD draft 02](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html). CIMD remains a draft specification; Recoup's provider currently implements draft 02. "},{"slug":"authentication","title":"Authentication","description":"How authentication works in the Recoup API — API keys, access tokens, and organization access control.","category":"Quickstart","group":"Getting started","source":"authentication.mdx","body":"## Overview\n\nEvery request to the Recoup API must be authenticated using exactly one of two mechanisms:\n\n| Method | Header | Use case |\n|--------|--------|----------|\n| API Key | `x-api-key` | Server-to-server integrations |\n| Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy |\n\nProviding both headers in the same request will result in a `401` error.\n\n\nAgent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details.\n\n\n---\n\n## API Keys\n\nAPI 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.\n\n### Creating an API Key\n\n1. Navigate to [chat.recoupable.dev/keys](https://chat.recoupable.dev/keys)\n2. Enter a descriptive name (e.g. `\"Production Server\"`)\n3. Click **Create API Key**\n\n\nCopy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation.\n\n\n### Using an API Key\n\nPass your key in the `x-api-key` header:\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n### Access to Organizations\n\nIf 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.\n\n- **No org membership** — the key can only access its own account's data\n- **Org member** — the key can pass `account_id` to filter to any account within that organization\n\n\nOrg 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.\n\n\n---\n\n## Access Tokens (Privy)\n\nIf 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.\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"Authorization: Bearer YOUR_PRIVY_JWT\"\n```\n\nThe 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.\n\n---\n\n## How We Verify Access on API Calls\n\nEvery authenticated request goes through `validateAuthContext`, which enforces the following access rules:\n\n### API Key or Bearer Token\n\nBy default, requests access the key owner's own account. When `account_id` is provided:\n\n```\nRequest includes account_id override?\n ├── Same as key owner → Allowed (self-access)\n ├── Key owner is a member of an org that contains account_id → Allowed\n └── No matching org membership → 403 Forbidden\n```\n\nMembership 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.\n\n\nThe Recoup internal admin organization has universal access to all accounts.\n\n\n### Organization Access via `organization_id`\n\nSome endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either:\n\n- A **member** of the organization, or\n- The **organization account itself**\n\n---\n\n## Error Responses\n\n| Status | Cause |\n|--------|-------|\n| `401` | Missing or invalid credentials, or both `x-api-key` and `Authorization` headers provided |\n| `403` | Valid credentials but insufficient access to the requested `account_id` or `organization_id` |\n\n---\n\n## Security Notes\n\n- API keys are **never stored in plaintext** — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database\n- **Never include `account_id` in your API key creation request** — the account is always derived from your authenticated credentials\n- Rotate keys immediately if compromised via the [API Keys Management Page](https://chat.recoupable.dev/keys)\n\n## MCP OAuth and REST credentials\n\nRemote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See [MCP OAuth](/mcp-oauth).\n","headings":[{"title":"Overview","id":"overview"},{"title":"API Keys","id":"api-keys"},{"title":"Access Tokens (Privy)","id":"access-tokens-privy"},{"title":"How We Verify Access on API Calls","id":"how-we-verify-access-on-api-calls"},{"title":"Error Responses","id":"error-responses"},{"title":"Security Notes","id":"security-notes"},{"title":"MCP OAuth and REST credentials","id":"mcp-oauth-and-rest-credentials"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n }, {Info, Note, Warning} = _components;\n if (!Info) _missingMdxReference(\"Info\", true);\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"overview\",\n children: \"Overview\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Every request to the Recoup API must be authenticated using exactly one of two mechanisms:\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Method\"\n }), _jsx(_components.th, {\n children: \"Header\"\n }), _jsx(_components.th, {\n children: \"Use case\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"API Key\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"x-api-key\"\n })\n }), _jsx(_components.td, {\n children: \"Server-to-server integrations\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Access Token\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"Authorization: Bearer \"\n })\n }), _jsx(_components.td, {\n children: \"Frontend apps authenticated via Privy\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Providing both headers in the same request will result in a \", _jsx(_components.code, {\n children: \"401\"\n }), \" error.\"]\n }), \"\\n\", _jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"Agent onboarding endpoints (\", _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" and \", _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \") are \", _jsx(_components.strong, {\n children: \"unauthenticated\"\n }), \" — they exist so agents can obtain their first API key. See the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents guide\"\n }), \" for details.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"api-keys\",\n children: \"API Keys\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are \", _jsx(_components.strong, {\n children: \"personal keys\"\n }), \" — they are always tied to the account that created them.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"creating-an-api-key\",\n children: \"Creating an API Key\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"chat.recoupable.dev/keys\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Enter a descriptive name (e.g. \", _jsx(_components.code, {\n children: \"\\\"Production Server\\\"\"\n }), \")\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Click \", _jsx(_components.strong, {\n children: \"Create API Key\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"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.\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"using-an-api-key\",\n children: \"Using an API Key\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass your key in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"access-to-organizations\",\n children: \"Access to Organizations\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If your account belongs to one or more organizations, your API key can access data across those organizations by passing an \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" parameter on supported endpoints. This lets you filter to any account within an organization your key has access to.\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"No org membership\"\n }), \" — the key can only access its own account's data\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Org member\"\n }), \" — the key can pass \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" to filter to any account within that organization\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Info, {\n children: _jsxs(_components.p, {\n children: [\"Org membership is determined by the account's \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: \"organizations\"\n }), \". An account gains access to an org when it is added as a member.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"access-tokens-privy\",\n children: \"Access Tokens (Privy)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you're building a frontend application that authenticates users via \", _jsx(_components.a, {\n href: \"https://privy.io\",\n children: \"Privy\"\n }), \", you can pass the user's Privy JWT as a Bearer token instead of an API key.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"Authorization: Bearer YOUR_PRIVY_JWT\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"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.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"how-we-verify-access-on-api-calls\",\n children: \"How We Verify Access on API Calls\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Every authenticated request goes through \", _jsx(_components.code, {\n children: \"validateAuthContext\"\n }), \", which enforces the following access rules:\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"api-key-or-bearer-token\",\n children: \"API Key or Bearer Token\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"By default, requests access the key owner's own account. When \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" is provided:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"Request includes account_id override?\\n ├── Same as key owner → Allowed (self-access)\\n ├── Key owner is a member of an org that contains account_id → Allowed\\n └── No matching org membership → 403 Forbidden\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Membership is verified by checking the key owner's \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: \"organizations\"\n }), \" for a record linking the account to the target account's organization.\"]\n }), \"\\n\", _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"The Recoup internal admin organization has universal access to all accounts.\"\n })\n }), \"\\n\", _jsxs(_components.h3, {\n id: \"organization-access-via-organizationid\",\n children: [\"Organization Access via \", _jsx(_components.code, {\n children: \"organization_id\"\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Some endpoints accept an \", _jsx(_components.code, {\n children: \"organization_id\"\n }), \" parameter. When provided, the API additionally validates that the authenticated account is either:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"A \", _jsx(_components.strong, {\n children: \"member\"\n }), \" of the organization, or\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The \", _jsx(_components.strong, {\n children: \"organization account itself\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"error-responses\",\n children: \"Error Responses\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Status\"\n }), _jsx(_components.th, {\n children: \"Cause\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"401\"\n })\n }), _jsxs(_components.td, {\n children: [\"Missing or invalid credentials, or both \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" and \", _jsx(_components.code, {\n children: \"Authorization\"\n }), \" headers provided\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"403\"\n })\n }), _jsxs(_components.td, {\n children: [\"Valid credentials but insufficient access to the requested \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" or \", _jsx(_components.code, {\n children: \"organization_id\"\n })]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"security-notes\",\n children: \"Security Notes\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"API keys are \", _jsx(_components.strong, {\n children: \"never stored in plaintext\"\n }), \" — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsxs(_components.strong, {\n children: [\"Never include \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" in your API key creation request\"]\n }), \" — the account is always derived from your authenticated credentials\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Rotate keys immediately if compromised via the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys Management Page\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"mcp-oauth-and-rest-credentials\",\n children: \"MCP OAuth and REST credentials\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Remote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Authentication How authentication works in the Recoup API — API keys, access tokens, and organization access control. Quickstart Getting started ## Overview Every request to the Recoup API must be authenticated using exactly one of two mechanisms: | Method | Header | Use case | |--------|--------|----------| | API Key | `x-api-key` | Server-to-server integrations | | Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy | Providing both headers in the same request will result in a `401` error. Agent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details. --- ## 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.dev/keys](https://chat.recoupable.dev/keys) 2. Enter a descriptive name (e.g. `\"Production Server\"`) 3. Click **Create API Key** Copy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation. ### Using an API Key Pass your key in the `x-api-key` header: ### 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 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. --- ## Access Tokens (Privy) If you're building a frontend application that authenticates users via [Privy](https://privy.io), you can pass the user's Privy JWT as a Bearer token instead of an API key. 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. --- ## How We Verify Access on API Calls Every authenticated request goes through `validateAuthContext`, which enforces the following access rules: ### API Key or Bearer Token By default, requests access the key owner's own account. When `account_id` is provided: Membership is verified by checking the key owner's [organizations](/api-reference/organizations/list) for a record linking the account to the target account's organization. The Recoup internal admin organization has universal access to all accounts. ### Organization Access via `organization_id` Some endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either: - A **member** of the organization, or - The **organization account itself** --- ## Error Responses | 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.dev/keys) ## MCP OAuth and REST credentials Remote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See [MCP OAuth](/mcp-oauth). "},{"slug":"credits","title":"Credits","description":"How Recoup credits work — what's billed, how to check your balance, and how to upgrade.","category":"Quickstart","group":"Getting started","source":"credits.mdx","body":"Some Recoup endpoints are billed in **credits** — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates.\n\n---\n\n## What's billed\n\n| Family | Billed? | Notes |\n|--------|---------|-------|\n| **Research** ([`/api/research/*`](/api-reference/research/web)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). |\n| **Content generation** ([`/api/content/image`](/api-reference/content/generate-image), [`video`](/api-reference/content/generate-video), upscale, transcribe and analyze) | Yes | Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory. |\n| **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. |\n| **Music analysis** ([`POST /api/songs/analyze`](/api-reference/songs/analyze)) | Yes | \\$0.05 per model call plus \\$0.001166 per second of inference time; `full_report` is the sum of its 13 calls. |\n| **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | \\$0.05, plus \\$0.01 per post requested via `posts` — per social profile scraped. |\n| **Other operations** | Consult the endpoint contract | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. |\n\nUpstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient.\n\n---\n\n## What a credit is worth\n\n**Balances and prices are US dollars.** The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: `1,000,000 = $1.00`, so it can carry sub-cent charges (a \\$0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get).\n\n---\n\n## Check your balance\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/credits \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nResponse shape:\n\n```json\n{\n \"account_id\": \"11111111-1111-4111-8111-111111111111\",\n \"remaining_credits\": 292450000,\n \"total_credits\": 300000000,\n \"used_credits\": 7550000,\n \"is_pro\": true,\n \"plan\": \"pro\",\n \"task_limit\": null,\n \"min_cadence_minutes\": 60,\n \"timestamp\": \"2026-10-01T12:00:00Z\"\n}\n```\n\n`plan`, `task_limit`, and `min_cadence_minutes` describe the [plan](#subscription) the balance belongs to. `total_credits` is your plan-derived monthly allotment. `remaining_credits` can exceed `total_credits` after a top-up or an admin grant, and `used_credits` clamps to 0 in that case. Full schema at [Get Account Credits](/api-reference/accounts/credits-get).\n\n### Plan response examples\n\n`is_pro` on credits and `isPro` on subscriptions mean effective Pro, so both are\nfalse for paid Starter. Use `plan` to distinguish Starter from Free. The credits\nresponse reports the effective allowance; the [subscription response](/api-reference/accounts/subscription-get)\nseparately identifies whether it comes from the account or an organization.\n\n| Situation | Credits `plan` / `is_pro` | Subscription `source` | Task limit / minimum cadence |\n| --- | --- | --- | --- |\n| Free | `free` / `false` | `null` | 1 / weekly |\n| Paid Starter | `starter` / `false` | `account` | 3 / daily |\n| Direct Pro | `pro` / `true` | `account` | `null` (unlimited) / hourly |\n| Starter account with organization Pro | `pro` / `true` | `organization` | `null` (unlimited) / hourly |\n| Inactive subscription without another paid entitlement | `free` / `false` | `null` | 1 / weekly |\n\nFor example, a Pro balance of 325,000,000 against an allowance of 300,000,000\nreturns `used_credits: 0`. The API preserves a signed balance: a negative balance\ncan make this display exceed the allowance. This is not a ledger of charges.\nA null timestamp means the timestamp is unavailable, not proof of no prior activity.\nAn inactive subscription resolves to `status: \"none\"` and null subscription/billing\nfields; this endpoint does not return the canceled subscription's history. Billing\ndetails may also be unavailable on an active response. Named reference examples\nillustrate these states without quoting an available offer or a live payment.\n\nTo see what consumed the balance, list the charges line by line with [`GET /api/accounts/{id}/usage`](/api-reference/accounts/usage-get): one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in `model_id` (for example `POST /api/artist/socials/scrape`), so a list of charges reads as a list of calls.\n\n---\n\n## Subscription\n\nFor Platform, Advisory, Build + Partner, and Enterprise options, see [Recoup pricing](https://recoupable.dev/pricing). API and MCP usage is billed separately through credits.\n\nYour account's current credit allowance and scheduled-task limits are returned by [Get Account Credits](/api-reference/accounts/credits-get). Use `total_credits`, `task_limit`, and `min_cadence_minutes` from that response rather than inferring limits from a public plan name.\n\nThe API may return account identifiers such as `free`, `starter`, or `pro`. These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint.\n\n### Task limits\n\n[`POST /api/tasks`](/api-reference/tasks/create) and [`PATCH /api/tasks`](/api-reference/tasks/update) [check the plan](/api-reference/accounts/credits-get) before writing. Creating a task past `task_limit`, re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than `min_cadence_minutes` returns **HTTP 402** with `error: \"plan_limit\"`:\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"plan_limit\",\n \"limit\": \"task_count\",\n \"message\": \"Free includes 1 task. Starter includes 3, Pro is unlimited.\",\n \"plan\": \"free\",\n \"task_limit\": 1,\n \"min_cadence_minutes\": 10080,\n \"current_task_count\": 1,\n \"billingUrl\": \"https://app.recoupable.dev/plan\"\n}\n```\n\n`limit` is `task_count` or `min_cadence`; `current_task_count` excludes the task being created or updated. Edits that only touch `title`, `prompt`, or `model` never hit the gate.\n\n### Monthly refill\n\nThe refill is a **floor, not an assignment.** It raises `remaining_credits` up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a [top-up](#one-time-top-ups) or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar.\n\nThe refill is lazy rather than scheduled: it applies on the next read of [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get) once your credits row is more than a month old. The balance you read is always the refilled one.\n\n### Manage your subscription\n\nSign in to your [account billing page](https://app.recoupable.dev/plan) to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in [Create Subscription Session](/api-reference/subscriptions/sessions-create) and open its returned checkout URL. Review the price and billing terms before completing checkout.\n\nAdvisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment.\n\n### Check your tier\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/subscription \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nGet `$ACCOUNT_ID` from [`GET /api/accounts/id`](/api-reference/accounts/id) if you don't already have it. Response includes `isPro` (boolean), `status`, `plan`, and `source` (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at [Get Subscription](/api-reference/accounts/subscription-get).\n\n### One-time top-ups\n\nYou can purchase credits any time via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create). The endpoint adapts to what's on the account:\n\n- **Card on file → silent auto-charge.** Recoup charges your saved Stripe card off-session and returns `paymentIntentId`, `creditsPurchased`, and `totalCents`. Credits land within seconds.\n- **No card, or Stripe declines the saved card → Stripe Checkout fallback.** The response contains a Checkout `url` you open in the browser. When Stripe specifically declined a saved card, the response also includes a `declineReason` (e.g. `insufficient_funds`, `expired_card`) so you can explain *why* before sending the customer to update billing.\n\n```bash\ncurl -sS -X POST https://api.recoupable.dev/api/credits/sessions \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"credits\": 1000000, \"successUrl\": \"https://chat.recoupable.dev/credits/success\"}'\n```\n\nFull request/response schema at [Create Credits Top-Up Session](/api-reference/credits/sessions-create).\n\n### Check which card will be charged\n\nBefore triggering a silent off-session charge, inspect the default payment method on file:\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/payment-method \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nResponse shape:\n\n```json\n{\n \"account_id\": \"11111111-1111-4111-8111-111111111111\",\n \"card\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"exp_month\": 12,\n \"exp_year\": 2026,\n \"funding\": \"credit\"\n }\n}\n```\n\n`card` is `null` when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original `exp_month` / `exp_year`); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at [Get Default Payment Method](/api-reference/accounts/payment-method-get).\n\n---\n\n## Running out of credits\n\nEvery billed API request runs a credit gate before it executes. If `remaining_credits` doesn't cover the request's cost, the request stops there and returns **HTTP 402**. Nothing is charged and no Stripe object is created.\n\nThe decision tree:\n\n1. **Enough credits?** → Request proceeds, credits deducted on success.\n2. **Short?** → Request returns **HTTP 402** with the balance, the cost, and a link to billing.\n\nA card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through [`POST /api/credits/sessions`](/api-reference/credits/sessions-create), or when the account has turned on auto top-up. Saving a card ahead of time via [`POST /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-create) makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on [`/api/accounts/{id}/subscription`](/api-reference/accounts/subscription-get), [`/api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-get), and [`/api/accounts/{id}/payments`](/api-reference/accounts/payments-get); pass an organization id as `{id}` to read the organization's billing.\n\n### Auto top-up (opt-in)\n\nAuto top-up is off for every account until it is turned on with [`PUT /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-update), which needs three things chosen by the account: `enabled`, the `amountCents` to buy each time (5.00 to 1,000.00 USD), and the `thresholdCents` balance that triggers it. Both are USD cents; the `remaining_credits` balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file.\n\nOnce on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as `lastError` (returned by [`GET /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-get)), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself.\n\n### Remove a saved card\n\n[`DELETE /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-delete) turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again.\n\nSuccess returns **204** with no body. If no customer or selected card exists, **404** leaves settings and cards unchanged. A **500** can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card.\n\nThis operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently.\n\n---\n\n## 402 Payment Required\n\nWhen the gate comes up short, billed endpoints return **HTTP 402** with a unified body:\n\n```json\n{\n \"error\": \"insufficient_credits\",\n \"remaining_credits\": 120000,\n \"required_credits\": 1000000,\n \"billingUrl\": \"https://app.recoupable.dev\"\n}\n```\n\n| Field | When it appears | Meaning |\n|-------|-----------------|---------|\n| `error` | Always | Literally `\"insufficient_credits\"` |\n| `remaining_credits` | Always | Account balance at the moment of the failed request |\n| `required_credits` | Always | What this endpoint needed |\n| `billingUrl` | Always | Static link to the Recoup app, where a human can save a card and buy credits |\n\n`billingUrl` is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running.\n\n**How to react:**\n\n- **Browser-driven UI** (e.g., the Recoup chat app): send the customer to `billingUrl`, or call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create) inline and open the `url` it returns.\n- **Programmatic / LLM-driven client**: report `remaining_credits` and `required_credits`, and surface `billingUrl` as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands.\n\n---\n\n## Cost per endpoint\n\nCurrent as of this revision of the page. The authoritative source is the per-endpoint reference docs and the `required_credits` field on any 402 response.\n\n| Endpoint | Cost |\n|----------|------|\n| [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | Variable, priced from the model's token usage; see `required_credits` on a 402 |\n| [Recoup artist and track research](/api-reference/research/search) | \\$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups |\n| [`POST /api/research/people`](/api-reference/research/people) | \\$0.05 per call |\n| [`POST /api/research/web`](/api-reference/research/web) | \\$0.01 per call |\n| [`POST /api/research/extract`](/api-reference/research/extract) | \\$0.05 × number of URLs |\n| [`POST /api/research/enrich`](/api-reference/research/enrich) | \\$0.05 / \\$0.10 / \\$0.25 (base / core / ultra processor) |\n| [`POST /api/research/deep`](/api-reference/research/deep) | \\$0.25 per call |\n| [`POST /api/image/generate`](/api-reference/image/generation) | Per-call price; see endpoint reference |\n| [`POST /api/songs/analyze`](/api-reference/songs/analyze) | `$0.05 + $0.001166 × elapsed_seconds` per model call; `full_report` = 13 calls |\n\n## Billing recovery and units\n\n`insufficient_credits` returns `billingUrl`, a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns `checkoutUrl`; subscription Checkout returns `url`. Inspect the endpoint-specific error type.\n\nTop-ups require `successUrl` on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; `totalCents` is 289 for that example. It is not a credit count. `isPro` means effective Pro only, and is false for paid Starter; use `plan` for paid-plan decisions.\n\nScheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names.\n","headings":[{"title":"What's billed","id":"whats-billed"},{"title":"What a credit is worth","id":"what-a-credit-is-worth"},{"title":"Check your balance","id":"check-your-balance"},{"title":"Subscription","id":"subscription"},{"title":"Running out of credits","id":"running-out-of-credits"},{"title":"402 Payment Required","id":"402-payment-required"},{"title":"Cost per endpoint","id":"cost-per-endpoint"},{"title":"Billing recovery and units","id":"billing-recovery-and-units"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Some Recoup endpoints are billed in \", _jsx(_components.strong, {\n children: \"credits\"\n }), \" — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"whats-billed\",\n children: \"What's billed\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Family\"\n }), _jsx(_components.th, {\n children: \"Billed?\"\n }), _jsx(_components.th, {\n children: \"Notes\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Research\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: _jsx(_components.code, {\n children: \"/api/research/*\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. \", _jsx(_components.a, {\n href: \"/api-reference/research/enrich\",\n children: _jsx(_components.code, {\n children: \"enrich\"\n })\n }), \" charges by processor tier; \", _jsx(_components.a, {\n href: \"/api-reference/research/extract\",\n children: _jsx(_components.code, {\n children: \"extract\"\n })\n }), \" charges by URL count).\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Content generation\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/content/generate-image\",\n children: _jsx(_components.code, {\n children: \"/api/content/image\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/content/generate-video\",\n children: _jsx(_components.code, {\n children: \"video\"\n })\n }), \", upscale, transcribe and analyze)\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"AI Chat — streaming\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/chat/workflow\",\n children: _jsx(_components.code, {\n children: \"POST /api/chat\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Variable cost based on model token usage, with a per-request minimum.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Music analysis\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"$0.05 per model call plus $0.001166 per second of inference time; \", _jsx(_components.code, {\n children: \"full_report\"\n }), \" is the sum of its 13 calls.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Social scrape\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/social/scrape\",\n children: _jsx(_components.code, {\n children: \"/api/socials/{id}/scrape\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/artist/socials-scrape\",\n children: _jsx(_components.code, {\n children: \"/api/artist/socials/scrape\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"$0.05, plus $0.01 per post requested via \", _jsx(_components.code, {\n children: \"posts\"\n }), \" — per social profile scraped.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.strong, {\n children: \"Other operations\"\n })\n }), _jsx(_components.td, {\n children: \"Consult the endpoint contract\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/artists/list\",\n children: \"Artist CRUD\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: \"sandboxes\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/sessions/get\",\n children: \"sessions\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/tasks/get\",\n children: \"scheduled tasks\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: \"account/org management\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/agents/signup\",\n children: \"agent signup\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/spotify/search\",\n children: \"Spotify proxies\"\n }), \", etc. Subscription gating may still apply.\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Upstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"what-a-credit-is-worth\",\n children: \"What a credit is worth\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Balances and prices are US dollars.\"\n }), \" The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: \", _jsx(_components.code, {\n children: \"1,000,000 = $1.00\"\n }), \", so it can carry sub-cent charges (a $0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/credits\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"check-your-balance\",\n children: \"Check your balance\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/credits \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response shape:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"11111111-1111-4111-8111-111111111111\\\",\\n \\\"remaining_credits\\\": 292450000,\\n \\\"total_credits\\\": 300000000,\\n \\\"used_credits\\\": 7550000,\\n \\\"is_pro\\\": true,\\n \\\"plan\\\": \\\"pro\\\",\\n \\\"task_limit\\\": null,\\n \\\"min_cadence_minutes\\\": 60,\\n \\\"timestamp\\\": \\\"2026-10-01T12:00:00Z\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"plan\"\n }), \", \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", and \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" describe the \", _jsx(_components.a, {\n href: \"#subscription\",\n children: \"plan\"\n }), \" the balance belongs to. \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \" is your plan-derived monthly allotment. \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" can exceed \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \" after a top-up or an admin grant, and \", _jsx(_components.code, {\n children: \"used_credits\"\n }), \" clamps to 0 in that case. Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"Get Account Credits\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"plan-response-examples\",\n children: \"Plan response examples\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"is_pro\"\n }), \" on credits and \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" on subscriptions mean effective Pro, so both are\\nfalse for paid Starter. Use \", _jsx(_components.code, {\n children: \"plan\"\n }), \" to distinguish Starter from Free. The credits\\nresponse reports the effective allowance; the \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: \"subscription response\"\n }), \"\\nseparately identifies whether it comes from the account or an organization.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Situation\"\n }), _jsxs(_components.th, {\n children: [\"Credits \", _jsx(_components.code, {\n children: \"plan\"\n }), \" / \", _jsx(_components.code, {\n children: \"is_pro\"\n })]\n }), _jsxs(_components.th, {\n children: [\"Subscription \", _jsx(_components.code, {\n children: \"source\"\n })]\n }), _jsx(_components.th, {\n children: \"Task limit / minimum cadence\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Free\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"free\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"null\"\n })\n }), _jsx(_components.td, {\n children: \"1 / weekly\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Paid Starter\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"starter\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"account\"\n })\n }), _jsx(_components.td, {\n children: \"3 / daily\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Direct Pro\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"pro\"\n }), \" / \", _jsx(_components.code, {\n children: \"true\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"account\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"null\"\n }), \" (unlimited) / hourly\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Starter account with organization Pro\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"pro\"\n }), \" / \", _jsx(_components.code, {\n children: \"true\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"organization\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"null\"\n }), \" (unlimited) / hourly\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Inactive subscription without another paid entitlement\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"free\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"null\"\n })\n }), _jsx(_components.td, {\n children: \"1 / weekly\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For example, a Pro balance of 325,000,000 against an allowance of 300,000,000\\nreturns \", _jsx(_components.code, {\n children: \"used_credits: 0\"\n }), \". The API preserves a signed balance: a negative balance\\ncan make this display exceed the allowance. This is not a ledger of charges.\\nA null timestamp means the timestamp is unavailable, not proof of no prior activity.\\nAn inactive subscription resolves to \", _jsx(_components.code, {\n children: \"status: \\\"none\\\"\"\n }), \" and null subscription/billing\\nfields; this endpoint does not return the canceled subscription's history. Billing\\ndetails may also be unavailable on an active response. Named reference examples\\nillustrate these states without quoting an available offer or a live payment.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To see what consumed the balance, list the charges line by line with \", _jsx(_components.a, {\n href: \"/api-reference/accounts/usage-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/usage\"\n })\n }), \": one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in \", _jsx(_components.code, {\n children: \"model_id\"\n }), \" (for example \", _jsx(_components.code, {\n children: \"POST /api/artist/socials/scrape\"\n }), \"), so a list of charges reads as a list of calls.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"subscription\",\n children: \"Subscription\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For Platform, Advisory, Build + Partner, and Enterprise options, see \", _jsx(_components.a, {\n href: \"https://recoupable.dev/pricing\",\n children: \"Recoup pricing\"\n }), \". API and MCP usage is billed separately through credits.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Your account's current credit allowance and scheduled-task limits are returned by \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"Get Account Credits\"\n }), \". Use \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \", \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", and \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" from that response rather than inferring limits from a public plan name.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The API may return account identifiers such as \", _jsx(_components.code, {\n children: \"free\"\n }), \", \", _jsx(_components.code, {\n children: \"starter\"\n }), \", or \", _jsx(_components.code, {\n children: \"pro\"\n }), \". These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"task-limits\",\n children: \"Task limits\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/tasks/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/tasks\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/tasks/update\",\n children: _jsx(_components.code, {\n children: \"PATCH /api/tasks\"\n })\n }), \" \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"check the plan\"\n }), \" before writing. Creating a task past \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with \", _jsx(_components.code, {\n children: \"error: \\\"plan_limit\\\"\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"status\\\": \\\"error\\\",\\n \\\"error\\\": \\\"plan_limit\\\",\\n \\\"limit\\\": \\\"task_count\\\",\\n \\\"message\\\": \\\"Free includes 1 task. Starter includes 3, Pro is unlimited.\\\",\\n \\\"plan\\\": \\\"free\\\",\\n \\\"task_limit\\\": 1,\\n \\\"min_cadence_minutes\\\": 10080,\\n \\\"current_task_count\\\": 1,\\n \\\"billingUrl\\\": \\\"https://app.recoupable.dev/plan\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"limit\"\n }), \" is \", _jsx(_components.code, {\n children: \"task_count\"\n }), \" or \", _jsx(_components.code, {\n children: \"min_cadence\"\n }), \"; \", _jsx(_components.code, {\n children: \"current_task_count\"\n }), \" excludes the task being created or updated. Edits that only touch \", _jsx(_components.code, {\n children: \"title\"\n }), \", \", _jsx(_components.code, {\n children: \"prompt\"\n }), \", or \", _jsx(_components.code, {\n children: \"model\"\n }), \" never hit the gate.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"monthly-refill\",\n children: \"Monthly refill\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The refill is a \", _jsx(_components.strong, {\n children: \"floor, not an assignment.\"\n }), \" It raises \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a \", _jsx(_components.a, {\n href: \"#one-time-top-ups\",\n children: \"top-up\"\n }), \" or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The refill is lazy rather than scheduled: it applies on the next read of \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/credits\"\n })\n }), \" once your credits row is more than a month old. The balance you read is always the refilled one.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"manage-your-subscription\",\n children: \"Manage your subscription\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sign in to your \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/plan\",\n children: \"account billing page\"\n }), \" to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in \", _jsx(_components.a, {\n href: \"/api-reference/subscriptions/sessions-create\",\n children: \"Create Subscription Session\"\n }), \" and open its returned checkout URL. Review the price and billing terms before completing checkout.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Advisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"check-your-tier\",\n children: \"Check your tier\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/subscription \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Get \", _jsx(_components.code, {\n children: \"$ACCOUNT_ID\"\n }), \" from \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n })\n }), \" if you don't already have it. Response includes \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" (boolean), \", _jsx(_components.code, {\n children: \"status\"\n }), \", \", _jsx(_components.code, {\n children: \"plan\"\n }), \", and \", _jsx(_components.code, {\n children: \"source\"\n }), \" (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: \"Get Subscription\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"one-time-top-ups\",\n children: \"One-time top-ups\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"You can purchase credits any time via \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \". The endpoint adapts to what's on the account:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Card on file → silent auto-charge.\"\n }), \" Recoup charges your saved Stripe card off-session and returns \", _jsx(_components.code, {\n children: \"paymentIntentId\"\n }), \", \", _jsx(_components.code, {\n children: \"creditsPurchased\"\n }), \", and \", _jsx(_components.code, {\n children: \"totalCents\"\n }), \". Credits land within seconds.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"No card, or Stripe declines the saved card → Stripe Checkout fallback.\"\n }), \" The response contains a Checkout \", _jsx(_components.code, {\n children: \"url\"\n }), \" you open in the browser. When Stripe specifically declined a saved card, the response also includes a \", _jsx(_components.code, {\n children: \"declineReason\"\n }), \" (e.g. \", _jsx(_components.code, {\n children: \"insufficient_funds\"\n }), \", \", _jsx(_components.code, {\n children: \"expired_card\"\n }), \") so you can explain \", _jsx(_components.em, {\n children: \"why\"\n }), \" before sending the customer to update billing.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS -X POST https://api.recoupable.dev/api/credits/sessions \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"credits\\\": 1000000, \\\"successUrl\\\": \\\"https://chat.recoupable.dev/credits/success\\\"}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Full request/response schema at \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: \"Create Credits Top-Up Session\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"check-which-card-will-be-charged\",\n children: \"Check which card will be charged\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before triggering a silent off-session charge, inspect the default payment method on file:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/payment-method \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response shape:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"11111111-1111-4111-8111-111111111111\\\",\\n \\\"card\\\": {\\n \\\"brand\\\": \\\"visa\\\",\\n \\\"last4\\\": \\\"4242\\\",\\n \\\"exp_month\\\": 12,\\n \\\"exp_year\\\": 2026,\\n \\\"funding\\\": \\\"credit\\\"\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"card\"\n }), \" is \", _jsx(_components.code, {\n children: \"null\"\n }), \" when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original \", _jsx(_components.code, {\n children: \"exp_month\"\n }), \" / \", _jsx(_components.code, {\n children: \"exp_year\"\n }), \"); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-get\",\n children: \"Get Default Payment Method\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"running-out-of-credits\",\n children: \"Running out of credits\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Every billed API request runs a credit gate before it executes. If \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" doesn't cover the request's cost, the request stops there and returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \". Nothing is charged and no Stripe object is created.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The decision tree:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Enough credits?\"\n }), \" → Request proceeds, credits deducted on success.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Short?\"\n }), \" → Request returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with the balance, the cost, and a link to billing.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \", or when the account has turned on auto top-up. Saving a card ahead of time via \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/accounts/{id}/payment-method\"\n })\n }), \" makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/subscription\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/payment-method\"\n })\n }), \", and \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payments-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/payments\"\n })\n }), \"; pass an organization id as \", _jsx(_components.code, {\n children: \"{id}\"\n }), \" to read the organization's billing.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"auto-top-up-opt-in\",\n children: \"Auto top-up (opt-in)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Auto top-up is off for every account until it is turned on with \", _jsx(_components.a, {\n href: \"/api-reference/accounts/auto-top-up-update\",\n children: _jsx(_components.code, {\n children: \"PUT /api/accounts/{id}/auto-top-up\"\n })\n }), \", which needs three things chosen by the account: \", _jsx(_components.code, {\n children: \"enabled\"\n }), \", the \", _jsx(_components.code, {\n children: \"amountCents\"\n }), \" to buy each time (5.00 to 1,000.00 USD), and the \", _jsx(_components.code, {\n children: \"thresholdCents\"\n }), \" balance that triggers it. Both are USD cents; the \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as \", _jsx(_components.code, {\n children: \"lastError\"\n }), \" (returned by \", _jsx(_components.a, {\n href: \"/api-reference/accounts/auto-top-up-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/auto-top-up\"\n })\n }), \"), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"remove-a-saved-card\",\n children: \"Remove a saved card\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-delete\",\n children: _jsx(_components.code, {\n children: \"DELETE /api/accounts/{id}/payment-method\"\n })\n }), \" turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Success returns \", _jsx(_components.strong, {\n children: \"204\"\n }), \" with no body. If no customer or selected card exists, \", _jsx(_components.strong, {\n children: \"404\"\n }), \" leaves settings and cards unchanged. A \", _jsx(_components.strong, {\n children: \"500\"\n }), \" can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"402-payment-required\",\n children: \"402 Payment Required\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"When the gate comes up short, billed endpoints return \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with a unified body:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"error\\\": \\\"insufficient_credits\\\",\\n \\\"remaining_credits\\\": 120000,\\n \\\"required_credits\\\": 1000000,\\n \\\"billingUrl\\\": \\\"https://app.recoupable.dev\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Field\"\n }), _jsx(_components.th, {\n children: \"When it appears\"\n }), _jsx(_components.th, {\n children: \"Meaning\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"error\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsxs(_components.td, {\n children: [\"Literally \", _jsx(_components.code, {\n children: \"\\\"insufficient_credits\\\"\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"remaining_credits\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"Account balance at the moment of the failed request\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"required_credits\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"What this endpoint needed\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"billingUrl\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"Static link to the Recoup app, where a human can save a card and buy credits\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"billingUrl\"\n }), \" is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"How to react:\"\n })\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Browser-driven UI\"\n }), \" (e.g., the Recoup chat app): send the customer to \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \", or call \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \" inline and open the \", _jsx(_components.code, {\n children: \"url\"\n }), \" it returns.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Programmatic / LLM-driven client\"\n }), \": report \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" and \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \", and surface \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \" as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"cost-per-endpoint\",\n children: \"Cost per endpoint\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Current as of this revision of the page. The authoritative source is the per-endpoint reference docs and the \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \" field on any 402 response.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Endpoint\"\n }), _jsx(_components.th, {\n children: \"Cost\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/chat/workflow\",\n children: _jsx(_components.code, {\n children: \"POST /api/chat\"\n })\n }), \" (streaming)\"]\n }), _jsxs(_components.td, {\n children: [\"Variable, priced from the model's token usage; see \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \" on a 402\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/search\",\n children: \"Recoup artist and track research\"\n })\n }), _jsx(_components.td, {\n children: \"$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/people\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/people\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/web\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.01 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/extract\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/extract\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 × number of URLs\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/enrich\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/enrich\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 / $0.10 / $0.25 (base / core / ultra processor)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/deep\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/deep\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.25 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/image/generation\",\n children: _jsx(_components.code, {\n children: \"POST /api/image/generate\"\n })\n })\n }), _jsx(_components.td, {\n children: \"Per-call price; see endpoint reference\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"$0.05 + $0.001166 × elapsed_seconds\"\n }), \" per model call; \", _jsx(_components.code, {\n children: \"full_report\"\n }), \" = 13 calls\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"billing-recovery-and-units\",\n children: \"Billing recovery and units\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"insufficient_credits\"\n }), \" returns \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \", a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns \", _jsx(_components.code, {\n children: \"checkoutUrl\"\n }), \"; subscription Checkout returns \", _jsx(_components.code, {\n children: \"url\"\n }), \". Inspect the endpoint-specific error type.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Top-ups require \", _jsx(_components.code, {\n children: \"successUrl\"\n }), \" on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; \", _jsx(_components.code, {\n children: \"totalCents\"\n }), \" is 289 for that example. It is not a credit count. \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" means effective Pro only, and is false for paid Starter; use \", _jsx(_components.code, {\n children: \"plan\"\n }), \" for paid-plan decisions.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Scheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Credits How Recoup credits work — what's billed, how to check your balance, and how to upgrade. Quickstart Getting started Some Recoup endpoints are billed in **credits** — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates. --- ## What's billed | Family | Billed? | Notes | |--------|---------|-------| | **Research** ([`/api/research/*`](/api-reference/research/web)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). | | **Content generation** ([`/api/content/image`](/api-reference/content/generate-image), [`video`](/api-reference/content/generate-video), upscale, transcribe and analyze) | Yes | Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory. | | **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. | | **Music analysis** ([`POST /api/songs/analyze`](/api-reference/songs/analyze)) | Yes | \\$0.05 per model call plus \\$0.001166 per second of inference time; `full_report` is the sum of its 13 calls. | | **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | \\$0.05, plus \\$0.01 per post requested via `posts` — per social profile scraped. | | **Other operations** | Consult the endpoint contract | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. | Upstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient. --- ## What a credit is worth **Balances and prices are US dollars.** The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: `1,000,000 = $1.00`, so it can carry sub-cent charges (a \\$0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get). --- ## Check your balance Response shape: `plan`, `task_limit`, and `min_cadence_minutes` describe the [plan](#subscription) the balance belongs to. `total_credits` is your plan-derived monthly allotment. `remaining_credits` can exceed `total_credits` after a top-up or an admin grant, and `used_credits` clamps to 0 in that case. Full schema at [Get Account Credits](/api-reference/accounts/credits-get). ### Plan response examples `is_pro` on credits and `isPro` on subscriptions mean effective Pro, so both are false for paid Starter. Use `plan` to distinguish Starter from Free. The credits response reports the effective allowance; the [subscription response](/api-reference/accounts/subscription-get) separately identifies whether it comes from the account or an organization. | Situation | Credits `plan` / `is_pro` | Subscription `source` | Task limit / minimum cadence | | --- | --- | --- | --- | | Free | `free` / `false` | `null` | 1 / weekly | | Paid Starter | `starter` / `false` | `account` | 3 / daily | | Direct Pro | `pro` / `true` | `account` | `null` (unlimited) / hourly | | Starter account with organization Pro | `pro` / `true` | `organization` | `null` (unlimited) / hourly | | Inactive subscription without another paid entitlement | `free` / `false` | `null` | 1 / weekly | For example, a Pro balance of 325,000,000 against an allowance of 300,000,000 returns `used_credits: 0`. The API preserves a signed balance: a negative balance can make this display exceed the allowance. This is not a ledger of charges. A null timestamp means the timestamp is unavailable, not proof of no prior activity. An inactive subscription resolves to `status: \"none\"` and null subscription/billing fields; this endpoint does not return the canceled subscription's history. Billing details may also be unavailable on an active response. Named reference examples illustrate these states without quoting an available offer or a live payment. To see what consumed the balance, list the charges line by line with [`GET /api/accounts/{id}/usage`](/api-reference/accounts/usage-get): one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in `model_id` (for example `POST /api/artist/socials/scrape`), so a list of charges reads as a list of calls. --- ## Subscription For Platform, Advisory, Build + Partner, and Enterprise options, see [Recoup pricing](https://recoupable.dev/pricing). API and MCP usage is billed separately through credits. Your account's current credit allowance and scheduled-task limits are returned by [Get Account Credits](/api-reference/accounts/credits-get). Use `total_credits`, `task_limit`, and `min_cadence_minutes` from that response rather than inferring limits from a public plan name. The API may return account identifiers such as `free`, `starter`, or `pro`. These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint. ### Task limits [`POST /api/tasks`](/api-reference/tasks/create) and [`PATCH /api/tasks`](/api-reference/tasks/update) [check the plan](/api-reference/accounts/credits-get) before writing. Creating a task past `task_limit`, re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than `min_cadence_minutes` returns **HTTP 402** with `error: \"plan_limit\"`: `limit` is `task_count` or `min_cadence`; `current_task_count` excludes the task being created or updated. Edits that only touch `title`, `prompt`, or `model` never hit the gate. ### Monthly refill The refill is a **floor, not an assignment.** It raises `remaining_credits` up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a [top-up](#one-time-top-ups) or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar. The refill is lazy rather than scheduled: it applies on the next read of [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get) once your credits row is more than a month old. The balance you read is always the refilled one. ### Manage your subscription Sign in to your [account billing page](https://app.recoupable.dev/plan) to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in [Create Subscription Session](/api-reference/subscriptions/sessions-create) and open its returned checkout URL. Review the price and billing terms before completing checkout. Advisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment. ### Check your tier Get `$ACCOUNT_ID` from [`GET /api/accounts/id`](/api-reference/accounts/id) if you don't already have it. Response includes `isPro` (boolean), `status`, `plan`, and `source` (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at [Get Subscription](/api-reference/accounts/subscription-get). ### One-time top-ups You can purchase credits any time via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create). The endpoint adapts to what's on the account: - **Card on file → silent auto-charge.** Recoup charges your saved Stripe card off-session and returns `paymentIntentId`, `creditsPurchased`, and `totalCents`. Credits land within seconds. - **No card, or Stripe declines the saved card → Stripe Checkout fallback.** The response contains a Checkout `url` you open in the browser. When Stripe specifically declined a saved card, the response also includes a `declineReason` (e.g. `insufficient_funds`, `expired_card`) so you can explain *why* before sending the customer to update billing. Full request/response schema at [Create Credits Top-Up Session](/api-reference/credits/sessions-create). ### Check which card will be charged Before triggering a silent off-session charge, inspect the default payment method on file: Response shape: `card` is `null` when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original `exp_month` / `exp_year`); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at [Get Default Payment Method](/api-reference/accounts/payment-method-get). --- ## Running out of credits Every billed API request runs a credit gate before it executes. If `remaining_credits` doesn't cover the request's cost, the request stops there and returns **HTTP 402**. Nothing is charged and no Stripe object is created. The decision tree: 1. **Enough credits?** → Request proceeds, credits deducted on success. 2. **Short?** → Request returns **HTTP 402** with the balance, the cost, and a link to billing. A card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through [`POST /api/credits/sessions`](/api-reference/credits/sessions-create), or when the account has turned on auto top-up. Saving a card ahead of time via [`POST /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-create) makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on [`/api/accounts/{id}/subscription`](/api-reference/accounts/subscription-get), [`/api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-get), and [`/api/accounts/{id}/payments`](/api-reference/accounts/payments-get); pass an organization id as `{id}` to read the organization's billing. ### Auto top-up (opt-in) Auto top-up is off for every account until it is turned on with [`PUT /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-update), which needs three things chosen by the account: `enabled`, the `amountCents` to buy each time (5.00 to 1,000.00 USD), and the `thresholdCents` balance that triggers it. Both are USD cents; the `remaining_credits` balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file. Once on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as `lastError` (returned by [`GET /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-get)), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself. ### Remove a saved card [`DELETE /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-delete) turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again. Success returns **204** with no body. If no customer or selected card exists, **404** leaves settings and cards unchanged. A **500** can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card. This operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently. --- ## 402 Payment Required When the gate comes up short, billed endpoints return **HTTP 402** with a unified body: | Field | When it appears | Meaning | |-------|-----------------|---------| | `error` | Always | Literally `\"insufficient_credits\"` | | `remaining_credits` | Always | Account balance at the moment of the failed request | | `required_credits` | Always | What this endpoint needed | | `billingUrl` | Always | Static link to the Recoup app, where a human can save a card and buy credits | `billingUrl` is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running. **How to react:** - **Browser-driven UI** (e.g., the Recoup chat app): send the customer to `billingUrl`, or call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create) inline and open the `url` it returns. - **Programmatic / LLM-driven client**: report `remaining_credits` and `required_credits`, and surface `billingUrl` as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands. --- ## Cost per endpoint Current as of this revision of the page. The authoritative source is the per-endpoint reference docs and the `required_credits` field on any 402 response. | Endpoint | Cost | |----------|------| | [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | Variable, priced from the model's token usage; see `required_credits` on a 402 | | [Recoup artist and track research](/api-reference/research/search) | \\$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups | | [`POST /api/research/people`](/api-reference/research/people) | \\$0.05 per call | | [`POST /api/research/web`](/api-reference/research/web) | \\$0.01 per call | | [`POST /api/research/extract`](/api-reference/research/extract) | \\$0.05 × number of URLs | | [`POST /api/research/enrich`](/api-reference/research/enrich) | \\$0.05 / \\$0.10 / \\$0.25 (base / core / ultra processor) | | [`POST /api/research/deep`](/api-reference/research/deep) | \\$0.25 per call | | [`POST /api/image/generate`](/api-reference/image/generation) | Per-call price; see endpoint reference | | [`POST /api/songs/analyze`](/api-reference/songs/analyze) | `$0.05 + $0.001166 × elapsed_seconds` per model call; `full_report` = 13 calls | ## Billing recovery and units `insufficient_credits` returns `billingUrl`, a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns `checkoutUrl`; subscription Checkout returns `url`. Inspect the endpoint-specific error type. Top-ups require `successUrl` on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; `totalCents` is 289 for that example. It is not a credit count. `isPro` means effective Pro only, and is false for paid Starter; use `plan` for paid-plan decisions. Scheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names. "},{"slug":"research-availability","title":"Research availability","description":"Explore Recoup research, choose the right identifiers, and handle incomplete data.","category":"Quickstart","group":"Getting started","source":"research-availability.mdx","body":"Recoup Research lets you discover artists and tracks, read current metrics,\nexplore audience and playlist activity, and capture recording measurements.\nAuthenticate with your Recoup API key or supported bearer credential. Recoup\nmanages the data connections; you do not need a separate data-service key.\n\nCoverage varies by artist, recording, platform and metric. An empty result means\nno matching data was returned; it does not prove an artist has no activity or audience.\n\n## Choose an identifier\n\nSearch by name, inspect the matches, and pass the selected result's `id` to the\ndetail endpoints. Treat research IDs as opaque strings: do not parse them or\nsubstitute a Recoup account UUID. Artist-name shortcuts use the first match;\nselect an explicit ID when names are ambiguous.\n\nFor portable recording references, store the ISRC and available Spotify or\nApple Music identifiers. Additional response fields and provenance labels may\nvary as Recoup's data connections change. Preserve returned provenance for\ntraceability without using it to choose a data vendor.\n\n## Current track statistics\n\nSupply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus\nthe required `source` (the platform, such as `spotify`). Recoup uses stored\nSpotify measurements when available for an ISRC, and otherwise requests current\nresearch data. Preserve `data_source` and capture timestamps when returned;\nmissing provenance remains unknown. A displayed play count is not a verified\nroyalty-bearing stream count.\n\n## Research endpoints\n\n| Method | Path | Reference |\n| --- | --- | --- |\n| GET | `/api/research` | [Search](/api-reference/research/search) |\n| GET | `/api/research/albums` | [Albums](/api-reference/research/albums) |\n| GET | `/api/research/audience` | [Audience](/api-reference/research/audience) |\n| GET | `/api/research/career` | [Career activities](/api-reference/research/career) |\n| GET | `/api/research/insights` | [Insights activities](/api-reference/research/insights) |\n| GET | `/api/research/lookup` | [Spotify artist lookup](/api-reference/research/lookup) |\n| GET | `/api/research/metrics` | [Current artist metrics](/api-reference/research/metrics) |\n| GET | `/api/research/milestones` | [Milestones](/api-reference/research/milestones) |\n| GET | `/api/research/playlists` | [Artist playlists](/api-reference/research/playlists) |\n| GET | `/api/research/profile` | [Artist profile](/api-reference/research/profile) |\n| GET | `/api/research/similar` | [Related artists](/api-reference/research/similar) |\n| GET | `/api/research/track` | [Track details](/api-reference/research/track) |\n| GET | `/api/research/track/playlists` | [Track playlists](/api-reference/research/track-playlists) |\n| GET | `/api/research/tracks` | [Artist tracks](/api-reference/research/tracks) |\n| GET | `/api/research/urls` | [Platform URLs](/api-reference/research/urls) |\n\n## Understand the results\n\n- Artist metrics are current snapshots. Save dated results to compare them over time.\n- Related artists are unweighted; the accepted similarity axes do not change the ranking.\n- Artist playlist `status=past` uses all-time scope and can include current placements.\n- Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.\n- Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.\n- Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.\n\n## Historical measurement jobs\n\n`POST /api/research/measurement-jobs` supports `source: \"historical\"`\nfor Spotify backfill. It requires a card on file and returns queue counts with\n`id: null`; enqueueing does not confirm capture completion. Recordings with an\nexisting historical research measurement can be skipped even when their history\nis partial. Inspect the available dates before claiming complete coverage.\nCurrent capture jobs return a snapshot ID.\n\n## Costs and unavailable data\n\nSuccessful research calls cost $0.05 (50,000 micro-dollar credits). Track-name\nresolution can add separately charged lookup calls; reuse a selected research\nID when available. Historical enqueue itself does not deduct research credits;\ncapture work has its own balance and budget checks.\n\nFor `402 insufficient_credits`, show the returned `billingUrl`. Surface `429`\nand unavailable-data errors; use bounded retries for transient failures and stop\nwhen the request cannot be served. Recoup does not promise a `Retry-After` header\non these routes. Never fill a missing metric with an invented number or zero.\n","headings":[{"title":"Choose an identifier","id":"choose-an-identifier"},{"title":"Current track statistics","id":"current-track-statistics"},{"title":"Research endpoints","id":"research-endpoints"},{"title":"Understand the results","id":"understand-the-results"},{"title":"Historical measurement jobs","id":"historical-measurement-jobs"},{"title":"Costs and unavailable data","id":"costs-and-unavailable-data"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Recoup Research lets you discover artists and tracks, read current metrics,\\nexplore audience and playlist activity, and capture recording measurements.\\nAuthenticate with your Recoup API key or supported bearer credential. Recoup\\nmanages the data connections; you do not need a separate data-service key.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Coverage varies by artist, recording, platform and metric. An empty result means\\nno matching data was returned; it does not prove an artist has no activity or audience.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"choose-an-identifier\",\n children: \"Choose an identifier\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Search by name, inspect the matches, and pass the selected result's \", _jsx(_components.code, {\n children: \"id\"\n }), \" to the\\ndetail endpoints. Treat research IDs as opaque strings: do not parse them or\\nsubstitute a Recoup account UUID. Artist-name shortcuts use the first match;\\nselect an explicit ID when names are ambiguous.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For portable recording references, store the ISRC and available Spotify or\\nApple Music identifiers. Additional response fields and provenance labels may\\nvary as Recoup's data connections change. Preserve returned provenance for\\ntraceability without using it to choose a data vendor.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"current-track-statistics\",\n children: \"Current track statistics\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Supply exactly one of \", _jsx(_components.code, {\n children: \"isrc\"\n }), \", \", _jsx(_components.code, {\n children: \"spotify_track_id\"\n }), \", or \", _jsx(_components.code, {\n children: \"apple_music_track_id\"\n }), \", plus\\nthe required \", _jsx(_components.code, {\n children: \"source\"\n }), \" (the platform, such as \", _jsx(_components.code, {\n children: \"spotify\"\n }), \"). Recoup uses stored\\nSpotify measurements when available for an ISRC, and otherwise requests current\\nresearch data. Preserve \", _jsx(_components.code, {\n children: \"data_source\"\n }), \" and capture timestamps when returned;\\nmissing provenance remains unknown. A displayed play count is not a verified\\nroyalty-bearing stream count.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"research-endpoints\",\n children: \"Research endpoints\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Method\"\n }), _jsx(_components.th, {\n children: \"Path\"\n }), _jsx(_components.th, {\n children: \"Reference\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/search\",\n children: \"Search\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/albums\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/albums\",\n children: \"Albums\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/audience\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/audience\",\n children: \"Audience\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/career\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/career\",\n children: \"Career activities\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/insights\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/insights\",\n children: \"Insights activities\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/lookup\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/lookup\",\n children: \"Spotify artist lookup\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/metrics\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/metrics\",\n children: \"Current artist metrics\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/milestones\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/milestones\",\n children: \"Milestones\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/playlists\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/playlists\",\n children: \"Artist playlists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/profile\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/profile\",\n children: \"Artist profile\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/similar\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/similar\",\n children: \"Related artists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/track\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/track\",\n children: \"Track details\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/track/playlists\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/track-playlists\",\n children: \"Track playlists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/tracks\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/tracks\",\n children: \"Artist tracks\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/urls\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/urls\",\n children: \"Platform URLs\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"understand-the-results\",\n children: \"Understand the results\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Artist metrics are current snapshots. Save dated results to compare them over time.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Related artists are unweighted; the accepted similarity axes do not change the ranking.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Artist playlist \", _jsx(_components.code, {\n children: \"status=past\"\n }), \" uses all-time scope and can include current placements.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"historical-measurement-jobs\",\n children: \"Historical measurement jobs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/research/measurement-jobs\"\n }), \" supports \", _jsx(_components.code, {\n children: \"source: \\\"historical\\\"\"\n }), \"\\nfor Spotify backfill. It requires a card on file and returns queue counts with\\n\", _jsx(_components.code, {\n children: \"id: null\"\n }), \"; enqueueing does not confirm capture completion. Recordings with an\\nexisting historical research measurement can be skipped even when their history\\nis partial. Inspect the available dates before claiming complete coverage.\\nCurrent capture jobs return a snapshot ID.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"costs-and-unavailable-data\",\n children: \"Costs and unavailable data\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name\\nresolution can add separately charged lookup calls; reuse a selected research\\nID when available. Historical enqueue itself does not deduct research credits;\\ncapture work has its own balance and budget checks.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For \", _jsx(_components.code, {\n children: \"402 insufficient_credits\"\n }), \", show the returned \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \". Surface \", _jsx(_components.code, {\n children: \"429\"\n }), \"\\nand unavailable-data errors; use bounded retries for transient failures and stop\\nwhen the request cannot be served. Recoup does not promise a \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" header\\non these routes. Never fill a missing metric with an invented number or zero.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Research availability Explore Recoup research, choose the right identifiers, and handle incomplete data. Quickstart Getting started Recoup Research lets you discover artists and tracks, read current metrics, explore audience and playlist activity, and capture recording measurements. Authenticate with your Recoup API key or supported bearer credential. Recoup manages the data connections; you do not need a separate data-service key. Coverage varies by artist, recording, platform and metric. An empty result means no matching data was returned; it does not prove an artist has no activity or audience. ## Choose an identifier Search by name, inspect the matches, and pass the selected result's `id` to the detail endpoints. Treat research IDs as opaque strings: do not parse them or substitute a Recoup account UUID. Artist-name shortcuts use the first match; select an explicit ID when names are ambiguous. For portable recording references, store the ISRC and available Spotify or Apple Music identifiers. Additional response fields and provenance labels may vary as Recoup's data connections change. Preserve returned provenance for traceability without using it to choose a data vendor. ## Current track statistics Supply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus the required `source` (the platform, such as `spotify`). Recoup uses stored Spotify measurements when available for an ISRC, and otherwise requests current research data. Preserve `data_source` and capture timestamps when returned; missing provenance remains unknown. A displayed play count is not a verified royalty-bearing stream count. ## Research endpoints | Method | Path | Reference | | --- | --- | --- | | GET | `/api/research` | [Search](/api-reference/research/search) | | GET | `/api/research/albums` | [Albums](/api-reference/research/albums) | | GET | `/api/research/audience` | [Audience](/api-reference/research/audience) | | GET | `/api/research/career` | [Career activities](/api-reference/research/career) | | GET | `/api/research/insights` | [Insights activities](/api-reference/research/insights) | | GET | `/api/research/lookup` | [Spotify artist lookup](/api-reference/research/lookup) | | GET | `/api/research/metrics` | [Current artist metrics](/api-reference/research/metrics) | | GET | `/api/research/milestones` | [Milestones](/api-reference/research/milestones) | | GET | `/api/research/playlists` | [Artist playlists](/api-reference/research/playlists) | | GET | `/api/research/profile` | [Artist profile](/api-reference/research/profile) | | GET | `/api/research/similar` | [Related artists](/api-reference/research/similar) | | GET | `/api/research/track` | [Track details](/api-reference/research/track) | | GET | `/api/research/track/playlists` | [Track playlists](/api-reference/research/track-playlists) | | GET | `/api/research/tracks` | [Artist tracks](/api-reference/research/tracks) | | GET | `/api/research/urls` | [Platform URLs](/api-reference/research/urls) | ## Understand the results - Artist metrics are current snapshots. Save dated results to compare them over time. - Related artists are unweighted; the accepted similarity axes do not change the ranking. - Artist playlist `status=past` uses all-time scope and can include current placements. - Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline. - Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album. - Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied. ## Historical measurement jobs `POST /api/research/measurement-jobs` supports `source: \"historical\"` for Spotify backfill. It requires a card on file and returns queue counts with `id: null`; enqueueing does not confirm capture completion. Recordings with an existing historical research measurement can be skipped even when their history is partial. Inspect the available dates before claiming complete coverage. Current capture jobs return a snapshot ID. ## Costs and unavailable data Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name resolution can add separately charged lookup calls; reuse a selected research ID when available. Historical enqueue itself does not deduct research credits; capture work has its own balance and budget checks. For `402 insufficient_credits`, show the returned `billingUrl`. Surface `429` and unavailable-data errors; use bounded retries for transient failures and stop when the request cannot be served. Recoup does not promise a `Retry-After` header on these routes. Never fill a missing metric with an invented number or zero. "},{"slug":"workflows/create-artist","title":"Create a New Artist","description":"End-to-end workflow to create, research and enrich a new artist account in a single session.","category":"Artists","group":"Workflows","source":"workflows/create-artist.mdx","body":"This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \"researched + enriched\" parity from a sandbox or any external agent.\n\nThe chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.\n\n## Prerequisites\n\n- `$RECOUP_API_KEY` (`x-api-key`) or `$RECOUP_ACCESS_TOKEN` (Privy Bearer JWT) for `api.recoupable.dev`\n- `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes)\n- An artist name to create (e.g. `ARTIST_NAME=\"The Weeknd\"`)\n\nSelect one credential obtained through the approved real-account REST setup:\n\n```bash\nif [ -n \"$RECOUP_API_KEY\" ]; then\n AUTH=(-H \"x-api-key: $RECOUP_API_KEY\")\nelif [ -n \"$RECOUP_ACCESS_TOKEN\" ]; then\n AUTH=(-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\")\nelse\n echo \"Authenticate REST through the approved real-account setup flow.\" >&2\n exit 1\nfi\n```\n\nUse your real account and selected organization. Do not create a disposable\n`agent+` identity or paste credentials into the workspace file.\n\nThe flow has three phases, run from a single checklist file:\n\n1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match\n2. **Enrich** — `PATCH` the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials\n3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array\n\n## Step 0: Scaffold the workspace BEFORE any API call\n\nPick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:\n\n```bash\nARTIST_SLUG=$(echo \"$ARTIST_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\\+/-/g; s/^-//; s/-$//')\nARTIST_DIR=\"artists/$ARTIST_SLUG\"\nmkdir -p \"$ARTIST_DIR\"\n\ncat > \"$ARTIST_DIR/RECOUP.md\" <&2\n return 1 ;;\n 429)\n retry_after=$(awk 'tolower($1)==\"retry-after:\" {sub(/^[^:]*:[[:space:]]*/, \"\"); sub(/\\r$/, \"\"); print}' \"$headers\")\n rm -f \"$headers\"\n printf 'Research step stopped. Retry-After: %s. Resume manually when allowed.\\n' \"${retry_after:-not provided}\" >&2\n return 1 ;;\n 5??) ;;\n *) rm -f \"$headers\"; printf 'Research HTTP %s; resolve before resuming.\\n' \"$status\" >&2; return 1 ;;\n esac\n fi\n if [ \"$attempt\" -lt 3 ]; then sleep \"$((attempt * 2))\"; fi\n done\n rm -f \"$headers\"\n echo 'Research unavailable after three attempts.' >&2\n return 1\n}\n```\n\n### 4a: Resolve the research artist ID\n\n```bash\nLOOKUP=$(research_request lookup --get \\\n --data-urlencode \"spotifyId=$SPOTIFY_ARTIST_ID\") || exit 1\n\nRESEARCH_ARTIST_ID=$(printf '%s' \"$LOOKUP\" | jq -r \\\n '[.id, .artist_info.id] | map(select(type == \"string\") | select(test(\"\\\\S\"))) | first // empty')\n```\n\nSave this value as `researchArtistId`. It is separate from the Recoup artist\naccount UUID and Spotify ID. Do not coerce it to a number or copy an older\nsaved research ID into it; re-resolve and verify older workspaces. If a successful\nlookup has no usable `id`, record that gap and skip 4b–4d, then run 4e.\n\nSee [Artist Lookup](/api-reference/research/lookup) for the response contract.\n\n### 4b–4d: Read available structured signals\n\n```bash\nif [ -n \"$RESEARCH_ARTIST_ID\" ]; then\n PROFILE=$(research_request profile --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\n CAREER=$(research_request career --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\n PLAYLISTS=$(research_request playlists --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\nfi\n```\n\nInspect the fields actually returned. Profile data may be partial; `career` is\nan available activity feed, not a guaranteed complete career timeline.\n`playlists` returns `placements`, which may be empty. Do not turn missing data\ninto zero or infer a label, achievement or placement that is absent.\n\nSee [Artist Profile](/api-reference/research/profile),\n[Artist Activity](/api-reference/research/career) and\n[Playlist Placements](/api-reference/research/playlists).\n\n### 4e: Search for narrative, press and collaborations\n\n```bash\nRESEARCH_WEB=$(research_request web -X POST \\\n -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg name \"$ARTIST_NAME\" \\\n '{query: ($name + \" biography press recent collaborations\")}')\") || exit 1\n```\n\nVerify source links before asserting a fact. See [Web Search](/api-reference/research/web).\n\n**After this step:** persist `researchArtistId` when available. Save the returned\npayloads, source links and coverage gaps under `## Research` in `RECOUP.md`, with\none subsection per request. Tick step 4 only after the successful reads and any\nintentional structured-data skip have been recorded.\n\n## Step 5: Pull the Spotify catalog\n\n```bash\nTOP_TRACKS=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/artist/topTracks\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$SPOTIFY_ARTIST_ID\")\n\nALBUMS=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/artist/albums\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$SPOTIFY_ARTIST_ID\")\n\n# For each notable album, drill in (ALBUM_ID from $ALBUMS):\nALBUM_DETAIL=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/album\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$ALBUM_ID\")\n```\n\n`$SPOTIFY_ARTIST_ID` is the value you exported in step 2.\n\nSee [Spotify Top Tracks](/api-reference/spotify/artist-top-tracks), [Spotify Artist Albums](/api-reference/spotify/artist-albums), and [Spotify Album](/api-reference/spotify/album) for full schemas.\n\n**After this step:** populate the artist's `releases/` folder — write one `releases/{release-slug}/RELEASE.md` per album (album slugs are bare, `-ep` / `-single` / `-compilation` suffixes for other types) using the per-album `GET /api/spotify/album?id=$ALBUM_ID` response, and write the top tracks snapshot to `releases/top-tracks.md`. `RELEASE.md` is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as `⚠️ TBD`. The full template + the field-by-field Spotify mapping live in the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill at `references/release-template.md`. Tick `- [ ] 5.` → `- [x] 5.`.\n\n## Step 6: Search the web for additional socials\n\n```bash\nSOCIALS_SEARCH=$(curl -sS -X POST \"https://api.recoupable.dev/api/research/web\" \\\n \"${AUTH[@]}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg name \"$ARTIST_NAME\" \\\n '{query: ($name + \" official instagram tiktok twitter youtube\")}')\")\n```\n\nParse the results to extract any new social URLs whose host matches the platform reference table below.\n\nSee [Web Search](/api-reference/research/web) for the request/response schema.\n\n**After this step:** save the discovered URLs (one per platform) into the `## Notes` section so step 7 can read them without re-querying. Tick `- [ ] 6.` → `- [x] 6.`.\n\n## Step 7: PATCH the artist with the discovered socials\n\n```bash\ncurl -sS -X PATCH \"https://api.recoupable.dev/api/artists/$ARTIST_ID\" \\\n \"${AUTH[@]}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"profileUrls\": {\n \"INSTAGRAM\": \"https://instagram.com/...\",\n \"TIKTOK\": \"https://tiktok.com/@...\",\n \"TWITTER\": \"https://x.com/...\",\n \"YOUTUBE\": \"https://youtube.com/@...\"\n }\n }'\n```\n\nOnly include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally.\n\nSee [Update Artist](/api-reference/artists/update) for the full body schema.\n\n**After this step:** tick `- [ ] 7.` → `- [x] 7.`.\n\n## Step 8: Synthesize the knowledge base\n\nCombine the available structured and web research (`## Research` section), the Spotify catalog (`releases/`), and the discovered socials into a comprehensive markdown report. Recommended sections:\n\n- Artist biography and origin\n- Discography highlights (top tracks + key albums)\n- Spotify presence (genres, listener count, notable playlists)\n- Social media footprint\n- Recent activity / press\n- Notable collaborations and achievements\n\nAppend the report to the same `RECOUP.md` you scaffolded in Step 0 — add it as a `## Knowledge base` section below the checklist. The path is:\n\n```\nartists/$ARTIST_SLUG/RECOUP.md\n```\n\nThis dovetails with the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL.\n\n**After this step:** tick `- [ ] 8.` → `- [x] 8.`. With every box ticked, the artist is fully set up.\n\n## Platform key reference\n\n`profileUrls` keys are **uppercase** platform identifiers, inferred from the URL host. Recognized platforms:\n\n| URL contains | `profileUrls` key |\n| ---------------------------- | ----------------- |\n| `spotify.com` | `SPOTIFY` |\n| `instagram.com` | `INSTAGRAM` |\n| `tiktok.com` | `TIKTOK` |\n| `x.com`, `twitter.com` | `TWITTER` |\n| `youtube.` | `YOUTUBE` |\n| `apple.com` | `APPLE` |\n| `facebook.com` | `FACEBOOK` |\n| `threads.net`, `threads.com` | `THREADS` |\n\nURLs that don't match any of these are silently skipped — they won't be saved.\n\n## What this workflow doesn't enforce\n\nThere's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The `RECOUP.md` checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't.\n\nA few constraints to honor:\n\n- **Run steps in order.** The frontmatter values written at one step are the inputs for later steps.\n- **Don't continue past a 4xx/5xx without recovery.** Leave the box unchecked, write the error to `## Notes`, and resolve before resuming.\n- **Treat the file as the source of truth.** If something isn't on disk, don't assume it ran.\n","headings":[{"title":"Prerequisites","id":"prerequisites"},{"title":"Step 0: Scaffold the workspace BEFORE any API call","id":"step-0-scaffold-the-workspace-before-any-api-call"},{"title":"Resuming a partial setup","id":"resuming-a-partial-setup"},{"title":"Step 1: Create the artist","id":"step-1-create-the-artist"},{"title":"Step 2: Find the canonical Spotify match","id":"step-2-find-the-canonical-spotify-match"},{"title":"Step 3: Set basic profile + Spotify URL","id":"step-3-set-basic-profile-spotify-url"},{"title":"Step 4: Run Recoup research","id":"step-4-run-recoup-research"},{"title":"Step 5: Pull the Spotify catalog","id":"step-5-pull-the-spotify-catalog"},{"title":"Step 6: Search the web for additional socials","id":"step-6-search-the-web-for-additional-socials"},{"title":"Step 7: PATCH the artist with the discovered socials","id":"step-7-patch-the-artist-with-the-discovered-socials"},{"title":"Step 8: Synthesize the knowledge base","id":"step-8-synthesize-the-knowledge-base"},{"title":"Platform key reference","id":"platform-key-reference"},{"title":"What this workflow doesn't enforce","id":"what-this-workflow-doesnt-enforce"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \\\"researched + enriched\\\" parity from a sandbox or any external agent.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, \", _jsx(_components.strong, {\n children: \"drive the work from a checklist file\"\n }), \": scaffold the artist's \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"prerequisites\",\n children: \"Prerequisites\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$RECOUP_API_KEY\"\n }), \" (\", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \") or \", _jsx(_components.code, {\n children: \"$RECOUP_ACCESS_TOKEN\"\n }), \" (Privy Bearer JWT) for \", _jsx(_components.code, {\n children: \"api.recoupable.dev\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$RECOUP_ORG_ID\"\n }), \" — the org the artist should belong to (recommended in sandboxes)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"An artist name to create (e.g. \", _jsx(_components.code, {\n children: \"ARTIST_NAME=\\\"The Weeknd\\\"\"\n }), \")\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Select one credential obtained through the approved real-account REST setup:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"if [ -n \\\"$RECOUP_API_KEY\\\" ]; then\\n AUTH=(-H \\\"x-api-key: $RECOUP_API_KEY\\\")\\nelif [ -n \\\"$RECOUP_ACCESS_TOKEN\\\" ]; then\\n AUTH=(-H \\\"Authorization: Bearer $RECOUP_ACCESS_TOKEN\\\")\\nelse\\n echo \\\"Authenticate REST through the approved real-account setup flow.\\\" >&2\\n exit 1\\nfi\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use your real account and selected organization. Do not create a disposable\\n\", _jsx(_components.code, {\n children: \"agent+\"\n }), \" identity or paste credentials into the workspace file.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The flow has three phases, run from a single checklist file:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Create + identify\"\n }), \" — \", _jsx(_components.code, {\n children: \"POST /api/artists\"\n }), \", then find the canonical Spotify match\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Enrich\"\n }), \" — \", _jsx(_components.code, {\n children: \"PATCH\"\n }), \" the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Synthesize + persist\"\n }), \" — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally \", _jsx(_components.code, {\n children: \"PATCH\"\n }), \" the \", _jsx(_components.code, {\n children: \"knowledges\"\n }), \" array\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-0-scaffold-the-workspace-before-any-api-call\",\n children: \"Step 0: Scaffold the workspace BEFORE any API call\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pick a slug, make the directory, and write the initial \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"ARTIST_SLUG=$(echo \\\"$ARTIST_NAME\\\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\\\\+/-/g; s/^-//; s/-$//')\\nARTIST_DIR=\\\"artists/$ARTIST_SLUG\\\"\\nmkdir -p \\\"$ARTIST_DIR\\\"\\n\\ncat > \\\"$ARTIST_DIR/RECOUP.md\\\" <&2\\n return 1 ;;\\n 429)\\n retry_after=$(awk 'tolower($1)==\\\"retry-after:\\\" {sub(/^[^:]*:[[:space:]]*/, \\\"\\\"); sub(/\\\\r$/, \\\"\\\"); print}' \\\"$headers\\\")\\n rm -f \\\"$headers\\\"\\n printf 'Research step stopped. Retry-After: %s. Resume manually when allowed.\\\\n' \\\"${retry_after:-not provided}\\\" >&2\\n return 1 ;;\\n 5??) ;;\\n *) rm -f \\\"$headers\\\"; printf 'Research HTTP %s; resolve before resuming.\\\\n' \\\"$status\\\" >&2; return 1 ;;\\n esac\\n fi\\n if [ \\\"$attempt\\\" -lt 3 ]; then sleep \\\"$((attempt * 2))\\\"; fi\\n done\\n rm -f \\\"$headers\\\"\\n echo 'Research unavailable after three attempts.' >&2\\n return 1\\n}\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4a-resolve-the-research-artist-id\",\n children: \"4a: Resolve the research artist ID\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"LOOKUP=$(research_request lookup --get \\\\\\n --data-urlencode \\\"spotifyId=$SPOTIFY_ARTIST_ID\\\") || exit 1\\n\\nRESEARCH_ARTIST_ID=$(printf '%s' \\\"$LOOKUP\\\" | jq -r \\\\\\n '[.id, .artist_info.id] | map(select(type == \\\"string\\\") | select(test(\\\"\\\\\\\\S\\\"))) | first // empty')\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save this value as \", _jsx(_components.code, {\n children: \"researchArtistId\"\n }), \". It is separate from the Recoup artist\\naccount UUID and Spotify ID. Do not coerce it to a number or copy an older\\nsaved research ID into it; re-resolve and verify older workspaces. If a successful\\nlookup has no usable \", _jsx(_components.code, {\n children: \"id\"\n }), \", record that gap and skip 4b–4d, then run 4e.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/lookup\",\n children: \"Artist Lookup\"\n }), \" for the response contract.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4b4d-read-available-structured-signals\",\n children: \"4b–4d: Read available structured signals\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"if [ -n \\\"$RESEARCH_ARTIST_ID\\\" ]; then\\n PROFILE=$(research_request profile --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\n CAREER=$(research_request career --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\n PLAYLISTS=$(research_request playlists --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\nfi\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Inspect the fields actually returned. Profile data may be partial; \", _jsx(_components.code, {\n children: \"career\"\n }), \" is\\nan available activity feed, not a guaranteed complete career timeline.\\n\", _jsx(_components.code, {\n children: \"playlists\"\n }), \" returns \", _jsx(_components.code, {\n children: \"placements\"\n }), \", which may be empty. Do not turn missing data\\ninto zero or infer a label, achievement or placement that is absent.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/profile\",\n children: \"Artist Profile\"\n }), \",\\n\", _jsx(_components.a, {\n href: \"/api-reference/research/career\",\n children: \"Artist Activity\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"/api-reference/research/playlists\",\n children: \"Playlist Placements\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4e-search-for-narrative-press-and-collaborations\",\n children: \"4e: Search for narrative, press and collaborations\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"RESEARCH_WEB=$(research_request web -X POST \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg name \\\"$ARTIST_NAME\\\" \\\\\\n '{query: ($name + \\\" biography press recent collaborations\\\")}')\\\") || exit 1\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Verify source links before asserting a fact. See \", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: \"Web Search\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" persist \", _jsx(_components.code, {\n children: \"researchArtistId\"\n }), \" when available. Save the returned\\npayloads, source links and coverage gaps under \", _jsx(_components.code, {\n children: \"## Research\"\n }), \" in \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \", with\\none subsection per request. Tick step 4 only after the successful reads and any\\nintentional structured-data skip have been recorded.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-5-pull-the-spotify-catalog\",\n children: \"Step 5: Pull the Spotify catalog\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"TOP_TRACKS=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/artist/topTracks\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$SPOTIFY_ARTIST_ID\\\")\\n\\nALBUMS=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/artist/albums\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$SPOTIFY_ARTIST_ID\\\")\\n\\n# For each notable album, drill in (ALBUM_ID from $ALBUMS):\\nALBUM_DETAIL=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/album\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$ALBUM_ID\\\")\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"$SPOTIFY_ARTIST_ID\"\n }), \" is the value you exported in step 2.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/spotify/artist-top-tracks\",\n children: \"Spotify Top Tracks\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/spotify/artist-albums\",\n children: \"Spotify Artist Albums\"\n }), \", and \", _jsx(_components.a, {\n href: \"/api-reference/spotify/album\",\n children: \"Spotify Album\"\n }), \" for full schemas.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" populate the artist's \", _jsx(_components.code, {\n children: \"releases/\"\n }), \" folder — write one \", _jsx(_components.code, {\n children: \"releases/{release-slug}/RELEASE.md\"\n }), \" per album (album slugs are bare, \", _jsx(_components.code, {\n children: \"-ep\"\n }), \" / \", _jsx(_components.code, {\n children: \"-single\"\n }), \" / \", _jsx(_components.code, {\n children: \"-compilation\"\n }), \" suffixes for other types) using the per-album \", _jsx(_components.code, {\n children: \"GET /api/spotify/album?id=$ALBUM_ID\"\n }), \" response, and write the top tracks snapshot to \", _jsx(_components.code, {\n children: \"releases/top-tracks.md\"\n }), \". \", _jsx(_components.code, {\n children: \"RELEASE.md\"\n }), \" is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as \", _jsx(_components.code, {\n children: \"⚠️ TBD\"\n }), \". The full template + the field-by-field Spotify mapping live in the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace\",\n children: _jsx(_components.code, {\n children: \"artist-workspace\"\n })\n }), \" skill at \", _jsx(_components.code, {\n children: \"references/release-template.md\"\n }), \". Tick \", _jsx(_components.code, {\n children: \"- [ ] 5.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 5.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-6-search-the-web-for-additional-socials\",\n children: \"Step 6: Search the web for additional socials\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"SOCIALS_SEARCH=$(curl -sS -X POST \\\"https://api.recoupable.dev/api/research/web\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg name \\\"$ARTIST_NAME\\\" \\\\\\n '{query: ($name + \\\" official instagram tiktok twitter youtube\\\")}')\\\")\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Parse the results to extract any new social URLs whose host matches the platform reference table below.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: \"Web Search\"\n }), \" for the request/response schema.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" save the discovered URLs (one per platform) into the \", _jsx(_components.code, {\n children: \"## Notes\"\n }), \" section so step 7 can read them without re-querying. Tick \", _jsx(_components.code, {\n children: \"- [ ] 6.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 6.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-7-patch-the-artist-with-the-discovered-socials\",\n children: \"Step 7: PATCH the artist with the discovered socials\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS -X PATCH \\\"https://api.recoupable.dev/api/artists/$ARTIST_ID\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\n \\\"profileUrls\\\": {\\n \\\"INSTAGRAM\\\": \\\"https://instagram.com/...\\\",\\n \\\"TIKTOK\\\": \\\"https://tiktok.com/@...\\\",\\n \\\"TWITTER\\\": \\\"https://x.com/...\\\",\\n \\\"YOUTUBE\\\": \\\"https://youtube.com/@...\\\"\\n }\\n }'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Only include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/artists/update\",\n children: \"Update Artist\"\n }), \" for the full body schema.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" tick \", _jsx(_components.code, {\n children: \"- [ ] 7.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 7.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-8-synthesize-the-knowledge-base\",\n children: \"Step 8: Synthesize the knowledge base\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Combine the available structured and web research (\", _jsx(_components.code, {\n children: \"## Research\"\n }), \" section), the Spotify catalog (\", _jsx(_components.code, {\n children: \"releases/\"\n }), \"), and the discovered socials into a comprehensive markdown report. Recommended sections:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Artist biography and origin\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Discography highlights (top tracks + key albums)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Spotify presence (genres, listener count, notable playlists)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Social media footprint\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Recent activity / press\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Notable collaborations and achievements\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Append the report to the same \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" you scaffolded in Step 0 — add it as a \", _jsx(_components.code, {\n children: \"## Knowledge base\"\n }), \" section below the checklist. The path is:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"artists/$ARTIST_SLUG/RECOUP.md\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This dovetails with the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace\",\n children: _jsx(_components.code, {\n children: \"artist-workspace\"\n })\n }), \" skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" tick \", _jsx(_components.code, {\n children: \"- [ ] 8.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 8.\"\n }), \". With every box ticked, the artist is fully set up.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"platform-key-reference\",\n children: \"Platform key reference\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"profileUrls\"\n }), \" keys are \", _jsx(_components.strong, {\n children: \"uppercase\"\n }), \" platform identifiers, inferred from the URL host. Recognized platforms:\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"URL contains\"\n }), _jsxs(_components.th, {\n children: [_jsx(_components.code, {\n children: \"profileUrls\"\n }), \" key\"]\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"spotify.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"SPOTIFY\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"instagram.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"INSTAGRAM\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"tiktok.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"TIKTOK\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"x.com\"\n }), \", \", _jsx(_components.code, {\n children: \"twitter.com\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"TWITTER\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"youtube.\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"YOUTUBE\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"apple.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"APPLE\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"facebook.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"FACEBOOK\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"threads.net\"\n }), \", \", _jsx(_components.code, {\n children: \"threads.com\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"THREADS\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"URLs that don't match any of these are silently skipped — they won't be saved.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-this-workflow-doesnt-enforce\",\n children: \"What this workflow doesn't enforce\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"There's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A few constraints to honor:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Run steps in order.\"\n }), \" The frontmatter values written at one step are the inputs for later steps.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Don't continue past a 4xx/5xx without recovery.\"\n }), \" Leave the box unchecked, write the error to \", _jsx(_components.code, {\n children: \"## Notes\"\n }), \", and resolve before resuming.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Treat the file as the source of truth.\"\n }), \" If something isn't on disk, don't assume it ran.\"]\n }), \"\\n\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Create a New Artist End-to-end workflow to create, research and enrich a new artist account in a single session. Artists Workflows This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \"researched + enriched\" parity from a sandbox or any external agent. The chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it. ## Prerequisites - `$RECOUP_API_KEY` (`x-api-key`) or `$RECOUP_ACCESS_TOKEN` (Privy Bearer JWT) for `api.recoupable.dev` - `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes) - An artist name to create (e.g. `ARTIST_NAME=\"The Weeknd\"`) Select one credential obtained through the approved real-account REST setup: Use your real account and selected organization. Do not create a disposable `agent+` identity or paste credentials into the workspace file. The flow has three phases, run from a single checklist file: 1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match 2. **Enrich** — `PATCH` the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials 3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array ## Step 0: Scaffold the workspace BEFORE any API call Pick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps: The sandbox is already scoped to a single Recoupable organization (its repo _is_ the org), so artists live at the top level — there is no `orgs/` directory. Don't proceed to step 1 until the file exists on disk. **After every step that follows, do two writes back to `RECOUP.md`:** tick the checkbox for the step you just ran (`- [ ]` → `- [x]`) and persist any captured value into the frontmatter. Later steps read those values from the frontmatter — never re-derive what's already saved. ## Resuming a partial setup If `$ARTIST_DIR/RECOUP.md` already exists, do not re-scaffold and do not re-run completed steps. Read the file, find the first unchecked item, and resume from there using the values already saved in the frontmatter: If every item is checked, the artist is fully set up — confirm with the user before doing anything else. ## Step 1: Create the artist Capture `account_id` as `$ARTIST_ID` — every subsequent step needs it. `organization_id` is optional but should be included when running inside a sandbox so the artist is scoped to the right org. See [Create Artist](/api-reference/artists/create) for the full request/response schema. **After this step:** write `artistId: $ARTIST_ID` into the frontmatter and tick `- [ ] 1.` → `- [x] 1.` in `RECOUP.md`. ## Step 2: Find the canonical Spotify match Inspect the returned candidates' names, profile links, images and catalog. Set `SELECTED_SPOTIFY_ARTIST_ID` to the verified match; popularity alone does not establish identity. If candidates remain ambiguous, resolve that before saving the artist's profile. If the verified artist is absent from the first ten results, repeat the search with a more specific name or known catalog context and inspect the new results. Do not substitute another artist. After verifying the candidate, export its fields: Also keep `genres`, `followers.total`, and `popularity` from `$MATCH` for the KB report later. See [Spotify Search](/api-reference/spotify/search) for the full query parameters and response schema. **After this step:** write `spotifyArtistId`, `spotifyProfileUrl`, and `imageUrl` into the frontmatter, save `genres` / `followers.total` / `popularity` to the `## Notes` section, and tick `- [ ] 2.` → `- [x] 2.`. ## Step 3: Set basic profile + Spotify URL One `PATCH` covers the image and the Spotify social URL. Use **uppercase** platform keys in `profileUrls` (the API matches platforms case-sensitively — see the reference table below). 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 only after verifying it in the research (step 4). See [Update Artist](/api-reference/artists/update) for the full body schema. **After this step:** tick `- [ ] 3.` → `- [x] 3.`. ## Step 4: Run Recoup research Resolve the verified Spotify artist to an opaque Recoup research ID, then read available profile fields, activity and playlist placements. Coverage varies by artist and platform: an empty successful response is a data gap, not a request to warm a cache. Use a web search for biography, press and collaborations. The four structured reads below cost $0.05 each when successful, or $0.20 total (200,000 micro-dollar credits). Web research is billed separately; check the current credit reference before running it. Check HTTP status before extracting IDs or making dependent calls. This helper allows at most three attempts for network failures or `5xx`, each with a 90-second timeout. A `402` surfaces `billingUrl`; a `429` stops the step and prints `Retry-After` for a later manual retry; it does not wait or retry automatically. Leave the step unchecked on errors. ### 4a: Resolve the research artist ID Save this value as `researchArtistId`. It is separate from the Recoup artist account UUID and Spotify ID. Do not coerce it to a number or copy an older saved research ID into it; re-resolve and verify older workspaces. If a successful lookup has no usable `id`, record that gap and skip 4b–4d, then run 4e. See [Artist Lookup](/api-reference/research/lookup) for the response contract. ### 4b–4d: Read available structured signals Inspect the fields actually returned. Profile data may be partial; `career` is an available activity feed, not a guaranteed complete career timeline. `playlists` returns `placements`, which may be empty. Do not turn missing data into zero or infer a label, achievement or placement that is absent. See [Artist Profile](/api-reference/research/profile), [Artist Activity](/api-reference/research/career) and [Playlist Placements](/api-reference/research/playlists). ### 4e: Search for narrative, press and collaborations Verify source links before asserting a fact. See [Web Search](/api-reference/research/web). **After this step:** persist `researchArtistId` when available. Save the returned payloads, source links and coverage gaps under `## Research` in `RECOUP.md`, with one subsection per request. Tick step 4 only after the successful reads and any intentional structured-data skip have been recorded. ## Step 5: Pull the Spotify catalog `$SPOTIFY_ARTIST_ID` is the value you exported in step 2. See [Spotify Top Tracks](/api-reference/spotify/artist-top-tracks), [Spotify Artist Albums](/api-reference/spotify/artist-albums), and [Spotify Album](/api-reference/spotify/album) for full schemas. **After this step:** populate the artist's `releases/` folder — write one `releases/{release-slug}/RELEASE.md` per album (album slugs are bare, `-ep` / `-single` / `-compilation` suffixes for other types) using the per-album `GET /api/spotify/album?id=$ALBUM_ID` response, and write the top tracks snapshot to `releases/top-tracks.md`. `RELEASE.md` is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as `⚠️ TBD`. The full template + the field-by-field Spotify mapping live in the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill at `references/release-template.md`. Tick `- [ ] 5.` → `- [x] 5.`. ## Step 6: Search the web for additional socials Parse the results to extract any new social URLs whose host matches the platform reference table below. See [Web Search](/api-reference/research/web) for the request/response schema. **After this step:** save the discovered URLs (one per platform) into the `## Notes` section so step 7 can read them without re-querying. Tick `- [ ] 6.` → `- [x] 6.`. ## Step 7: PATCH the artist with the discovered socials Only include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally. See [Update Artist](/api-reference/artists/update) for the full body schema. **After this step:** tick `- [ ] 7.` → `- [x] 7.`. ## Step 8: Synthesize the knowledge base Combine the available structured and web research (`## Research` section), the Spotify catalog (`releases/`), and the discovered socials into a comprehensive markdown report. Recommended sections: - Artist biography and origin - Discography highlights (top tracks + key albums) - Spotify presence (genres, listener count, notable playlists) - Social media footprint - Recent activity / press - Notable collaborations and achievements Append the report to the same `RECOUP.md` you scaffolded in Step 0 — add it as a `## Knowledge base` section below the checklist. The path is: This dovetails with the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL. **After this step:** tick `- [ ] 8.` → `- [x] 8.`. With every box ticked, the artist is fully set up. ## Platform key reference `profileUrls` keys are **uppercase** platform identifiers, inferred from the URL host. Recognized platforms: | URL contains | `profileUrls` key | | ---------------------------- | ----------------- | | `spotify.com` | `SPOTIFY` | | `instagram.com` | `INSTAGRAM` | | `tiktok.com` | `TIKTOK` | | `x.com`, `twitter.com` | `TWITTER` | | `youtube.` | `YOUTUBE` | | `apple.com` | `APPLE` | | `facebook.com` | `FACEBOOK` | | `threads.net`, `threads.com` | `THREADS` | URLs that don't match any of these are silently skipped — they won't be saved. ## What this workflow doesn't enforce There's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The `RECOUP.md` checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't. A few constraints to honor: - **Run steps in order.** The frontmatter values written at one step are the inputs for later steps. - **Don't continue past a 4xx/5xx without recovery.** Leave the box unchecked, write the error to `## Notes`, and resolve before resuming. - **Treat the file as the source of truth.** If something isn't on disk, don't assume it ran. "},{"slug":"api-reference/artists/list","title":"Get Artists","description":"Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to.","category":"Artists","group":"Artists","source":"api-reference/artists/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists","spec":"releases.json"},"searchText":"Get Artists Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to. Artists Artists GET /api/artists "},{"slug":"api-reference/artists/profile","title":"Get Artist Profile","description":"Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call.","category":"Artists","group":"Artists","source":"api-reference/artists/profile.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/profile","spec":"releases.json"},"searchText":"Get Artist Profile Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call. Artists Artists GET /api/artists/{id}/profile "},{"slug":"api-reference/artists/create","title":"Create Artist","description":"Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization.","category":"Artists","group":"Artists","source":"api-reference/artists/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/artists","spec":"releases.json"},"searchText":"Create Artist Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization. Artists Artists POST /api/artists "},{"slug":"api-reference/artists/update","title":"Update Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Update Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/pin","title":"Pin Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/pin.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Pin Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/unpin","title":"Unpin Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/unpin.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Unpin Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/delete","title":"Delete Artist","description":"Delete an artist accessible to the authenticated account.","category":"Artists","group":"Artists","source":"api-reference/artists/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Delete Artist Delete an artist accessible to the authenticated account. Artists Artists DELETE /api/artists/{id} "},{"slug":"api-reference/artists/socials","title":"Get Artist Socials","description":"Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember.","category":"Artists","group":"Artists","source":"api-reference/artists/socials.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/socials","spec":"releases.json"},"searchText":"Get Artist Socials Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember. Artists Artists GET /api/artists/{id}/socials "},{"slug":"api-reference/artists/socials-delete","title":"Delete Artist Social","description":"Remove a social profile link from an artist to correct a wrongly auto-matched social.","category":"Artists","group":"Artists","source":"api-reference/artists/socials-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/artists/{id}/socials/{socialId}","spec":"releases.json"},"searchText":"Delete Artist Social Remove a social profile link from an artist to correct a wrongly auto-matched social. Artists Artists DELETE /api/artists/{id}/socials/{socialId} "},{"slug":"api-reference/fans/get","title":"Get Artist Fans","description":"Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists.","category":"Artists","group":"Fans","source":"api-reference/fans/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/fans","spec":"releases.json"},"searchText":"Get Artist Fans Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists. Artists Fans GET /api/artists/{id}/fans "},{"slug":"api-reference/chat/workflow","title":"Stream Chat","description":"Stream sandbox-driven chat (Vercel Workflow)","category":"Chats","group":"Streaming","source":"api-reference/chat/workflow.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat","spec":"research.json"},"searchText":"Stream Chat Stream sandbox-driven chat (Vercel Workflow) Chats Streaming POST /api/chat "},{"slug":"api-reference/chat/workflow-stream","title":"Resume Chat Stream","description":"Resume a chat response stream","category":"Chats","group":"Streaming","source":"api-reference/chat/workflow-stream.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chat/{chatId}/stream","spec":"research.json"},"searchText":"Resume Chat Stream Resume a chat response stream Chats Streaming GET /api/chat/{chatId}/stream "},{"slug":"api-reference/chat/runs","title":"Start Chat Run","description":"Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow).","category":"Chats","group":"Streaming","source":"api-reference/chat/runs.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat/runs","spec":"research.json"},"searchText":"Start Chat Run Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow). Chats Streaming POST /api/chat/runs "},{"slug":"api-reference/chat/runs-status","title":"Get Chat Run Status","description":"Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.","category":"Chats","group":"Streaming","source":"api-reference/chat/runs-status.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chat/runs/{runId}","spec":"research.json"},"searchText":"Get Chat Run Status Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content. Chats Streaming GET /api/chat/runs/{runId} "},{"slug":"api-reference/chat/stop","title":"Stop Chat","description":"Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account.","category":"Chats","group":"Streaming","source":"api-reference/chat/stop.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat/{chatId}/stop","spec":"research.json"},"searchText":"Stop Chat Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account. Chats Streaming POST /api/chat/{chatId}/stop "},{"slug":"api-reference/chat/create","title":"Create Chat","description":"Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to.","category":"Chats","group":"Chats","source":"api-reference/chat/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats","spec":"research.json"},"searchText":"Create Chat Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to. Chats Chats POST /api/chats "},{"slug":"api-reference/chat/chats","title":"Get Chats","description":"Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL.","category":"Chats","group":"Chats","source":"api-reference/chat/chats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats","spec":"research.json"},"searchText":"Get Chats Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL. Chats Chats GET /api/chats "},{"slug":"api-reference/chat/artist","title":"Get Chat Artist","description":"Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller.","category":"Chats","group":"Chats","source":"api-reference/chat/artist.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats/{id}/artist","spec":"research.json"},"searchText":"Get Chat Artist Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller. Chats Chats GET /api/chats/{id}/artist "},{"slug":"api-reference/chat/update","title":"Update Chat","description":"Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters.","category":"Chats","group":"Chats","source":"api-reference/chat/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/chats","spec":"research.json"},"searchText":"Update Chat Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters. Chats Chats PATCH /api/chats "},{"slug":"api-reference/chat/delete","title":"Delete Chat","description":"Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself.","category":"Chats","group":"Chats","source":"api-reference/chat/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/chats","spec":"research.json"},"searchText":"Delete Chat Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself. Chats Chats DELETE /api/chats "},{"slug":"api-reference/chat/compact","title":"Compact Chats","description":"Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary.","category":"Chats","group":"Chats","source":"api-reference/chat/compact.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats/compact","spec":"research.json"},"searchText":"Compact Chats Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary. Chats Chats POST /api/chats/compact "},{"slug":"api-reference/ai/models","title":"List Models","description":"Returns the catalog of language models available through the Vercel AI Gateway. Embedding models are filtered out. The full schema mirrors the Vercel AI Gateway response (`GatewayLanguageModelEntry` from `@ai-sdk/gateway`); the documented properties below are the load-bearing fields used by clients. No authentication required.","category":"Chats","group":"Chats","source":"api-reference/ai/models.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/ai/models","spec":"ai.json"},"searchText":"List Models Returns the catalog of language models available through the Vercel AI Gateway. Embedding models are filtered out. The full schema mirrors the Vercel AI Gateway response (`GatewayLanguageModelEntry` from `@ai-sdk/gateway`); the documented properties below are the load-bearing fields used by clients. No authentication required. Chats Chats GET /api/ai/models "},{"slug":"api-reference/chat/messages","title":"Get Chat Messages","description":"Retrieve all messages (memories) for a specific chat room in chronological order.","category":"Chats","group":"Messages","source":"api-reference/chat/messages.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats/{id}/messages","spec":"research.json"},"searchText":"Get Chat Messages Retrieve all messages (memories) for a specific chat room in chronological order. Chats Messages GET /api/chats/{id}/messages "},{"slug":"api-reference/chat/messages-copy","title":"Copy Chat Messages","description":"Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy.","category":"Chats","group":"Messages","source":"api-reference/chat/messages-copy.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats/{id}/messages/copy","spec":"research.json"},"searchText":"Copy Chat Messages Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy. Chats Messages POST /api/chats/{id}/messages/copy "},{"slug":"api-reference/chat/messages-trailing-delete","title":"Delete Trailing Chat Messages","description":"Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override.","category":"Chats","group":"Messages","source":"api-reference/chat/messages-trailing-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/chats/{id}/messages/trailing","spec":"research.json"},"searchText":"Delete Trailing Chat Messages Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override. Chats Messages DELETE /api/chats/{id}/messages/trailing "},{"slug":"api-reference/research/search","title":"Research Search","description":"Search Recoup Research for artists, tracks or labels by name. Artist and track matches include an `id` when an identifier is available. Select a match and reuse that ID for detail requests. `type` accepts artists, tracks or labels, plus their singular aliases, case-insensitively. Playlist search is unavailable. Recoup defaults `limit` to 10; pagination strings are passed to the data connection and its limits apply.","category":"Research","group":"Artist discovery","source":"api-reference/research/search.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research","spec":"research.json"},"searchText":"Research Search Search Recoup Research for artists, tracks or labels by name. Artist and track matches include an `id` when an identifier is available. Select a match and reuse that ID for detail requests. `type` accepts artists, tracks or labels, plus their singular aliases, case-insensitively. Playlist search is unavailable. Recoup defaults `limit` to 10; pagination strings are passed to the data connection and its limits apply. Research Artist discovery GET /api/research "},{"slug":"api-reference/research/lookup","title":"Lookup by URL","description":"Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved.","category":"Research","group":"Artist discovery","source":"api-reference/research/lookup.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/lookup","spec":"research.json"},"searchText":"Lookup by URL Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved. Research Artist discovery GET /api/research/lookup "},{"slug":"api-reference/research/profile","title":"Artist Profile","description":"Read artist identity and available biography, links, genres and related-artist metadata. Fields depend on available research data. For current platform counts, use [Metrics](/api-reference/research/metrics).","category":"Research","group":"Artist discovery","source":"api-reference/research/profile.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/profile","spec":"research.json"},"searchText":"Artist Profile Read artist identity and available biography, links, genres and related-artist metadata. Fields depend on available research data. For current platform counts, use [Metrics](/api-reference/research/metrics). Research Artist discovery GET /api/research/profile "},{"slug":"api-reference/research/metrics","title":"Platform Metrics","description":"Read current artist statistics for the required platform `source`. This is a synchronous snapshot, without a historical series or refresh-pending job. A valid source does not guarantee data is available. Save dated responses to compare results over time.","category":"Research","group":"Metrics & insights","source":"api-reference/research/metrics.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/metrics","spec":"research.json"},"searchText":"Platform Metrics Read current artist statistics for the required platform `source`. This is a synchronous snapshot, without a historical series or refresh-pending job. A valid source does not guarantee data is available. Save dated responses to compare results over time. Research Metrics & insights GET /api/research/metrics "},{"slug":"api-reference/research/audience","title":"Audience Demographics","description":"Read available audience data for an artist and platform. The default is `instagram`; other supported data connections can include Spotify, TikTok and YouTube. Geographic and demographic coverage varies. Age and gender breakdowns are not guaranteed.","category":"Research","group":"Metrics & insights","source":"api-reference/research/audience.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/audience","spec":"research.json"},"searchText":"Audience Demographics Read available audience data for an artist and platform. The default is `instagram`; other supported data connections can include Spotify, TikTok and YouTube. Geographic and demographic coverage varies. Age and gender breakdowns are not guaranteed. Research Metrics & insights GET /api/research/audience "},{"slug":"api-reference/research/insights","title":"Insights Activities","description":"Read available artist activities under `insights`. This endpoint returns activity data; it does not generate an AI analysis or a separate insight report.","category":"Research","group":"Metrics & insights","source":"api-reference/research/insights.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/insights","spec":"research.json"},"searchText":"Insights Activities Read available artist activities under `insights`. This endpoint returns activity data; it does not generate an AI analysis or a separate insight report. Research Metrics & insights GET /api/research/insights "},{"slug":"api-reference/research/career","title":"Career Timeline","description":"Read available dated artist activities under `career`. Career, insights and milestones use the same activity feed. This endpoint does not calculate a career stage or score, and does not guarantee a complete career history.","category":"Research","group":"Metrics & insights","source":"api-reference/research/career.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/career","spec":"research.json"},"searchText":"Career Timeline Read available dated artist activities under `career`. Career, insights and milestones use the same activity feed. This endpoint does not calculate a career stage or score, and does not guarantee a complete career history. Research Metrics & insights GET /api/research/career "},{"slug":"api-reference/research/milestones","title":"Milestones","description":"Read available artist activities under `milestones`. Coverage varies; an empty result does not prove the artist has no milestones. This endpoint does not guarantee a complete history or scored career timeline.","category":"Research","group":"Metrics & insights","source":"api-reference/research/milestones.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/milestones","spec":"research.json"},"searchText":"Milestones Read available artist activities under `milestones`. Coverage varies; an empty result does not prove the artist has no milestones. This endpoint does not guarantee a complete history or scored career timeline. Research Metrics & insights GET /api/research/milestones "},{"slug":"api-reference/research/events","title":"Artist Events","description":"List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup.","category":"Research","group":"Metrics & insights","source":"api-reference/research/events.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/events","spec":"research.json"},"searchText":"Artist Events List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup. Research Metrics & insights POST /api/research/events "},{"slug":"api-reference/research/similar","title":"Similar Artists","description":"Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored.","category":"Research","group":"Metrics & insights","source":"api-reference/research/similar.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/similar","spec":"research.json"},"searchText":"Similar Artists Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored. Research Metrics & insights GET /api/research/similar "},{"slug":"api-reference/research/urls","title":"Social URLs","description":"Read available platform URLs as `{domain, url}` entries. A missing link means no matching URL was returned; it does not prove the artist lacks an account on that platform.","category":"Research","group":"Metrics & insights","source":"api-reference/research/urls.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/urls","spec":"research.json"},"searchText":"Social URLs Read available platform URLs as `{domain, url}` entries. A missing link means no matching URL was returned; it does not prove the artist lacks an account on that platform. Research Metrics & insights GET /api/research/urls "},{"slug":"api-reference/research/albums","title":"Albums","description":"Read the artist catalog through the `albums` view using the `artist_id` selected from [Search](/api-reference/research/search). Results can include track-shaped catalog entries rather than distinct album objects. `is_primary` accepts true/false; filtering depends on the data connection. `limit` must be a positive integer string and `offset` a non-negative integer string.","category":"Research","group":"Catalog","source":"api-reference/research/albums.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/albums","spec":"research.json"},"searchText":"Albums Read the artist catalog through the `albums` view using the `artist_id` selected from [Search](/api-reference/research/search). Results can include track-shaped catalog entries rather than distinct album objects. `is_primary` accepts true/false; filtering depends on the data connection. `limit` must be a positive integer string and `offset` a non-negative integer string. Research Catalog GET /api/research/albums "},{"slug":"api-reference/research/tracks","title":"Tracks","description":"Read available artist catalog entries under `tracks`. Entries can include remixes and features; completeness and fields vary. This endpoint accepts an artist identifier without catalog pagination or filtering controls.","category":"Research","group":"Catalog","source":"api-reference/research/tracks.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/tracks","spec":"research.json"},"searchText":"Tracks Read available artist catalog entries under `tracks`. Entries can include remixes and features; completeness and fields vary. This endpoint accepts an artist identifier without catalog pagination or filtering controls. Research Catalog GET /api/research/tracks "},{"slug":"api-reference/research/track","title":"Track","description":"Read track details using the `id` selected from [Search](/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording.","category":"Research","group":"Catalog","source":"api-reference/research/track.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track","spec":"research.json"},"searchText":"Track Read track details using the `id` selected from [Search](/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording. Research Catalog GET /api/research/track "},{"slug":"api-reference/research/track-stats","title":"Track Stats","description":"Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown.","category":"Research","group":"Catalog","source":"api-reference/research/track-stats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track/stats","spec":"research.json"},"searchText":"Track Stats Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown. Research Catalog GET /api/research/track/stats "},{"slug":"api-reference/research/measurements","title":"Track measurements","description":"Track measurements","category":"Research","group":"Catalog","source":"api-reference/research/measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/tracks/{id}/measurements","spec":"research.json"},"searchText":"Track measurements Track measurements Research Catalog GET /api/research/tracks/{id}/measurements "},{"slug":"api-reference/research/album-measurements","title":"Album measurements","description":"Album measurements","category":"Research","group":"Catalog","source":"api-reference/research/album-measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/albums/{id}/measurements","spec":"research.json"},"searchText":"Album measurements Album measurements Research Catalog GET /api/research/albums/{id}/measurements "},{"slug":"api-reference/research/measurement-jobs","title":"Create measurement job","description":"Create a measurement job","category":"Research","group":"Catalog","source":"api-reference/research/measurement-jobs.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/measurement-jobs","spec":"research.json"},"searchText":"Create measurement job Create a measurement job Research Catalog POST /api/research/measurement-jobs "},{"slug":"api-reference/research/playlists","title":"Playlist Placements","description":"Read available playlist placements for an artist. `status=current` selects current scope; `status=past` selects all-time scope, which can include current placements. `limit` is an optional raw string with no Recoup default; supported limits and coverage depend on the data connection.","category":"Research","group":"Playlists","source":"api-reference/research/playlists.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/playlists","spec":"research.json"},"searchText":"Playlist Placements Read available playlist placements for an artist. `status=current` selects current scope; `status=past` selects all-time scope, which can include current placements. `limit` is an optional raw string with no Recoup default; supported limits and coverage depend on the data connection. Research Playlists GET /api/research/playlists "},{"slug":"api-reference/research/track-playlists","title":"Track Playlists","description":"Read available track playlist and activity entries. Supply a selected track `id`, or a track name `q` with optional `artist`. Name resolution selects the first Spotify match and resolves its research ID; `id` takes precedence. Filtering and pagination support depend on the data connection. With no filter flags, editorial, indie, majorCurator and popularIndie default to true. Track-name resolution can add separately charged lookup calls; reuse a selected ID to avoid them.","category":"Research","group":"Playlists","source":"api-reference/research/track-playlists.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track/playlists","spec":"research.json"},"searchText":"Track Playlists Read available track playlist and activity entries. Supply a selected track `id`, or a track name `q` with optional `artist`. Name resolution selects the first Spotify match and resolves its research ID; `id` takes precedence. Filtering and pagination support depend on the data connection. With no filter flags, editorial, indie, majorCurator and popularIndie default to true. Track-name resolution can add separately charged lookup calls; reuse a selected ID to avoid them. Research Playlists GET /api/research/track/playlists "},{"slug":"api-reference/research/web","title":"Web Search","description":"Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover.","category":"Research","group":"Web & social","source":"api-reference/research/web.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/web","spec":"research.json"},"searchText":"Web Search Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover. Research Web & social POST /api/research/web "},{"slug":"api-reference/research/deep","title":"Deep Research","description":"Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources.","category":"Research","group":"Web & social","source":"api-reference/research/deep.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/deep","spec":"research.json"},"searchText":"Deep Research Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources. Research Web & social POST /api/research/deep "},{"slug":"api-reference/research/people","title":"People Search","description":"Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data.","category":"Research","group":"Web & social","source":"api-reference/research/people.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/people","spec":"research.json"},"searchText":"People Search Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data. Research Web & social POST /api/research/people "},{"slug":"api-reference/research/extract","title":"Extract URL","description":"Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content.","category":"Research","group":"Web & social","source":"api-reference/research/extract.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/extract","spec":"research.json"},"searchText":"Extract URL Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content. Research Web & social POST /api/research/extract "},{"slug":"api-reference/research/enrich","title":"Enrich","description":"Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected.","category":"Research","group":"Web & social","source":"api-reference/research/enrich.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/enrich","spec":"research.json"},"searchText":"Enrich Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected. Research Web & social POST /api/research/enrich "},{"slug":"api-reference/songs/songs","title":"Get Songs","description":"Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information.","category":"Catalog","group":"Songs","source":"api-reference/songs/songs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/songs","spec":"releases.json"},"searchText":"Get Songs Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information. Catalog Songs GET /api/songs "},{"slug":"api-reference/songs/create","title":"Song creation availability","description":"Import songs into an owned catalog; standalone song creation is not available.","category":"Catalog","group":"Songs","source":"api-reference/songs/create.mdx","body":"Standalone `POST /api/songs` is not available. The API currently supports\n[`GET /api/songs`](/api-reference/songs/songs) for reading songs.\n\n## Add songs to a catalog\n\nIf you have an existing catalog you can access, use\n[`POST /api/catalogs/songs`](/api-reference/songs/catalog-songs-add).\nEach song needs its `catalog_id` and `isrc`; optional name, album, notes and\nartist names supply fallback metadata. The API checks access to every named\ncatalog before processing songs. This writes song records and catalog links;\nit is not a standalone create-only replacement.\n\n## Unfinished product decision\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) owns the\ndecision whether a separate song-creation API is needed and what ownership,\nmetadata-update and duplicate behavior it should allow. The old standalone\nrequest and response are removed from the callable specification until that\ndecision and its implementation exist. Do not omit `catalog_id` or substitute\nan unrelated catalog to make a write succeed.\n","headings":[{"title":"Add songs to a catalog","id":"add-songs-to-a-catalog"},{"title":"Unfinished product decision","id":"unfinished-product-decision"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Standalone \", _jsx(_components.code, {\n children: \"POST /api/songs\"\n }), \" is not available. The API currently supports\\n\", _jsx(_components.a, {\n href: \"/api-reference/songs/songs\",\n children: _jsx(_components.code, {\n children: \"GET /api/songs\"\n })\n }), \" for reading songs.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"add-songs-to-a-catalog\",\n children: \"Add songs to a catalog\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you have an existing catalog you can access, use\\n\", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-add\",\n children: _jsx(_components.code, {\n children: \"POST /api/catalogs/songs\"\n })\n }), \".\\nEach song needs its \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" and \", _jsx(_components.code, {\n children: \"isrc\"\n }), \"; optional name, album, notes and\\nartist names supply fallback metadata. The API checks access to every named\\ncatalog before processing songs. This writes song records and catalog links;\\nit is not a standalone create-only replacement.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"unfinished-product-decision\",\n children: \"Unfinished product decision\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" owns the\\ndecision whether a separate song-creation API is needed and what ownership,\\nmetadata-update and duplicate behavior it should allow. The old standalone\\nrequest and response are removed from the callable specification until that\\ndecision and its implementation exist. Do not omit \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" or substitute\\nan unrelated catalog to make a write succeed.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Song creation availability Import songs into an owned catalog; standalone song creation is not available. Catalog Songs Standalone `POST /api/songs` is not available. The API currently supports [`GET /api/songs`](/api-reference/songs/songs) for reading songs. ## Add songs to a catalog If you have an existing catalog you can access, use [`POST /api/catalogs/songs`](/api-reference/songs/catalog-songs-add). Each song needs its `catalog_id` and `isrc`; optional name, album, notes and artist names supply fallback metadata. The API checks access to every named catalog before processing songs. This writes song records and catalog links; it is not a standalone create-only replacement. ## Unfinished product decision [Reconciliation #327](https://github.com/recoupable/mono/issues/327) owns the decision whether a separate song-creation API is needed and what ownership, metadata-update and duplicate behavior it should allow. The old standalone request and response are removed from the callable specification until that decision and its implementation exist. Do not omit `catalog_id` or substitute an unrelated catalog to make a write succeed. "},{"slug":"api-reference/songs/analyze","title":"Analyze Songs","description":"Analyze music using a state-of-the-art Audio Language Model ([Music Flamingo](https://www.universalmusic.com/universal-music-group-to-transform-music-experience-for-billions-of-fans-with-nvidia-ai/)) that listens directly to the audio waveform.","category":"Catalog","group":"Songs","source":"api-reference/songs/analyze.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/songs/analyze","spec":"releases.json"},"searchText":"Analyze Songs Analyze music using a state-of-the-art Audio Language Model ([Music Flamingo](https://www.universalmusic.com/universal-music-group-to-transform-music-experience-for-billions-of-fans-with-nvidia-ai/)) that listens directly to the audio waveform. Catalog Songs POST /api/songs/analyze "},{"slug":"api-reference/songs/analyze-presets","title":"List Analyze Presets","description":"Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token.","category":"Catalog","group":"Songs","source":"api-reference/songs/analyze-presets.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/songs/analyze/presets","spec":"releases.json"},"searchText":"List Analyze Presets Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token. Catalog Songs GET /api/songs/analyze/presets "},{"slug":"api-reference/songs/catalogs","title":"Get Catalogs","description":"Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalogs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/catalogs","spec":"releases.json"},"searchText":"Get Catalogs Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run). Catalog Catalogs GET /api/accounts/{id}/catalogs "},{"slug":"api-reference/songs/catalogs-create","title":"Create Catalog","description":"Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalogs-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/catalogs","spec":"releases.json"},"searchText":"Create Catalog Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization. Catalog Catalogs POST /api/catalogs "},{"slug":"api-reference/songs/catalog-rename","title":"Rename Catalog","description":"Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-rename.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/catalogs/{catalogId}","spec":"releases.json"},"searchText":"Rename Catalog Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete). Catalog Catalogs PATCH /api/catalogs/{catalogId} "},{"slug":"api-reference/songs/catalog-delete","title":"Delete Catalog","description":"Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/catalogs/{catalogId}","spec":"releases.json"},"searchText":"Delete Catalog Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations). Catalog Catalogs DELETE /api/catalogs/{catalogId} "},{"slug":"api-reference/songs/valuation-run","title":"Run Valuation","description":"Run valuation","category":"Catalog","group":"Catalogs","source":"api-reference/songs/valuation-run.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/valuation","spec":"releases.json"},"searchText":"Run Valuation Run valuation Catalog Catalogs POST /api/valuation "},{"slug":"api-reference/songs/runs","title":"Get Runs","description":"Get runs","category":"Catalog","group":"Catalogs","source":"api-reference/songs/runs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/runs","spec":"releases.json"},"searchText":"Get Runs Get runs Catalog Catalogs GET /api/runs "},{"slug":"api-reference/songs/catalog-measurements","title":"Get Catalog Measurements","description":"Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/measurements","spec":"releases.json"},"searchText":"Get Catalog Measurements Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song. Catalog Catalogs GET /api/catalogs/{catalogId}/measurements "},{"slug":"api-reference/songs/catalog-playcount-history","title":"Catalog Playcount History","description":"Read catalog playcount history and period comparisons","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-playcount-history.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/playcount-history","spec":"releases.json"},"searchText":"Catalog Playcount History Read catalog playcount history and period comparisons Catalog Catalogs GET /api/catalogs/{catalogId}/playcount-history "},{"slug":"api-reference/songs/catalog-valuations","title":"Valuation history availability","description":"Saved valuation history is unfinished; current estimates do not establish a history.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-valuations.mdx","body":"Saved catalog valuation history is not available through\n`GET /api/catalogs/{catalogId}/valuations`. Current valuation calculations and\ncatalog measurements do not establish that estimates were saved or can be read\nback as a dated series.\n\n## Existing implementation work\n\n[Reconciliation #326](https://github.com/recoupable/mono/issues/326) owns this\noutcome through [App #1911](https://github.com/recoupable/app/issues/1911) and\n[API #795](https://github.com/recoupable/api/pull/795).\n[API #1059](https://github.com/recoupable/api/pull/1059) continues that work as a\nheld draft of internal adapters. It does not register a REST route, MCP tool or\nproduction caller and does not connect successful valuation runs to persistence.\n\nThe existing owner must finish the access prerequisite, run-to-save integration,\npublic read contract and authorized deployed save/readback before this feature\ncan be advertised. Removing the unfinished operation from the callable\nspecification does not complete or cancel valuation history. Do not rerun a paid\nvaluation solely to try to recover an unconfirmed save.\n","headings":[{"title":"Existing implementation work","id":"existing-implementation-work"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Saved catalog valuation history is not available through\\n\", _jsx(_components.code, {\n children: \"GET /api/catalogs/{catalogId}/valuations\"\n }), \". Current valuation calculations and\\ncatalog measurements do not establish that estimates were saved or can be read\\nback as a dated series.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"existing-implementation-work\",\n children: \"Existing implementation work\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/326\",\n children: \"Reconciliation #326\"\n }), \" owns this\\noutcome through \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/app/issues/1911\",\n children: \"App #1911\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/795\",\n children: \"API #795\"\n }), \".\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/1059\",\n children: \"API #1059\"\n }), \" continues that work as a\\nheld draft of internal adapters. It does not register a REST route, MCP tool or\\nproduction caller and does not connect successful valuation runs to persistence.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The existing owner must finish the access prerequisite, run-to-save integration,\\npublic read contract and authorized deployed save/readback before this feature\\ncan be advertised. Removing the unfinished operation from the callable\\nspecification does not complete or cancel valuation history. Do not rerun a paid\\nvaluation solely to try to recover an unconfirmed save.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Valuation history availability Saved valuation history is unfinished; current estimates do not establish a history. Catalog Catalogs Saved catalog valuation history is not available through `GET /api/catalogs/{catalogId}/valuations`. Current valuation calculations and catalog measurements do not establish that estimates were saved or can be read back as a dated series. ## Existing implementation work [Reconciliation #326](https://github.com/recoupable/mono/issues/326) owns this outcome through [App #1911](https://github.com/recoupable/app/issues/1911) and [API #795](https://github.com/recoupable/api/pull/795). [API #1059](https://github.com/recoupable/api/pull/1059) continues that work as a held draft of internal adapters. It does not register a REST route, MCP tool or production caller and does not connect successful valuation runs to persistence. The existing owner must finish the access prerequisite, run-to-save integration, public read contract and authorized deployed save/readback before this feature can be advertised. Removing the unfinished operation from the callable specification does not complete or cancel valuation history. Do not rerun a paid valuation solely to try to recover an unconfirmed save. "},{"slug":"api-reference/songs/catalog-songs","title":"Get Catalog Songs","description":"Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs.mdx","body":"\n This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints.\n\n\nA successful query with no matching songs returns HTTP `200`, an empty `songs`\narray, and `pagination.total_count: 0`. This also applies to an accessible catalog\nwith no songs. An empty result is not a `404` response.\n\nUse a nonempty `artistName` to request songs with a matching artist name. Omit the filter to\ninclude songs without a linked artist. Filtering applies before pagination and\nthe total count; a client can use a zero count to decide whether to retry without\nthe artist filter.\n\nMissing or inaccessible catalogs return `403`. A server or database failure\nreturns `500` with `status: \"error\"` and `error: \"Internal server error\"`.\n","headings":[],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the \", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-add\",\n children: \"Add Catalog Songs\"\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-delete\",\n children: \"Remove Catalog Songs\"\n }), \" endpoints.\"]\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A successful query with no matching songs returns HTTP \", _jsx(_components.code, {\n children: \"200\"\n }), \", an empty \", _jsx(_components.code, {\n children: \"songs\"\n }), \"\\narray, and \", _jsx(_components.code, {\n children: \"pagination.total_count: 0\"\n }), \". This also applies to an accessible catalog\\nwith no songs. An empty result is not a \", _jsx(_components.code, {\n children: \"404\"\n }), \" response.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use a nonempty \", _jsx(_components.code, {\n children: \"artistName\"\n }), \" to request songs with a matching artist name. Omit the filter to\\ninclude songs without a linked artist. Filtering applies before pagination and\\nthe total count; a client can use a zero count to decide whether to retry without\\nthe artist filter.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Missing or inaccessible catalogs return \", _jsx(_components.code, {\n children: \"403\"\n }), \". A server or database failure\\nreturns \", _jsx(_components.code, {\n children: \"500\"\n }), \" with \", _jsx(_components.code, {\n children: \"status: \\\"error\\\"\"\n }), \" and \", _jsx(_components.code, {\n children: \"error: \\\"Internal server error\\\"\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"GET","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Get Catalog Songs Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0. Catalog Catalogs GET /api/catalogs/songs This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints. A successful query with no matching songs returns HTTP `200`, an empty `songs` array, and `pagination.total_count: 0`. This also applies to an accessible catalog with no songs. An empty result is not a `404` response. Use a nonempty `artistName` to request songs with a matching artist name. Omit the filter to include songs without a linked artist. Filtering applies before pagination and the total count; a client can use a zero count to decide whether to retry without the artist filter. Missing or inaccessible catalogs return `403`. A server or database failure returns `500` with `status: \"error\"` and `error: \"Internal server error\"`. "},{"slug":"api-reference/songs/catalog-songs-add","title":"Add Catalog Songs","description":"Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs-add.mdx","body":"\n For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.\n\n","headings":[],"compiled":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.\"\n })\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"POST","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Add Catalog Songs Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used. Catalog Catalogs POST /api/catalogs/songs For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used. "},{"slug":"api-reference/songs/catalog-songs-delete","title":"Remove Catalog Songs","description":"Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs-delete.mdx","body":"\n This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted.\n\n","headings":[],"compiled":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"This endpoint removes the relationship in \", _jsx(_components.code, {\n children: \"catalog_songs\"\n }), \" for each \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" and ISRC pair. The song data itself is not deleted.\"]\n })\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"DELETE","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Remove Catalog Songs Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair. Catalog Catalogs DELETE /api/catalogs/songs This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted. "},{"slug":"api-reference/songs/catalog-streams","title":"Daily Catalog Streams","description":"Read daily catalog streams","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-streams.mdx","body":"## Date range and coverage\n\nSet `days` to an integer from 1 to 366 days. For example, use `days=90` for a 90-day comparison period. `since` is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive.\n\nA supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while `pagination.has_more` is true. Missing measurements suppress growth; they do not establish zero streams.\n\nThe catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection.\n","headings":[{"title":"Date range and coverage","id":"date-range-and-coverage"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"date-range-and-coverage\",\n children: \"Date range and coverage\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Set \", _jsx(_components.code, {\n children: \"days\"\n }), \" to an integer from 1 to 366 days. For example, use \", _jsx(_components.code, {\n children: \"days=90\"\n }), \" for a 90-day comparison period. \", _jsx(_components.code, {\n children: \"since\"\n }), \" is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while \", _jsx(_components.code, {\n children: \"pagination.has_more\"\n }), \" is true. Missing measurements suppress growth; they do not establish zero streams.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","api":{"method":"GET","path":"/api/catalogs/{catalogId}/streams","spec":"releases.json"},"searchText":"Daily Catalog Streams Read daily catalog streams Catalog Catalogs GET /api/catalogs/{catalogId}/streams ## Date range and coverage Set `days` to an integer from 1 to 366 days. For example, use `days=90` for a 90-day comparison period. `since` is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive. A supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while `pagination.has_more` is true. Missing measurements suppress growth; they do not establish zero streams. The catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection. "},{"slug":"api-reference/songs/catalog-stream-tracking","title":"Catalog Stream Tracking","description":"Inspect daily catalog tracking","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-stream-tracking.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/stream-tracking","spec":"releases.json"},"searchText":"Catalog Stream Tracking Inspect daily catalog tracking Catalog Catalogs GET /api/catalogs/{catalogId}/stream-tracking "},{"slug":"api-reference/songs/update-catalog-stream-tracking","title":"Update Catalog Stream Tracking","description":"Control daily catalog tracking","category":"Catalog","group":"Catalogs","source":"api-reference/songs/update-catalog-stream-tracking.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/catalogs/{catalogId}/stream-tracking","spec":"releases.json"},"searchText":"Update Catalog Stream Tracking Control daily catalog tracking Catalog Catalogs POST /api/catalogs/{catalogId}/stream-tracking "},{"slug":"api-reference/context/operate","title":"Context Engine","description":"Ingest, read, or compile context briefs","category":"Catalog","group":"Context","source":"api-reference/context/operate.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context","spec":"context.json"},"searchText":"Context Engine Ingest, read, or compile context briefs Catalog Context POST /api/context "},{"slug":"api-reference/context/guest-start","title":"Start guest context","description":"Start guest context extraction","category":"Catalog","group":"Context","source":"api-reference/context/guest-start.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context/guest","spec":"context.json"},"searchText":"Start guest context Start guest context extraction Catalog Context POST /api/context/guest "},{"slug":"api-reference/context/guest-read","title":"Read guest context","description":"Read guest context","category":"Catalog","group":"Context","source":"api-reference/context/guest-read.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/context/guest","spec":"context.json"},"searchText":"Read guest context Read guest context Catalog Context GET /api/context/guest "},{"slug":"api-reference/context/guest-claim","title":"Claim guest context","description":"Claim guest context after sign-in","category":"Catalog","group":"Context","source":"api-reference/context/guest-claim.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context/guest/claim","spec":"context.json"},"searchText":"Claim guest context Claim guest context after sign-in Catalog Context POST /api/context/guest/claim "},{"slug":"workflows/generate-music-video","title":"Generate a Music Video","description":"End-to-end workflow to produce a vertical, social-ready music video — image, motion, caption — from an artist and a song.","category":"Content","group":"Workflows","source":"workflows/generate-music-video.mdx","body":"This is the canonical recipe used internally by Recoup's `create-content` background task. Two paths are documented below: the **async pipeline** that an LLM agent should use, and the **manual recipe** for humans (or for cases where you want to swap a single step).\n\n## Hand it to your LLM\n\nThe fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a `.md` suffix, so models can fetch and follow it without parsing HTML:\n\n```\nGenerate a music video for The Weeknd – \"Blinding Lights\" using\nhttps://docs.recoupable.dev/workflows/generate-music-video.md\n```\n\nSwap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL.\n\n## Running as an agent? Use the async pipeline\n\n`POST /api/content/video` is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments.\n\nUse the async path instead — same five steps, run server-side:\n\n```bash\n# Trigger\nRUN_IDS=$(curl -sS -X POST \"https://api.recoupable.dev/api/content/create\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg artist \"$ARTIST_ACCOUNT_ID\" --arg template \"$TEMPLATE\" \\\n '{artist_account_id: $artist, template: $template}')\" \\\n | jq -r '.runIds[]')\n\n# Poll (every ~10s) until COMPLETED / FAILED / CANCELED / CRASHED\nRUN_ID=$(echo \"$RUN_IDS\" | head -1)\nuntil STATUS=$(curl -sS \"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq -r '.runs[0].status') && \\\n [[ \"$STATUS\" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do\n sleep 10\ndone\n\n# Read the output\ncurl -sS \"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq '.runs[0].output'\n# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }\n```\n\nPolling fits inside short shell timeouts and survives session restarts. See [Tasks Runs](/api-reference/tasks/runs) for the full status enum (`QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, etc.) and the `CreateContentRunOutput` schema.\n\n### Resolving `$ARTIST_ACCOUNT_ID`\n\n`POST /api/content/create` needs the artist's `account_id`. Three calls:\n\n```bash\nORG_ID=$(curl -sS \"https://api.recoupable.dev/api/organizations\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" | jq -r '.organizations[0].id')\n\nARTIST_ACCOUNT_ID=$(curl -sS \"https://api.recoupable.dev/api/artists?org_id=$ORG_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq -r --arg name \"$ARTIST_NAME\" '.artists[] | select(.name == $name) | .account_id')\n```\n\nThe artist record exposes both `id` and `account_id` (both UUIDs). Use **`account_id`** — `id` is the artist row's primary key, `account_id` is the underlying account that owns it. The two are easy to swap; you'll get a 404 from `/api/content/create` if you pass the wrong one.\n\n## Where the song lives\n\nStep 5 (and the async pipeline's lipsync mode) need a `song.mp3`. **Don't assume one exists, and don't assume the user has one locally.** Walk the agent through this fallback chain:\n\n1. **Check the artist's sandbox repo first.** Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths:\n\n ```\n .openclaw/workspace/orgs/{org-slug}/artists/{artist-slug}/songs/{song-slug}/{song-slug}.mp3\n /lyrics.json\n /clips.json\n ```\n\n Discover the repo with [`GET /api/sandboxes`](/api-reference/sandboxes/list) (returns `github_repo` and a `filetree`); fetch a file with [`GET /api/sandboxes/file?path=…`](/api-reference/sandboxes/file). **Binary files (`.mp3`, `.png`, `.mp4`) come back base64-encoded in the `content` field — decode before writing to disk.**\n\n2. **If no song is in the sandbox, ask the user how to proceed.** Two options to offer:\n - *\"Want me to fetch the audio from YouTube?\"* — agent downloads via `yt-dlp` (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications.\n - *\"Want to supply the song yourself?\"* — user uploads / drops a path; agent reads from there.\n\n Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call.\n\n3. **Don't fall back to \"use a placeholder track.\"** A music video without the song is not a deliverable.\n\n## Manual recipe (humans + targeted overrides)\n\nThe rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length).\n\n### Prerequisites\n\n- An auth credential for `api.recoupable.dev`. Two options — pick one and use it for every call below:\n - **API key** (`recoup_sk_…`, recommended for sandbox / agent use): pass as `-H \"x-api-key: $RECOUP_API_KEY\"`.\n - One-shot agent: `POST /api/agents/signup` with an `agent+{unique}@recoupable.com` email returns the key immediately.\n - Real-email signup: same endpoint with a real email mails a 6-digit code; complete with `POST /api/agents/verify`. See [Agents](/agents).\n - **Privy access token** (for end-user flows in chat/UI): pass as `-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\"`.\n - The examples below use `x-api-key`. Substitute `Authorization: Bearer …` if you're using a Privy token.\n- `$ARTIST_NAME`, `$SONG_TITLE`, `$SONG_LYRICS_CLIP` (a 1–2 sentence mood snippet)\n- `$REFERENCE_IMAGE_URL` *(optional)* — an artist photo or album cover to seed the image; if your template's purpose is \"show this exact image\" (e.g. `album-record-store`), set this and skip image generation in step 2\n- A `song.mp3` for step 5. **Don't ask the user for a local file** — fetch from the artist's repo via `/api/sandboxes/file`.\n- `ffmpeg` installed locally for step 5\n\n### Step 0: Scaffold the workspace BEFORE any API call\n\nThe `VIDEO.md` checklist *is* the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box.\n\n```bash\nVIDEO_SLUG=$(echo \"$SONG_TITLE\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-//; s/-$//')\nVIDEO_DIR=\"videos/$VIDEO_SLUG\"\nmkdir -p \"$VIDEO_DIR\"\n\ncat > \"$VIDEO_DIR/VIDEO.md\" < \"$VIDEO_DIR/caption.txt\"\n\n# Single-line filter graph — newlines inside -filter_complex are literal characters and break the [v] label\nffmpeg -y \\\n -stream_loop -1 -i \"$VIDEO_DIR/clip.mp4\" \\\n -i \"$SONG_PATH\" \\\n -filter_complex \"[0:v]crop=ih*9/16:ih,scale=1080:1920,drawtext=fontfile=$CAPTION_FONT:textfile=$VIDEO_DIR/caption.txt:fontcolor=$CAPTION_COLOR:fontsize=$CAPTION_FONT_SIZE:x=(w-text_w)/2:y=h-text_h-120:box=1:boxcolor=$CAPTION_STROKE@0.5:boxborderw=20[v]\" \\\n -map \"[v]\" -map \"1:a\" \\\n -shortest -c:v libx264 -c:a aac -pix_fmt yuv420p \\\n \"$FINAL_PATH\"\n```\n\n**After:** write `finalVideoPath`, tick the box. With every box ticked, the music video is complete.\n\n## Step 6: Publish (optional)\n\nOnce the MP4 is rendered, push it to the artist's socials with the [Connectors API](/api-reference/connectors/list). One heads-up worth knowing:\n\n- **TikTok URL ownership.** `TIKTOK_PUBLISH_VIDEO` (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. `fal.media` URLs will fail with `url_ownership_unverified` — use `TIKTOK_UPLOAD_VIDEO` instead, which accepts the same URL and uploads server-side.\n\n---\n\nThe checklist is the source of truth — if a box isn't ticked, treat the step as not run.\n","headings":[{"title":"Hand it to your LLM","id":"hand-it-to-your-llm"},{"title":"Running as an agent? Use the async pipeline","id":"running-as-an-agent-use-the-async-pipeline"},{"title":"Where the song lives","id":"where-the-song-lives"},{"title":"Manual recipe (humans + targeted overrides)","id":"manual-recipe-humans-targeted-overrides"},{"title":"Step 6: Publish (optional)","id":"step-6-publish-optional"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"This is the canonical recipe used internally by Recoup's \", _jsx(_components.code, {\n children: \"create-content\"\n }), \" background task. Two paths are documented below: the \", _jsx(_components.strong, {\n children: \"async pipeline\"\n }), \" that an LLM agent should use, and the \", _jsx(_components.strong, {\n children: \"manual recipe\"\n }), \" for humans (or for cases where you want to swap a single step).\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hand-it-to-your-llm\",\n children: \"Hand it to your LLM\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a \", _jsx(_components.code, {\n children: \".md\"\n }), \" suffix, so models can fetch and follow it without parsing HTML:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"Generate a music video for The Weeknd – \\\"Blinding Lights\\\" using\\nhttps://docs.recoupable.dev/workflows/generate-music-video.md\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Swap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"running-as-an-agent-use-the-async-pipeline\",\n children: \"Running as an agent? Use the async pipeline\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/video\"\n }), \" is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the async path instead — same five steps, run server-side:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"# Trigger\\nRUN_IDS=$(curl -sS -X POST \\\"https://api.recoupable.dev/api/content/create\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg artist \\\"$ARTIST_ACCOUNT_ID\\\" --arg template \\\"$TEMPLATE\\\" \\\\\\n '{artist_account_id: $artist, template: $template}')\\\" \\\\\\n | jq -r '.runIds[]')\\n\\n# Poll (every ~10s) until COMPLETED / FAILED / CANCELED / CRASHED\\nRUN_ID=$(echo \\\"$RUN_IDS\\\" | head -1)\\nuntil STATUS=$(curl -sS \\\"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq -r '.runs[0].status') && \\\\\\n [[ \\\"$STATUS\\\" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do\\n sleep 10\\ndone\\n\\n# Read the output\\ncurl -sS \\\"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq '.runs[0].output'\\n# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Polling fits inside short shell timeouts and survives session restarts. See \", _jsx(_components.a, {\n href: \"/api-reference/tasks/runs\",\n children: \"Tasks Runs\"\n }), \" for the full status enum (\", _jsx(_components.code, {\n children: \"QUEUED\"\n }), \", \", _jsx(_components.code, {\n children: \"EXECUTING\"\n }), \", \", _jsx(_components.code, {\n children: \"COMPLETED\"\n }), \", \", _jsx(_components.code, {\n children: \"FAILED\"\n }), \", \", _jsx(_components.code, {\n children: \"CANCELED\"\n }), \", \", _jsx(_components.code, {\n children: \"CRASHED\"\n }), \", etc.) and the \", _jsx(_components.code, {\n children: \"CreateContentRunOutput\"\n }), \" schema.\"]\n }), \"\\n\", _jsxs(_components.h3, {\n id: \"resolving-artistaccountid\",\n children: [\"Resolving \", _jsx(_components.code, {\n children: \"$ARTIST_ACCOUNT_ID\"\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/create\"\n }), \" needs the artist's \", _jsx(_components.code, {\n children: \"account_id\"\n }), \". Three calls:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"ORG_ID=$(curl -sS \\\"https://api.recoupable.dev/api/organizations\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" | jq -r '.organizations[0].id')\\n\\nARTIST_ACCOUNT_ID=$(curl -sS \\\"https://api.recoupable.dev/api/artists?org_id=$ORG_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq -r --arg name \\\"$ARTIST_NAME\\\" '.artists[] | select(.name == $name) | .account_id')\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The artist record exposes both \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" (both UUIDs). Use \", _jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"account_id\"\n })\n }), \" — \", _jsx(_components.code, {\n children: \"id\"\n }), \" is the artist row's primary key, \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" is the underlying account that owns it. The two are easy to swap; you'll get a 404 from \", _jsx(_components.code, {\n children: \"/api/content/create\"\n }), \" if you pass the wrong one.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"where-the-song-lives\",\n children: \"Where the song lives\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Step 5 (and the async pipeline's lipsync mode) need a \", _jsx(_components.code, {\n children: \"song.mp3\"\n }), \". \", _jsx(_components.strong, {\n children: \"Don't assume one exists, and don't assume the user has one locally.\"\n }), \" Walk the agent through this fallback chain:\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Check the artist's sandbox repo first.\"\n }), \" Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \".openclaw/workspace/orgs/{org-slug}/artists/{artist-slug}/songs/{song-slug}/{song-slug}.mp3\\n /lyrics.json\\n /clips.json\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Discover the repo with \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes\"\n })\n }), \" (returns \", _jsx(_components.code, {\n children: \"github_repo\"\n }), \" and a \", _jsx(_components.code, {\n children: \"filetree\"\n }), \"); fetch a file with \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/file\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes/file?path=…\"\n })\n }), \". \", _jsxs(_components.strong, {\n children: [\"Binary files (\", _jsx(_components.code, {\n children: \".mp3\"\n }), \", \", _jsx(_components.code, {\n children: \".png\"\n }), \", \", _jsx(_components.code, {\n children: \".mp4\"\n }), \") come back base64-encoded in the \", _jsx(_components.code, {\n children: \"content\"\n }), \" field — decode before writing to disk.\"]\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"If no song is in the sandbox, ask the user how to proceed.\"\n }), \" Two options to offer:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.em, {\n children: \"\\\"Want me to fetch the audio from YouTube?\\\"\"\n }), \" — agent downloads via \", _jsx(_components.code, {\n children: \"yt-dlp\"\n }), \" (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.em, {\n children: \"\\\"Want to supply the song yourself?\\\"\"\n }), \" — user uploads / drops a path; agent reads from there.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Don't fall back to \\\"use a placeholder track.\\\"\"\n }), \" A music video without the song is not a deliverable.\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"manual-recipe-humans-targeted-overrides\",\n children: \"Manual recipe (humans + targeted overrides)\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length).\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"prerequisites\",\n children: \"Prerequisites\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"An auth credential for \", _jsx(_components.code, {\n children: \"api.recoupable.dev\"\n }), \". Two options — pick one and use it for every call below:\", \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"API key\"\n }), \" (\", _jsx(_components.code, {\n children: \"recoup_sk_…\"\n }), \", recommended for sandbox / agent use): pass as \", _jsx(_components.code, {\n children: \"-H \\\"x-api-key: $RECOUP_API_KEY\\\"\"\n }), \".\", \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"One-shot agent: \", _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" with an \", _jsx(_components.code, {\n children: \"agent+{unique}@recoupable.com\"\n }), \" email returns the key immediately.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Real-email signup: same endpoint with a real email mails a 6-digit code; complete with \", _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \". See \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents\"\n }), \".\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Privy access token\"\n }), \" (for end-user flows in chat/UI): pass as \", _jsx(_components.code, {\n children: \"-H \\\"Authorization: Bearer $RECOUP_ACCESS_TOKEN\\\"\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The examples below use \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \". Substitute \", _jsx(_components.code, {\n children: \"Authorization: Bearer …\"\n }), \" if you're using a Privy token.\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$ARTIST_NAME\"\n }), \", \", _jsx(_components.code, {\n children: \"$SONG_TITLE\"\n }), \", \", _jsx(_components.code, {\n children: \"$SONG_LYRICS_CLIP\"\n }), \" (a 1–2 sentence mood snippet)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$REFERENCE_IMAGE_URL\"\n }), \" \", _jsx(_components.em, {\n children: \"(optional)\"\n }), \" — an artist photo or album cover to seed the image; if your template's purpose is \\\"show this exact image\\\" (e.g. \", _jsx(_components.code, {\n children: \"album-record-store\"\n }), \"), set this and skip image generation in step 2\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"A \", _jsx(_components.code, {\n children: \"song.mp3\"\n }), \" for step 5. \", _jsx(_components.strong, {\n children: \"Don't ask the user for a local file\"\n }), \" — fetch from the artist's repo via \", _jsx(_components.code, {\n children: \"/api/sandboxes/file\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"ffmpeg\"\n }), \" installed locally for step 5\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"step-0-scaffold-the-workspace-before-any-api-call\",\n children: \"Step 0: Scaffold the workspace BEFORE any API call\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.code, {\n children: \"VIDEO.md\"\n }), \" checklist \", _jsx(_components.em, {\n children: \"is\"\n }), \" the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"VIDEO_SLUG=$(echo \\\"$SONG_TITLE\\\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-//; s/-$//')\\nVIDEO_DIR=\\\"videos/$VIDEO_SLUG\\\"\\nmkdir -p \\\"$VIDEO_DIR\\\"\\n\\ncat > \\\"$VIDEO_DIR/VIDEO.md\\\" < \\\"$VIDEO_DIR/caption.txt\\\"\\n\\n# Single-line filter graph — newlines inside -filter_complex are literal characters and break the [v] label\\nffmpeg -y \\\\\\n -stream_loop -1 -i \\\"$VIDEO_DIR/clip.mp4\\\" \\\\\\n -i \\\"$SONG_PATH\\\" \\\\\\n -filter_complex \\\"[0:v]crop=ih*9/16:ih,scale=1080:1920,drawtext=fontfile=$CAPTION_FONT:textfile=$VIDEO_DIR/caption.txt:fontcolor=$CAPTION_COLOR:fontsize=$CAPTION_FONT_SIZE:x=(w-text_w)/2:y=h-text_h-120:box=1:boxcolor=$CAPTION_STROKE@0.5:boxborderw=20[v]\\\" \\\\\\n -map \\\"[v]\\\" -map \\\"1:a\\\" \\\\\\n -shortest -c:v libx264 -c:a aac -pix_fmt yuv420p \\\\\\n \\\"$FINAL_PATH\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After:\"\n }), \" write \", _jsx(_components.code, {\n children: \"finalVideoPath\"\n }), \", tick the box. With every box ticked, the music video is complete.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-6-publish-optional\",\n children: \"Step 6: Publish (optional)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once the MP4 is rendered, push it to the artist's socials with the \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors API\"\n }), \". One heads-up worth knowing:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"TikTok URL ownership.\"\n }), \" \", _jsx(_components.code, {\n children: \"TIKTOK_PUBLISH_VIDEO\"\n }), \" (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. \", _jsx(_components.code, {\n children: \"fal.media\"\n }), \" URLs will fail with \", _jsx(_components.code, {\n children: \"url_ownership_unverified\"\n }), \" — use \", _jsx(_components.code, {\n children: \"TIKTOK_UPLOAD_VIDEO\"\n }), \" instead, which accepts the same URL and uploads server-side.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.p, {\n children: \"The checklist is the source of truth — if a box isn't ticked, treat the step as not run.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Generate a Music Video End-to-end workflow to produce a vertical, social-ready music video — image, motion, caption — from an artist and a song. Content Workflows This is the canonical recipe used internally by Recoup's `create-content` background task. Two paths are documented below: the **async pipeline** that an LLM agent should use, and the **manual recipe** for humans (or for cases where you want to swap a single step). ## Hand it to your LLM The fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a `.md` suffix, so models can fetch and follow it without parsing HTML: Swap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL. ## Running as an agent? Use the async pipeline `POST /api/content/video` is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments. Use the async path instead — same five steps, run server-side: Polling fits inside short shell timeouts and survives session restarts. See [Tasks Runs](/api-reference/tasks/runs) for the full status enum (`QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, etc.) and the `CreateContentRunOutput` schema. ### Resolving `$ARTIST_ACCOUNT_ID` `POST /api/content/create` needs the artist's `account_id`. Three calls: The artist record exposes both `id` and `account_id` (both UUIDs). Use **`account_id`** — `id` is the artist row's primary key, `account_id` is the underlying account that owns it. The two are easy to swap; you'll get a 404 from `/api/content/create` if you pass the wrong one. ## Where the song lives Step 5 (and the async pipeline's lipsync mode) need a `song.mp3`. **Don't assume one exists, and don't assume the user has one locally.** Walk the agent through this fallback chain: 1. **Check the artist's sandbox repo first.** Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths: Discover the repo with [`GET /api/sandboxes`](/api-reference/sandboxes/list) (returns `github_repo` and a `filetree`); fetch a file with [`GET /api/sandboxes/file?path=…`](/api-reference/sandboxes/file). **Binary files (`.mp3`, `.png`, `.mp4`) come back base64-encoded in the `content` field — decode before writing to disk.** 2. **If no song is in the sandbox, ask the user how to proceed.** Two options to offer: - *\"Want me to fetch the audio from YouTube?\"* — agent downloads via `yt-dlp` (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications. - *\"Want to supply the song yourself?\"* — user uploads / drops a path; agent reads from there. Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call. 3. **Don't fall back to \"use a placeholder track.\"** A music video without the song is not a deliverable. ## Manual recipe (humans + targeted overrides) The rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length). ### Prerequisites - An auth credential for `api.recoupable.dev`. Two options — pick one and use it for every call below: - **API key** (`recoup_sk_…`, recommended for sandbox / agent use): pass as `-H \"x-api-key: $RECOUP_API_KEY\"`. - One-shot agent: `POST /api/agents/signup` with an `agent+{unique}@recoupable.com` email returns the key immediately. - Real-email signup: same endpoint with a real email mails a 6-digit code; complete with `POST /api/agents/verify`. See [Agents](/agents). - **Privy access token** (for end-user flows in chat/UI): pass as `-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\"`. - The examples below use `x-api-key`. Substitute `Authorization: Bearer …` if you're using a Privy token. - `$ARTIST_NAME`, `$SONG_TITLE`, `$SONG_LYRICS_CLIP` (a 1–2 sentence mood snippet) - `$REFERENCE_IMAGE_URL` *(optional)* — an artist photo or album cover to seed the image; if your template's purpose is \"show this exact image\" (e.g. `album-record-store`), set this and skip image generation in step 2 - A `song.mp3` for step 5. **Don't ask the user for a local file** — fetch from the artist's repo via `/api/sandboxes/file`. - `ffmpeg` installed locally for step 5 ### Step 0: Scaffold the workspace BEFORE any API call The `VIDEO.md` checklist *is* the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box. ### Step 1: Pick a template (required: list **and** detail) Templates carry the prompt, reference images, and styling that drive the rest of the chain — you can't write a good Step 2 prompt without them. List, pick, then fetch detail: **Templates that list \"Requires: face image\"** (e.g. `artist-caption-bedroom`) will fall back to their bundled reference images and produce a generic-likeness subject if you don't supply one — they don't 400. Pass `$REFERENCE_IMAGE_URL` if you want the model to preserve a specific artist's likeness, or omit it for a stock-feeling result. See [List Templates](/api-reference/content/templates) and [Template Detail](/api-reference/content/template-detail). **After:** write `template` into frontmatter, tick the box. ### Step 2: Generate the base image Use the template's own prompt and reference images — don't write your own from scratch. The template encodes the visual style; freeform prompts almost always drift off-brand. **Shortcut:** if `$REFERENCE_IMAGE_URL` is the exact image you want (e.g. an album cover for `album-record-store`, or a final editorial photo), set `IMAGE_URL=$REFERENCE_IMAGE_URL` and skip this call entirely. **Avoid:** prompts that aim for a real artist's likeness. Veo (used in step 3) rejects celebrity-likeness images with a 422. Use the template's prompt as-is and let the reference images carry the style. See [Generate Image](/api-reference/content/generate-image). **After:** write `imageUrl`, tick the box. ### Optional: Upscale (image or video) Same endpoint for both, swap `type`. Skip if you don't need the resolution bump. See [Upscale](/api-reference/content/upscale). ### Step 3: Generate the video Pass the image and a short motion prompt. For lipsync, also pass a presigned `audio_url` to a song clip — the model will animate the artist's mouth. This call routinely takes 60–180s. **From a short-shell agent, use the async pipeline at the top of this page instead.** From a long-lived shell, output is an 8s clip. Step 5 loops it to song length. See [Generate Video](/api-reference/content/generate-video). **After:** write `videoUrl`, tick the box. ### Step 4: Generate the caption `length` accepts `\"short\"` (default), `\"medium\"`, `\"long\"`, or `\"none\"` to skip. The four styling fields (`font`, `color`, `borderColor`, `maxFontSize`) are template-driven hints — Step 5 wires them into ffmpeg's `drawtext` so the burned-in caption matches the template's brand. See [Generate Caption](/api-reference/content/generate-caption). **After:** write `captionText`, tick the box. ### Step 5: Compose the final 9:16 video (local) The API returns a 16:9 motion clip. Compose locally: crop to 9:16, overlay the song audio for the full duration, and burn in the caption with the styling from step 4. **After:** write `finalVideoPath`, tick the box. With every box ticked, the music video is complete. ## Step 6: Publish (optional) Once the MP4 is rendered, push it to the artist's socials with the [Connectors API](/api-reference/connectors/list). One heads-up worth knowing: - **TikTok URL ownership.** `TIKTOK_PUBLISH_VIDEO` (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. `fal.media` URLs will fail with `url_ownership_unverified` — use `TIKTOK_UPLOAD_VIDEO` instead, which accepts the same URL and uploads server-side. --- The checklist is the source of truth — if a box isn't ticked, treat the step as not run. "},{"slug":"api-reference/content/create","title":"Create Content","description":"Trigger 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).","category":"Content","group":"Content Creation","source":"api-reference/content/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/create","spec":"content.json"},"searchText":"Create Content Trigger 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). Content Content Creation POST /api/content/create "},{"slug":"api-reference/content/generate-image","title":"Generate Image","description":"Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL.","category":"Content","group":"Content Creation","source":"api-reference/content/generate-image.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/image","spec":"content.json"},"searchText":"Generate Image Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL. Content Content Creation POST /api/content/image "},{"slug":"api-reference/content/generate-video","title":"Generate Video","description":"Generate a video from a text prompt, optionally animating a still image (`image_url`) or transitioning between two images (`image_url` + `end_image_url`).","category":"Content","group":"Content Creation","source":"api-reference/content/generate-video.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/video","spec":"content.json"},"searchText":"Generate Video Generate a video from a text prompt, optionally animating a still image (`image_url`) or transitioning between two images (`image_url` + `end_image_url`). Content Content Creation POST /api/content/video "},{"slug":"api-reference/content/generate-caption","title":"Generate Caption","description":"Generate a short caption from a topic. Returns the text content and default styling (font, color, size).","category":"Content","group":"Content Creation","source":"api-reference/content/generate-caption.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/caption","spec":"content.json"},"searchText":"Generate Caption Generate a short caption from a topic. Returns the text content and default styling (font, color, size). Content Content Creation POST /api/content/caption "},{"slug":"api-reference/content/transcribe-audio","title":"Transcribe Audio","description":"Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments.","category":"Content","group":"Content Creation","source":"api-reference/content/transcribe-audio.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/transcribe","spec":"content.json"},"searchText":"Transcribe Audio Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments. Content Content Creation POST /api/content/transcribe "},{"slug":"api-reference/content/edit","title":"Edit Content","description":"Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.","category":"Content","group":"Content Creation","source":"api-reference/content/edit.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/content","spec":"content.json"},"searchText":"Edit Content Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array. Content Content Creation PATCH /api/content "},{"slug":"api-reference/content/upscale","title":"Upscale Content","description":"Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL.","category":"Content","group":"Content Creation","source":"api-reference/content/upscale.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/upscale","spec":"content.json"},"searchText":"Upscale Content Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL. Content Content Creation POST /api/content/upscale "},{"slug":"api-reference/content/analyze-video","title":"Analyze Video","description":"Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text.","category":"Content","group":"Content Creation","source":"api-reference/content/analyze-video.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/analyze","spec":"content.json"},"searchText":"Analyze Video Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text. Content Content Creation POST /api/content/analyze "},{"slug":"api-reference/content/templates","title":"List Templates","description":"List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one.","category":"Content","group":"Content Creation","source":"api-reference/content/templates.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/templates","spec":"content.json"},"searchText":"List Templates List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one. Content Content Creation GET /api/content/templates "},{"slug":"api-reference/content/template-detail","title":"Get Template Detail","description":"Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations.","category":"Content","group":"Content Creation","source":"api-reference/content/template-detail.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/templates/{id}","spec":"content.json"},"searchText":"Get Template Detail Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations. Content Content Creation GET /api/content/templates/{id} "},{"slug":"api-reference/content/validate","title":"Validate Artist","description":"Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter.","category":"Content","group":"Content Creation","source":"api-reference/content/validate.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/validate","spec":"content.json"},"searchText":"Validate Artist Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter. Content Content Creation GET /api/content/validate "},{"slug":"api-reference/content/estimate","title":"Estimate Cost","description":"Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits.","category":"Content","group":"Content Creation","source":"api-reference/content/estimate.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/estimate","spec":"content.json"},"searchText":"Estimate Cost Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits. Content Content Creation GET /api/content/estimate "},{"slug":"api-reference/image/generation","title":"Generate Image","description":"Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking.","category":"Content","group":"Content Creation","source":"api-reference/image/generation.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/image/generate","spec":"content.json"},"searchText":"Generate Image Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking. Content Content Creation GET /api/image/generate "},{"slug":"api-reference/transcribe/audio","title":"Transcribe Audio","description":"Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage. The owner account is derived from your credentials; you must have access to the specified artist_account_id.","category":"Content","group":"Content Creation","source":"api-reference/transcribe/audio.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/transcribe","spec":"content.json"},"searchText":"Transcribe Audio Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage. The owner account is derived from your credentials; you must have access to the specified artist_account_id. Content Content Creation POST /api/transcribe "},{"slug":"api-reference/content/lipsync","title":"Generate lipsync (release pending)","description":"Generate audio-driven video (release pending)","category":"Content","group":"Content Creation","source":"api-reference/content/lipsync.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/lipsync","spec":"content.json"},"searchText":"Generate lipsync (release pending) Generate audio-driven video (release pending) Content Content Creation POST /api/content/lipsync "},{"slug":"api-reference/music/generate","title":"Generate Music","description":"Generate music","category":"Content","group":"Music","source":"api-reference/music/generate.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/music","spec":"content.json"},"searchText":"Generate Music Generate music Content Music POST /api/music "},{"slug":"api-reference/music/list","title":"List Music Generations","description":"List music generations","category":"Content","group":"Music","source":"api-reference/music/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/music","spec":"content.json"},"searchText":"List Music Generations List music generations Content Music GET /api/music "},{"slug":"api-reference/music/get","title":"Get Music Generation","description":"Get music generation","category":"Content","group":"Music","source":"api-reference/music/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/music/{generationId}","spec":"content.json"},"searchText":"Get Music Generation Get music generation Content Music GET /api/music/{generationId} "},{"slug":"api-reference/music/legacy","title":"Music API migration","description":"Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths.","category":"Content","group":"Music","source":"api-reference/music/legacy.mdx","body":"## Generate a song now\n\nUse [`POST /api/music`](/api-reference/music/generate) with a prompt and lyrics.\nIt returns `202` with a generation record; poll\n[`GET /api/music/{generationId}`](/api-reference/music/get) for completion and\nthe resulting audio URL. It does not return audio in the initial response.\nSee the current reference for accepted settings, account scope and credits.\n\n## Former music routes\n\nThe six POST paths below are retired from the callable specification because\nthey have no implemented handlers in the current API. They are not aliases for\n`POST /api/music`. Their specialized outcomes are not equivalent to ordinary\nsong generation and are not declared canceled by this correction.\n\n| Former path | Current choice and remaining limit |\n| --- | --- |\n| `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. |\n| `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. |\n| `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. |\n| `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. |\n| `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. |\n| `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. |\n\n## What remains undecided\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the\nspecialized capability decisions. The current music-generation implementation\nis tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and\n[API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every\nformer capability. An agent or local skill may help prepare inputs, but that\ndoes not establish a hosted route or compatibility with the former request.\n\nThis is a reference correction. No provider run or audio-quality check was\nperformed to make these availability statements.\n","headings":[{"title":"Generate a song now","id":"generate-a-song-now"},{"title":"Former music routes","id":"former-music-routes"},{"title":"What remains undecided","id":"what-remains-undecided"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"generate-a-song-now\",\n children: \"Generate a song now\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.a, {\n href: \"/api-reference/music/generate\",\n children: _jsx(_components.code, {\n children: \"POST /api/music\"\n })\n }), \" with a prompt and lyrics.\\nIt returns \", _jsx(_components.code, {\n children: \"202\"\n }), \" with a generation record; poll\\n\", _jsx(_components.a, {\n href: \"/api-reference/music/get\",\n children: _jsx(_components.code, {\n children: \"GET /api/music/{generationId}\"\n })\n }), \" for completion and\\nthe resulting audio URL. It does not return audio in the initial response.\\nSee the current reference for accepted settings, account scope and credits.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"former-music-routes\",\n children: \"Former music routes\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The six POST paths below are retired from the callable specification because\\nthey have no implemented handlers in the current API. They are not aliases for\\n\", _jsx(_components.code, {\n children: \"POST /api/music\"\n }), \". Their specialized outcomes are not equivalent to ordinary\\nsong generation and are not declared canceled by this correction.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Former path\"\n }), _jsx(_components.th, {\n children: \"Current choice and remaining limit\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/compose\"\n })\n }), _jsx(_components.td, {\n children: \"Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/compose/detailed\"\n })\n }), _jsx(_components.td, {\n children: \"Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/plan\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/stream\"\n })\n }), _jsx(_components.td, {\n children: \"Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/video-to-music\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/stem-separation\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems.\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-remains-undecided\",\n children: \"What remains undecided\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" retains the\\nspecialized capability decisions. The current music-generation implementation\\nis tracked in \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/app/issues/1992\",\n children: \"App #1992\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/848\",\n children: \"API #848\"\n }), \"; it is not delivery of every\\nformer capability. An agent or local skill may help prepare inputs, but that\\ndoes not establish a hosted route or compatibility with the former request.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This is a reference correction. No provider run or audio-quality check was\\nperformed to make these availability statements.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Music API migration Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths. Content Music ## Generate a song now Use [`POST /api/music`](/api-reference/music/generate) with a prompt and lyrics. It returns `202` with a generation record; poll [`GET /api/music/{generationId}`](/api-reference/music/get) for completion and the resulting audio URL. It does not return audio in the initial response. See the current reference for accepted settings, account scope and credits. ## Former music routes The six POST paths below are retired from the callable specification because they have no implemented handlers in the current API. They are not aliases for `POST /api/music`. Their specialized outcomes are not equivalent to ordinary song generation and are not declared canceled by this correction. | Former path | Current choice and remaining limit | | --- | --- | | `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. | | `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. | | `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. | | `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. | | `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. | | `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. | ## What remains undecided [Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the specialized capability decisions. The current music-generation implementation is tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and [API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every former capability. An agent or local skill may help prepare inputs, but that does not establish a hosted route or compatibility with the former request. This is a reference correction. No provider run or audio-quality check was performed to make these availability statements. "},{"slug":"api-reference/posts/get","title":"Get Artist Posts","description":"Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections.","category":"Content","group":"Posts & Comments","source":"api-reference/posts/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/posts","spec":"social.json"},"searchText":"Get Artist Posts Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections. Content Posts & Comments GET /api/artists/{id}/posts "},{"slug":"api-reference/comments/get","title":"Get Comments","description":"Read saved comments on an authorized creator’s linked posts","category":"Content","group":"Posts & Comments","source":"api-reference/comments/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/comments","spec":"social.json"},"searchText":"Get Comments Read saved comments on an authorized creator’s linked posts Content Posts & Comments GET /api/comments "},{"slug":"api-reference/social/scrape","title":"Social Scrape","description":"Trigger a scrape of one social profile. Use [Get Artist Socials](/api-reference/artists/socials) first to get the social `id`. The response contains scraper run metadata; poll it with the [Scraper Results API](/api-reference/apify/scraper).","category":"Social Media","group":"Social","source":"api-reference/social/scrape.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/socials/{id}/scrape","spec":"social.json"},"searchText":"Social Scrape Trigger a scrape of one social profile. Use [Get Artist Socials](/api-reference/artists/socials) first to get the social `id`. The response contains scraper run metadata; poll it with the [Scraper Results API](/api-reference/apify/scraper). Social Media Social POST /api/socials/{id}/scrape "},{"slug":"api-reference/artist/socials-scrape","title":"api-reference/artist/socials-scrape","description":"Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper).","category":"Social Media","group":"Social","source":"api-reference/artist/socials-scrape.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/artist/socials/scrape","spec":"releases.json"},"searchText":"api-reference/artist/socials-scrape Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper). Social Media Social POST /api/artist/socials/scrape "},{"slug":"api-reference/spotify/search","title":"Search","description":"Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/search.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/search","spec":"social.json"},"searchText":"Search Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API. Social Media Spotify GET /api/spotify/search "},{"slug":"api-reference/spotify/artist","title":"Get Artist","description":"Get Spotify catalog information for a single artist identified by their unique Spotify ID.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/","spec":"social.json"},"searchText":"Get Artist Get Spotify catalog information for a single artist identified by their unique Spotify ID. Social Media Spotify GET /api/spotify/artist/ "},{"slug":"api-reference/spotify/artist-albums","title":"Get Artist Albums","description":"Get Spotify catalog information about an artist's albums.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist-albums.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/albums","spec":"social.json"},"searchText":"Get Artist Albums Get Spotify catalog information about an artist's albums. Social Media Spotify GET /api/spotify/artist/albums "},{"slug":"api-reference/spotify/artist-top-tracks","title":"Get Artist Top Tracks","description":"Get an artist's top tracks by country.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist-top-tracks.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/topTracks","spec":"social.json"},"searchText":"Get Artist Top Tracks Get an artist's top tracks by country. Social Media Spotify GET /api/spotify/artist/topTracks "},{"slug":"api-reference/spotify/album","title":"Get Album","description":"Get Spotify catalog information for a single album.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/album.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/album","spec":"social.json"},"searchText":"Get Album Get Spotify catalog information for a single album. Social Media Spotify GET /api/spotify/album "},{"slug":"api-reference/apple/songs","title":"Songs by ISRC","description":"Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose.","category":"Social Media","group":"Apple Music","source":"api-reference/apple/songs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/apple/songs","spec":"social.json"},"searchText":"Songs by ISRC Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose. Social Media Apple Music GET /api/apple/songs "},{"slug":"api-reference/apify/scraper","title":"Scraper Results","description":"Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results.","category":"Social Media","group":"Apify","source":"api-reference/apify/scraper.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/apify/runs/{runId}","spec":"social.json"},"searchText":"Scraper Results Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results. Social Media Apify GET /api/apify/runs/{runId} "},{"slug":"api-reference/agents/signup","title":"Agent Signup","description":"Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key.","category":"Agents & Sandboxes","group":"Agent Onboarding","source":"api-reference/agents/signup.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/signup","spec":"accounts.json"},"searchText":"Agent Signup Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key. Agents & Sandboxes Agent Onboarding POST /api/agents/signup "},{"slug":"api-reference/agents/verify","title":"Verify Agent Email","description":"Verify an agent's email with the code sent during signup. Returns an API key on success.","category":"Agents & Sandboxes","group":"Agent Onboarding","source":"api-reference/agents/verify.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/verify","spec":"accounts.json"},"searchText":"Verify Agent Email Verify an agent's email with the code sent during signup. Returns an API key on success. Agents & Sandboxes Agent Onboarding POST /api/agents/verify "},{"slug":"agents","title":"Agents","description":"Verified email onboarding for a separate Recoup REST API key.","category":"Agents & Sandboxes","group":"Agents","source":"agents.mdx","body":"## Use your real account\n\nPrefer [MCP OAuth](/mcp-oauth) for supported AI hosts. REST integrations need a\nseparate API key; an OAuth connection does not export one into your shell.\n\nUse the email verification flow below with an address the user controls. Keep\nthe returned key out of messages and logs, and store it through a secret facility\nor an explicitly approved local environment file. Never use a disposable account\nto recover an existing user's data.\n\nThe source signup contract also supports immediate keys for new `agent+` addresses.\nThat creates a separate identity; it does not grant customer or organization access.\nIt is not the recommended onboarding path for customer work. Multiple API keys per\naccount are supported, without revoking existing keys.\n\n## Standard signup (email verification)\n\nIf you're building a human-facing integration and want the user to verify their real email, use an email address the user controls:\n\nStep 1 — request a verification code:\n\n```bash\ncurl -X POST \"https://api.recoupable.dev/api/agents/signup\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\"}'\n```\n\nStep 2 — submit the 6-digit code from the verification email:\n\n```bash\ncurl -X POST \"https://api.recoupable.dev/api/agents/verify\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"code\": \"123456\"}'\n```\n\nResponse:\n\n```json\n{\n \"account_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"api_key\": \"recoup_sk_abc123...\",\n \"message\": \"Verified\"\n}\n```\n\n## Using your API key\n\nPass the returned `api_key` in the `x-api-key` header on every authenticated request:\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\nSee [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request.\n","headings":[{"title":"Use your real account","id":"use-your-real-account"},{"title":"Standard signup (email verification)","id":"standard-signup-email-verification"},{"title":"Using your API key","id":"using-your-api-key"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"use-your-real-account\",\n children: \"Use your real account\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Prefer \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for supported AI hosts. REST integrations need a\\nseparate API key; an OAuth connection does not export one into your shell.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the email verification flow below with an address the user controls. Keep\\nthe returned key out of messages and logs, and store it through a secret facility\\nor an explicitly approved local environment file. Never use a disposable account\\nto recover an existing user's data.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The source signup contract also supports immediate keys for new \", _jsx(_components.code, {\n children: \"agent+\"\n }), \" addresses.\\nThat creates a separate identity; it does not grant customer or organization access.\\nIt is not the recommended onboarding path for customer work. Multiple API keys per\\naccount are supported, without revoking existing keys.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"standard-signup-email-verification\",\n children: \"Standard signup (email verification)\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you're building a human-facing integration and want the user to verify their real email, use an email address the user controls:\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Step 1 — request a verification code:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X POST \\\"https://api.recoupable.dev/api/agents/signup\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"email\\\": \\\"you@example.com\\\"}'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Step 2 — submit the 6-digit code from the verification email:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X POST \\\"https://api.recoupable.dev/api/agents/verify\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"email\\\": \\\"you@example.com\\\", \\\"code\\\": \\\"123456\\\"}'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\\n \\\"api_key\\\": \\\"recoup_sk_abc123...\\\",\\n \\\"message\\\": \\\"Verified\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"using-your-api-key\",\n children: \"Using your API key\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass the returned \", _jsx(_components.code, {\n children: \"api_key\"\n }), \" in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header on every authenticated request:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"Authentication\"\n }), \" for the full authentication model, including organization access and Bearer token support, and \", _jsx(_components.a, {\n href: \"/quickstart\",\n children: \"Quickstart\"\n }), \" for your first end-to-end request.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Agents Verified email onboarding for a separate Recoup REST API key. Agents & Sandboxes Agents ## Use your real account Prefer [MCP OAuth](/mcp-oauth) for supported AI hosts. REST integrations need a separate API key; an OAuth connection does not export one into your shell. Use the email verification flow below with an address the user controls. Keep the returned key out of messages and logs, and store it through a secret facility or an explicitly approved local environment file. Never use a disposable account to recover an existing user's data. The source signup contract also supports immediate keys for new `agent+` addresses. That creates a separate identity; it does not grant customer or organization access. It is not the recommended onboarding path for customer work. Multiple API keys per account are supported, without revoking existing keys. ## Standard signup (email verification) If you're building a human-facing integration and want the user to verify their real email, use an email address the user controls: Step 1 — request a verification code: Step 2 — submit the 6-digit code from the verification email: Response: ## Using your API key Pass the returned `api_key` in the `x-api-key` header on every authenticated request: See [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request. "},{"slug":"content-agent","title":"Content Agent","description":"Use hosted creative presets and current image, video and composition primitives.","category":"Agents & Sandboxes","group":"Agents","source":"content-agent.mdx","body":"## Release Packs\n\nFor a song-centered content pack, use [Release Packs](/release-packs): collect\nessential context inline, preserve one job, quote the complete scope and produce\nreviewed media. New releases, catalog rediscovery, anniversaries, reissues and\nremixes use the same brief-driven path. These pack operations do not require an\nexisting artist or repository; availability depends on deployed host tools.\n\n## Hosted workflows\n\n`POST /api/content/create` retains the hosted preset workflow. Supply the authorized\n`artist_account_id`, optional `template`, `images`, `songs`, `batch` (defaults to 1; range 1–30), `lipsync`, `upscale`\nand `caption_length`. Discover templates through `/api/content/templates` and its\ndetail route. The response contains `runIds`; poll `/api/tasks/runs?runId=...` until\nterminal. Report failures and inspect the final artifact before delivery.\n\nHosted lipsync is a supported preset intent. The coordinated API/worker repair\nrestores the selected song window to the fixed audio-to-video path; that repaired\njourney is release-pending until deployment and actual output verification.\n\n## Direct primitives\n\nFor images use `POST /api/content/image` with `prompt` and up to 10 unique\n`image_urls`. The house model is Muse Image, switching to its edit path when\nreferences are present. New clients must use `image_urls`; compatibility aliases\nare translated by the reconciliation release.\n\nFor video use `POST /api/content/video` with `prompt`, optional `image_url` and\n`end_image_url`, integer `duration` 5–15, and `resolution` `480P` or `768P`.\nThe house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model,\nreference-only, extend, `video_url` or `audio_url` request control. Unsupported\nsemantic inputs return 400 in the reconciliation release, before paid generation.\n\nThe dedicated `/api/content/lipsync` primitive restores the existing fixed LTX\nmodel for the worker; it is not assumed available on an older deployment.\nCaption, transcribe, analyze, upscale and edit have their own endpoint contracts.\nLocal ffmpeg composition can crop, trim, overlay or mux a song; it does not create\nmouth synchronization or prove a hosted generation succeeded.\n\n## Cost and evidence\n\nEach generation/inference stage can consume credits. `/api/content/estimate`\nreturns an advisory estimate, not a guaranteed price or complete final ledger.\nA later failed composition does not imply that completed upstream work was free.\nOn insufficient credits, surface `billingUrl` and stop. Consult [Credits](/credits).\n\nRecord image inspection, motion review and audio playback. The worker checks for\nan audio stream on lipsync output before composition; perceptual mouth alignment\nstill requires inspection. Automated checks do not replace human QA.\n\n## Slack integration\n\nThe separate [Slack webhook](/api-reference/content-agent/webhook) handles\nContent Agent mentions. Its request/event contract and the [completion callback](/api-reference/content-agent/callback) are distinct from direct primitives.\nWorkspace operators must configure the Slack application and service credentials;\ninstalling a creative skill does not install that integration.\n\n### Set up the Slack app\n\nCreate a Slack app, enable the `chat:write` and `app_mentions:read` bot scopes,\nand subscribe to `app_mention` events at\n`https://api.recoupable.dev/api/content-agent/slack`. Install it in the intended\nworkspace and invite it to the channel.\n\nConfigure `SLACK_CONTENT_BOT_TOKEN`, `SLACK_CONTENT_SIGNING_SECRET`,\n`CODING_AGENT_CALLBACK_SECRET` and `REDIS_URL` in the Recoup API service.\nThe existing Tasks worker uses the same `CODING_AGENT_CALLBACK_SECRET` for\ncompletion callbacks and its authorized Recoup credential and API base URL.\nKeep these values in service secret settings. The current callback secret name\nis `CODING_AGENT_CALLBACK_SECRET`; `CONTENT_AGENT_CALLBACK_SECRET` is obsolete.\n\nSlack sends the signed-request headers listed in the [webhook reference](/api-reference/content-agent/webhook).\nKeep `SLACK_CONTENT_SIGNING_SECRET` matched to that Slack app. Setup requests\nwith missing or invalid signatures, a timestamp outside the five-minute window,\nor an unavailable signing secret return `401` with plain-text `Unauthorized`.\nA verified setup request returns its JSON challenge. If setup fails, check the\napp secret and service clock against [Slack request verification](https://docs.slack.dev/authentication/verifying-requests-from-slack/).\nOrdinary event acknowledgements come from the Slack adapter; they acknowledge\nreceipt while generation completes separately.\n\nMention the installed bot with the authorized artist account UUID:\n\n```text\n@RecoupContentAgent ARTIST_ACCOUNT_UUID artist-caption-bedroom batch=1\n```\n\nThe template, `batch=N` (1–30) and `lipsync` flags are optional. Check the\nacknowledgment, then inspect the completed result or reported failure in the\nthread. Generated output still requires the inspection described above.\n","headings":[{"title":"Release Packs","id":"release-packs"},{"title":"Hosted workflows","id":"hosted-workflows"},{"title":"Direct primitives","id":"direct-primitives"},{"title":"Cost and evidence","id":"cost-and-evidence"},{"title":"Slack integration","id":"slack-integration"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"release-packs\",\n children: \"Release Packs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a song-centered content pack, use \", _jsx(_components.a, {\n href: \"/release-packs\",\n children: \"Release Packs\"\n }), \": collect\\nessential context inline, preserve one job, quote the complete scope and produce\\nreviewed media. New releases, catalog rediscovery, anniversaries, reissues and\\nremixes use the same brief-driven path. These pack operations do not require an\\nexisting artist or repository; availability depends on deployed host tools.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hosted-workflows\",\n children: \"Hosted workflows\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/create\"\n }), \" retains the hosted preset workflow. Supply the authorized\\n\", _jsx(_components.code, {\n children: \"artist_account_id\"\n }), \", optional \", _jsx(_components.code, {\n children: \"template\"\n }), \", \", _jsx(_components.code, {\n children: \"images\"\n }), \", \", _jsx(_components.code, {\n children: \"songs\"\n }), \", \", _jsx(_components.code, {\n children: \"batch\"\n }), \" (defaults to 1; range 1–30), \", _jsx(_components.code, {\n children: \"lipsync\"\n }), \", \", _jsx(_components.code, {\n children: \"upscale\"\n }), \"\\nand \", _jsx(_components.code, {\n children: \"caption_length\"\n }), \". Discover templates through \", _jsx(_components.code, {\n children: \"/api/content/templates\"\n }), \" and its\\ndetail route. The response contains \", _jsx(_components.code, {\n children: \"runIds\"\n }), \"; poll \", _jsx(_components.code, {\n children: \"/api/tasks/runs?runId=...\"\n }), \" until\\nterminal. Report failures and inspect the final artifact before delivery.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Hosted lipsync is a supported preset intent. The coordinated API/worker repair\\nrestores the selected song window to the fixed audio-to-video path; that repaired\\njourney is release-pending until deployment and actual output verification.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"direct-primitives\",\n children: \"Direct primitives\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For images use \", _jsx(_components.code, {\n children: \"POST /api/content/image\"\n }), \" with \", _jsx(_components.code, {\n children: \"prompt\"\n }), \" and up to 10 unique\\n\", _jsx(_components.code, {\n children: \"image_urls\"\n }), \". The house model is Muse Image, switching to its edit path when\\nreferences are present. New clients must use \", _jsx(_components.code, {\n children: \"image_urls\"\n }), \"; compatibility aliases\\nare translated by the reconciliation release.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For video use \", _jsx(_components.code, {\n children: \"POST /api/content/video\"\n }), \" with \", _jsx(_components.code, {\n children: \"prompt\"\n }), \", optional \", _jsx(_components.code, {\n children: \"image_url\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"end_image_url\"\n }), \", integer \", _jsx(_components.code, {\n children: \"duration\"\n }), \" 5–15, and \", _jsx(_components.code, {\n children: \"resolution\"\n }), \" \", _jsx(_components.code, {\n children: \"480P\"\n }), \" or \", _jsx(_components.code, {\n children: \"768P\"\n }), \".\\nThe house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model,\\nreference-only, extend, \", _jsx(_components.code, {\n children: \"video_url\"\n }), \" or \", _jsx(_components.code, {\n children: \"audio_url\"\n }), \" request control. Unsupported\\nsemantic inputs return 400 in the reconciliation release, before paid generation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The dedicated \", _jsx(_components.code, {\n children: \"/api/content/lipsync\"\n }), \" primitive restores the existing fixed LTX\\nmodel for the worker; it is not assumed available on an older deployment.\\nCaption, transcribe, analyze, upscale and edit have their own endpoint contracts.\\nLocal ffmpeg composition can crop, trim, overlay or mux a song; it does not create\\nmouth synchronization or prove a hosted generation succeeded.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"cost-and-evidence\",\n children: \"Cost and evidence\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each generation/inference stage can consume credits. \", _jsx(_components.code, {\n children: \"/api/content/estimate\"\n }), \"\\nreturns an advisory estimate, not a guaranteed price or complete final ledger.\\nA later failed composition does not imply that completed upstream work was free.\\nOn insufficient credits, surface \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \" and stop. Consult \", _jsx(_components.a, {\n href: \"/credits\",\n children: \"Credits\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Record image inspection, motion review and audio playback. The worker checks for\\nan audio stream on lipsync output before composition; perceptual mouth alignment\\nstill requires inspection. Automated checks do not replace human QA.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"slack-integration\",\n children: \"Slack integration\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The separate \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/webhook\",\n children: \"Slack webhook\"\n }), \" handles\\nContent Agent mentions. Its request/event contract and the \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/callback\",\n children: \"completion callback\"\n }), \" are distinct from direct primitives.\\nWorkspace operators must configure the Slack application and service credentials;\\ninstalling a creative skill does not install that integration.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"set-up-the-slack-app\",\n children: \"Set up the Slack app\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Create a Slack app, enable the \", _jsx(_components.code, {\n children: \"chat:write\"\n }), \" and \", _jsx(_components.code, {\n children: \"app_mentions:read\"\n }), \" bot scopes,\\nand subscribe to \", _jsx(_components.code, {\n children: \"app_mention\"\n }), \" events at\\n\", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/api/content-agent/slack\"\n }), \". Install it in the intended\\nworkspace and invite it to the channel.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Configure \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_BOT_TOKEN\"\n }), \", \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_SIGNING_SECRET\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \" and \", _jsx(_components.code, {\n children: \"REDIS_URL\"\n }), \" in the Recoup API service.\\nThe existing Tasks worker uses the same \", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \" for\\ncompletion callbacks and its authorized Recoup credential and API base URL.\\nKeep these values in service secret settings. The current callback secret name\\nis \", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \"; \", _jsx(_components.code, {\n children: \"CONTENT_AGENT_CALLBACK_SECRET\"\n }), \" is obsolete.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Slack sends the signed-request headers listed in the \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/webhook\",\n children: \"webhook reference\"\n }), \".\\nKeep \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_SIGNING_SECRET\"\n }), \" matched to that Slack app. Setup requests\\nwith missing or invalid signatures, a timestamp outside the five-minute window,\\nor an unavailable signing secret return \", _jsx(_components.code, {\n children: \"401\"\n }), \" with plain-text \", _jsx(_components.code, {\n children: \"Unauthorized\"\n }), \".\\nA verified setup request returns its JSON challenge. If setup fails, check the\\napp secret and service clock against \", _jsx(_components.a, {\n href: \"https://docs.slack.dev/authentication/verifying-requests-from-slack/\",\n children: \"Slack request verification\"\n }), \".\\nOrdinary event acknowledgements come from the Slack adapter; they acknowledge\\nreceipt while generation completes separately.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Mention the installed bot with the authorized artist account UUID:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-text\",\n children: \"@RecoupContentAgent ARTIST_ACCOUNT_UUID artist-caption-bedroom batch=1\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The template, \", _jsx(_components.code, {\n children: \"batch=N\"\n }), \" (1–30) and \", _jsx(_components.code, {\n children: \"lipsync\"\n }), \" flags are optional. Check the\\nacknowledgment, then inspect the completed result or reported failure in the\\nthread. Generated output still requires the inspection described above.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Content Agent Use hosted creative presets and current image, video and composition primitives. Agents & Sandboxes Agents ## Release Packs For a song-centered content pack, use [Release Packs](/release-packs): collect essential context inline, preserve one job, quote the complete scope and produce reviewed media. New releases, catalog rediscovery, anniversaries, reissues and remixes use the same brief-driven path. These pack operations do not require an existing artist or repository; availability depends on deployed host tools. ## Hosted workflows `POST /api/content/create` retains the hosted preset workflow. Supply the authorized `artist_account_id`, optional `template`, `images`, `songs`, `batch` (defaults to 1; range 1–30), `lipsync`, `upscale` and `caption_length`. Discover templates through `/api/content/templates` and its detail route. The response contains `runIds`; poll `/api/tasks/runs?runId=...` until terminal. Report failures and inspect the final artifact before delivery. Hosted lipsync is a supported preset intent. The coordinated API/worker repair restores the selected song window to the fixed audio-to-video path; that repaired journey is release-pending until deployment and actual output verification. ## Direct primitives For images use `POST /api/content/image` with `prompt` and up to 10 unique `image_urls`. The house model is Muse Image, switching to its edit path when references are present. New clients must use `image_urls`; compatibility aliases are translated by the reconciliation release. For video use `POST /api/content/video` with `prompt`, optional `image_url` and `end_image_url`, integer `duration` 5–15, and `resolution` `480P` or `768P`. The house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model, reference-only, extend, `video_url` or `audio_url` request control. Unsupported semantic inputs return 400 in the reconciliation release, before paid generation. The dedicated `/api/content/lipsync` primitive restores the existing fixed LTX model for the worker; it is not assumed available on an older deployment. Caption, transcribe, analyze, upscale and edit have their own endpoint contracts. Local ffmpeg composition can crop, trim, overlay or mux a song; it does not create mouth synchronization or prove a hosted generation succeeded. ## Cost and evidence Each generation/inference stage can consume credits. `/api/content/estimate` returns an advisory estimate, not a guaranteed price or complete final ledger. A later failed composition does not imply that completed upstream work was free. On insufficient credits, surface `billingUrl` and stop. Consult [Credits](/credits). Record image inspection, motion review and audio playback. The worker checks for an audio stream on lipsync output before composition; perceptual mouth alignment still requires inspection. Automated checks do not replace human QA. ## Slack integration The separate [Slack webhook](/api-reference/content-agent/webhook) handles Content Agent mentions. Its request/event contract and the [completion callback](/api-reference/content-agent/callback) are distinct from direct primitives. Workspace operators must configure the Slack application and service credentials; installing a creative skill does not install that integration. ### Set up the Slack app Create a Slack app, enable the `chat:write` and `app_mentions:read` bot scopes, and subscribe to `app_mention` events at `https://api.recoupable.dev/api/content-agent/slack`. Install it in the intended workspace and invite it to the channel. Configure `SLACK_CONTENT_BOT_TOKEN`, `SLACK_CONTENT_SIGNING_SECRET`, `CODING_AGENT_CALLBACK_SECRET` and `REDIS_URL` in the Recoup API service. The existing Tasks worker uses the same `CODING_AGENT_CALLBACK_SECRET` for completion callbacks and its authorized Recoup credential and API base URL. Keep these values in service secret settings. The current callback secret name is `CODING_AGENT_CALLBACK_SECRET`; `CONTENT_AGENT_CALLBACK_SECRET` is obsolete. Slack sends the signed-request headers listed in the [webhook reference](/api-reference/content-agent/webhook). Keep `SLACK_CONTENT_SIGNING_SECRET` matched to that Slack app. Setup requests with missing or invalid signatures, a timestamp outside the five-minute window, or an unavailable signing secret return `401` with plain-text `Unauthorized`. A verified setup request returns its JSON challenge. If setup fails, check the app secret and service clock against [Slack request verification](https://docs.slack.dev/authentication/verifying-requests-from-slack/). Ordinary event acknowledgements come from the Slack adapter; they acknowledge receipt while generation completes separately. Mention the installed bot with the authorized artist account UUID: The template, `batch=N` (1–30) and `lipsync` flags are optional. Check the acknowledgment, then inspect the completed result or reported failure in the thread. Generated output still requires the inspection described above. "},{"slug":"release-packs","title":"Release Packs","description":"Turn a song and a campaign occasion into a coherent set of reviewed music assets.","category":"Agents & Sandboxes","group":"Agents","source":"release-packs.mdx","body":"\nThis contract accompanies the Release Packs first-use rollout. Availability depends\non the deployed API and the tools exposed by your connected host. A plugin download\nor successful sign-in alone does not establish that generation is available.\n\n\n## Start with the music\n\nAsk your agent: **“Create a release pack for this song.”** Supply the audio or an\naccessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a\nreissue, a remix, or a catalog rediscovery campaign.\n\nThe agent reuses information you have already supplied and any selected, accessible\nRecoup context. It asks only for essential gaps: the correct artist and recording,\nthe occasion, and artwork or creative direction. You can ask it to propose a\ndirection from the music instead. It must distinguish that proposal from your\nestablished branding.\n\nYou do not need an existing artist profile, Spotify history, connected social\naccounts, a catalog import, or a GitHub workspace to prepare a pack. An empty\nRecoup roster is a valid new account. Sign in through your host's Recoup connection\nwhen the agent needs authenticated execution; it should resume the same request.\n\n**“Plan a release” is a different request.** It produces a creative brief and\nrollout plan. Ask for a release pack to produce media, or ask for both so the agent\ncan carry the same brief into production.\n\nWhen ChatGPT supplies a selected attachment to the upload tool, the tool accepts\nits host file reference directly. It imports the selected download URL into\nprivate Recoup storage and validates the actual media bytes. Other hosts can use\nthe supported source URL, inline or signed-upload modes; a filename alone is not\nan accessible recording.\n\nFor direct API uploads, small inline files are limited to approximately 3 MB\n(4,000,000 base64 characters). For normal song files, request a private signed\nupload, transfer the file and finalize it, or import an accessible HTTPS source\nup to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable\nonly after the agent can access its actual bytes. Audio formats include MP3,\nWAV, FLAC and M4A. Source images can be PNG, JPEG or WebP.\n\n## What the brief contains\n\n| Input | How it is used |\n| --- | --- |\n| Artist, song and exact version | Keep the recording, remix and artist identity consistent |\n| Real audio and selected hook | Put the correct music into the finished clips |\n| Occasion | Choose relevant concepts and copy rather than defaulting to “out now” |\n| Creative direction or references | Keep a coherent visual family and voice |\n| Primary action and destination | Write relevant captions without inventing links |\n| Audience, platforms and constraints | Choose useful formats and respect supplied boundaries |\n\nFor anniversaries, the original release date and campaign date are separate. If\nthe original date is unknown, the agent must obtain it before making dated\nanniversary claims. A catalog request needs a bounded selection of recordings;\nit must not silently generate a pack for every track.\n\nResearch enriches the brief. Missing research or audience metrics should not\nforce unrelated onboarding or fabricated statistics. Existing artwork and\nsupplied preferences can be enough to propose strong creative work. An artist's\nface is optional; artwork-led and typographic work are valid directions.\n\n## Scope and budget before generation\n\n### Save a direction and choose how involved to be\n\nConnections exposing `brief.creative_context` can save an established visual world,\na rough idea or an exploratory direction in the same pack. The field is optional;\nolder connections keep their existing brief behavior. It holds attributed references,\nup to three direction candidates and the selected candidate.\n\n**Run with it** uses `working_mode: \"autonomous\"`: the agent records its direction\nselection and continues within the approved budget. **Show me directions first**\nuses `working_mode: \"guided\"`: final quoting and generation wait for a selection\nrecorded from the customer's feedback. An agent's own choice does not count as\ncustomer selection in guided mode.\n\nSave candidates under `directions`, then record `selection.direction_id`,\n`selection.selected_by` (`customer` or `agent`) and a short `decision_note`.\nDirection and reference IDs must be unique within this brief; selections cannot\npoint to another pack's candidate. Updating these fields follows the same saved\njob and expected-revision rules and invalidates its earlier quote.\n\nA reference manifest item declares its source, media type and `usage`:\n`reference_only` is inspiration, while `production` explicitly makes an image\neligible as a selected generation input. Only production images referenced by\nthe chosen direction enter the renderer. Together with explicit legacy\n`reference_image_urls`, at most five distinct production images are supported.\nThe original source manifest stays unchanged when production inputs are resolved.\n\nThis first slice accepts supplied direction boards through an optional `board_url`.\nIt does not add automatic mood-board generation, public-profile harvesting or new\nasset types. Discover those capabilities before promising them. An optional\ncustomer checkpoint does not authorize additional spending or publication.\n\nPreparation and generation are separate operations. Before paid production, the\nagent shows the proposed direction, deliverables, cost scope and maximum budget.\nThe quote binds the current brief and deliverables. Changing the song or scope\nrequires a new quote; an earlier approval cannot silently authorize different work.\n\nThe default scope is 15 creative pieces: eight video clips, four quote cards, one\nartwork, one carousel and one visualizer, with captions. A carousel is one piece;\nits slides and alternate aspect ratios are identified as components or variants.\nYou can request a smaller scope. The quote must describe the actual selected work,\nincluding chargeable stages and any retry allowance. Current quotes charge for\nimage and motion generation; captioning, audio analysis, composition and inspection\nare included without an added customer fee. The approved amount is held before\nproduction; unused stages are refunded. A new paid retry needs its own quote.\n\nThe older `GET /api/content/estimate` is an advisory per-video estimate. It is not\na complete Release Packs quote. On insufficient credits the agent surfaces the\nreturned `billingUrl`; it must not buy credits, switch accounts or retry paid\ngeneration automatically.\n\n## One job, with visible progress\n\nThe pack retains its brief, revision, quote, individual asset states and completed\nwork. Signing in, waiting for a render, or recovering from a failed stage should\nnot make you repeat the request or regenerate the whole pack.\n\nThe first representative asset is produced and inspected early. The agent then\ncontinues the agreed batch within your budget, unless you requested a preview\ncheckpoint. Progress distinguishes requested, generated, inspected and delivered\nassets. A partly generated pack is reported as partial.\n\n## Review and delivery\n\nA finished music-bearing asset must contain the selected recording and the correct\naudio window. Inspection covers sound, timing, duration, framing, readable text,\nvisual consistency and the campaign brief. A render request, a prompt or a concept\nis not a finished asset. Static image inspection and video inspection are separate.\n\nDelivery includes previews, usable files, captions, a manifest and any unresolved\ngaps. The agent retains successful work when a stage fails and retries only within\nthe approved scope and budget. Release Packs stops at the assets: posting and\nscheduling need a separate request.\n\nAfter delivery, you can save confirmed artist preferences for next time. A\none-off creative proposal must not overwrite established branding or become a\npermanent public knowledge-base entry automatically.\n\n## API and connected tools\n\nConnected operations are `prepare_release_pack`, `get_release_pack`,\n`estimate_release_pack`, `generate_release_pack`, `retry_release_pack`,\n`upload_release_pack_asset` and `export_release_pack`. Discover their actual schemas\nin the connected host; older connections may need a refresh.\n\nThe shared API contract separates preparation, reading, quoting, generation,\nretry and selected-asset upload. Connected tools use the same account and job\nrules. Credentials remain with the host; an agent must not extract OAuth tokens\ninto REST requests or ask for an API key to compensate for a missing MCP tool.\n\nIf a required operation is unavailable, the agent should name that operation,\nretain the brief and explain the next step. It must not claim the entire account\nis disconnected or present a plan as completed media.\n","headings":[{"title":"Start with the music","id":"start-with-the-music"},{"title":"What the brief contains","id":"what-the-brief-contains"},{"title":"Scope and budget before generation","id":"scope-and-budget-before-generation"},{"title":"One job, with visible progress","id":"one-job-with-visible-progress"},{"title":"Review and delivery","id":"review-and-delivery"},{"title":"API and connected tools","id":"api-and-connected-tools"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n }, {Info} = _components;\n if (!Info) _missingMdxReference(\"Info\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Info, {\n children: _jsx(_components.p, {\n children: \"This contract accompanies the Release Packs first-use rollout. Availability depends\\non the deployed API and the tools exposed by your connected host. A plugin download\\nor successful sign-in alone does not establish that generation is available.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"start-with-the-music\",\n children: \"Start with the music\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Ask your agent: \", _jsx(_components.strong, {\n children: \"“Create a release pack for this song.”\"\n }), \" Supply the audio or an\\naccessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a\\nreissue, a remix, or a catalog rediscovery campaign.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The agent reuses information you have already supplied and any selected, accessible\\nRecoup context. It asks only for essential gaps: the correct artist and recording,\\nthe occasion, and artwork or creative direction. You can ask it to propose a\\ndirection from the music instead. It must distinguish that proposal from your\\nestablished branding.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"You do not need an existing artist profile, Spotify history, connected social\\naccounts, a catalog import, or a GitHub workspace to prepare a pack. An empty\\nRecoup roster is a valid new account. Sign in through your host's Recoup connection\\nwhen the agent needs authenticated execution; it should resume the same request.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"“Plan a release” is a different request.\"\n }), \" It produces a creative brief and\\nrollout plan. Ask for a release pack to produce media, or ask for both so the agent\\ncan carry the same brief into production.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"When ChatGPT supplies a selected attachment to the upload tool, the tool accepts\\nits host file reference directly. It imports the selected download URL into\\nprivate Recoup storage and validates the actual media bytes. Other hosts can use\\nthe supported source URL, inline or signed-upload modes; a filename alone is not\\nan accessible recording.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"For direct API uploads, small inline files are limited to approximately 3 MB\\n(4,000,000 base64 characters). For normal song files, request a private signed\\nupload, transfer the file and finalize it, or import an accessible HTTPS source\\nup to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable\\nonly after the agent can access its actual bytes. Audio formats include MP3,\\nWAV, FLAC and M4A. Source images can be PNG, JPEG or WebP.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-the-brief-contains\",\n children: \"What the brief contains\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Input\"\n }), _jsx(_components.th, {\n children: \"How it is used\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Artist, song and exact version\"\n }), _jsx(_components.td, {\n children: \"Keep the recording, remix and artist identity consistent\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Real audio and selected hook\"\n }), _jsx(_components.td, {\n children: \"Put the correct music into the finished clips\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Occasion\"\n }), _jsx(_components.td, {\n children: \"Choose relevant concepts and copy rather than defaulting to “out now”\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Creative direction or references\"\n }), _jsx(_components.td, {\n children: \"Keep a coherent visual family and voice\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Primary action and destination\"\n }), _jsx(_components.td, {\n children: \"Write relevant captions without inventing links\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Audience, platforms and constraints\"\n }), _jsx(_components.td, {\n children: \"Choose useful formats and respect supplied boundaries\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For anniversaries, the original release date and campaign date are separate. If\\nthe original date is unknown, the agent must obtain it before making dated\\nanniversary claims. A catalog request needs a bounded selection of recordings;\\nit must not silently generate a pack for every track.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Research enriches the brief. Missing research or audience metrics should not\\nforce unrelated onboarding or fabricated statistics. Existing artwork and\\nsupplied preferences can be enough to propose strong creative work. An artist's\\nface is optional; artwork-led and typographic work are valid directions.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"scope-and-budget-before-generation\",\n children: \"Scope and budget before generation\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"save-a-direction-and-choose-how-involved-to-be\",\n children: \"Save a direction and choose how involved to be\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connections exposing \", _jsx(_components.code, {\n children: \"brief.creative_context\"\n }), \" can save an established visual world,\\na rough idea or an exploratory direction in the same pack. The field is optional;\\nolder connections keep their existing brief behavior. It holds attributed references,\\nup to three direction candidates and the selected candidate.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Run with it\"\n }), \" uses \", _jsx(_components.code, {\n children: \"working_mode: \\\"autonomous\\\"\"\n }), \": the agent records its direction\\nselection and continues within the approved budget. \", _jsx(_components.strong, {\n children: \"Show me directions first\"\n }), \"\\nuses \", _jsx(_components.code, {\n children: \"working_mode: \\\"guided\\\"\"\n }), \": final quoting and generation wait for a selection\\nrecorded from the customer's feedback. An agent's own choice does not count as\\ncustomer selection in guided mode.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save candidates under \", _jsx(_components.code, {\n children: \"directions\"\n }), \", then record \", _jsx(_components.code, {\n children: \"selection.direction_id\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"selection.selected_by\"\n }), \" (\", _jsx(_components.code, {\n children: \"customer\"\n }), \" or \", _jsx(_components.code, {\n children: \"agent\"\n }), \") and a short \", _jsx(_components.code, {\n children: \"decision_note\"\n }), \".\\nDirection and reference IDs must be unique within this brief; selections cannot\\npoint to another pack's candidate. Updating these fields follows the same saved\\njob and expected-revision rules and invalidates its earlier quote.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A reference manifest item declares its source, media type and \", _jsx(_components.code, {\n children: \"usage\"\n }), \":\\n\", _jsx(_components.code, {\n children: \"reference_only\"\n }), \" is inspiration, while \", _jsx(_components.code, {\n children: \"production\"\n }), \" explicitly makes an image\\neligible as a selected generation input. Only production images referenced by\\nthe chosen direction enter the renderer. Together with explicit legacy\\n\", _jsx(_components.code, {\n children: \"reference_image_urls\"\n }), \", at most five distinct production images are supported.\\nThe original source manifest stays unchanged when production inputs are resolved.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This first slice accepts supplied direction boards through an optional \", _jsx(_components.code, {\n children: \"board_url\"\n }), \".\\nIt does not add automatic mood-board generation, public-profile harvesting or new\\nasset types. Discover those capabilities before promising them. An optional\\ncustomer checkpoint does not authorize additional spending or publication.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Preparation and generation are separate operations. Before paid production, the\\nagent shows the proposed direction, deliverables, cost scope and maximum budget.\\nThe quote binds the current brief and deliverables. Changing the song or scope\\nrequires a new quote; an earlier approval cannot silently authorize different work.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The default scope is 15 creative pieces: eight video clips, four quote cards, one\\nartwork, one carousel and one visualizer, with captions. A carousel is one piece;\\nits slides and alternate aspect ratios are identified as components or variants.\\nYou can request a smaller scope. The quote must describe the actual selected work,\\nincluding chargeable stages and any retry allowance. Current quotes charge for\\nimage and motion generation; captioning, audio analysis, composition and inspection\\nare included without an added customer fee. The approved amount is held before\\nproduction; unused stages are refunded. A new paid retry needs its own quote.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The older \", _jsx(_components.code, {\n children: \"GET /api/content/estimate\"\n }), \" is an advisory per-video estimate. It is not\\na complete Release Packs quote. On insufficient credits the agent surfaces the\\nreturned \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \"; it must not buy credits, switch accounts or retry paid\\ngeneration automatically.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"one-job-with-visible-progress\",\n children: \"One job, with visible progress\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The pack retains its brief, revision, quote, individual asset states and completed\\nwork. Signing in, waiting for a render, or recovering from a failed stage should\\nnot make you repeat the request or regenerate the whole pack.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The first representative asset is produced and inspected early. The agent then\\ncontinues the agreed batch within your budget, unless you requested a preview\\ncheckpoint. Progress distinguishes requested, generated, inspected and delivered\\nassets. A partly generated pack is reported as partial.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"review-and-delivery\",\n children: \"Review and delivery\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"A finished music-bearing asset must contain the selected recording and the correct\\naudio window. Inspection covers sound, timing, duration, framing, readable text,\\nvisual consistency and the campaign brief. A render request, a prompt or a concept\\nis not a finished asset. Static image inspection and video inspection are separate.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Delivery includes previews, usable files, captions, a manifest and any unresolved\\ngaps. The agent retains successful work when a stage fails and retries only within\\nthe approved scope and budget. Release Packs stops at the assets: posting and\\nscheduling need a separate request.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"After delivery, you can save confirmed artist preferences for next time. A\\none-off creative proposal must not overwrite established branding or become a\\npermanent public knowledge-base entry automatically.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"api-and-connected-tools\",\n children: \"API and connected tools\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connected operations are \", _jsx(_components.code, {\n children: \"prepare_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"get_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"estimate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"generate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"retry_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"upload_release_pack_asset\"\n }), \" and \", _jsx(_components.code, {\n children: \"export_release_pack\"\n }), \". Discover their actual schemas\\nin the connected host; older connections may need a refresh.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The shared API contract separates preparation, reading, quoting, generation,\\nretry and selected-asset upload. Connected tools use the same account and job\\nrules. Credentials remain with the host; an agent must not extract OAuth tokens\\ninto REST requests or ask for an API key to compensate for a missing MCP tool.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If a required operation is unavailable, the agent should name that operation,\\nretain the brief and explain the next step. It must not claim the entire account\\nis disconnected or present a plan as completed media.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Release Packs Turn a song and a campaign occasion into a coherent set of reviewed music assets. Agents & Sandboxes Agents This contract accompanies the Release Packs first-use rollout. Availability depends on the deployed API and the tools exposed by your connected host. A plugin download or successful sign-in alone does not establish that generation is available. ## Start with the music Ask your agent: **“Create a release pack for this song.”** Supply the audio or an accessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a reissue, a remix, or a catalog rediscovery campaign. The agent reuses information you have already supplied and any selected, accessible Recoup context. It asks only for essential gaps: the correct artist and recording, the occasion, and artwork or creative direction. You can ask it to propose a direction from the music instead. It must distinguish that proposal from your established branding. You do not need an existing artist profile, Spotify history, connected social accounts, a catalog import, or a GitHub workspace to prepare a pack. An empty Recoup roster is a valid new account. Sign in through your host's Recoup connection when the agent needs authenticated execution; it should resume the same request. **“Plan a release” is a different request.** It produces a creative brief and rollout plan. Ask for a release pack to produce media, or ask for both so the agent can carry the same brief into production. When ChatGPT supplies a selected attachment to the upload tool, the tool accepts its host file reference directly. It imports the selected download URL into private Recoup storage and validates the actual media bytes. Other hosts can use the supported source URL, inline or signed-upload modes; a filename alone is not an accessible recording. For direct API uploads, small inline files are limited to approximately 3 MB (4,000,000 base64 characters). For normal song files, request a private signed upload, transfer the file and finalize it, or import an accessible HTTPS source up to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable only after the agent can access its actual bytes. Audio formats include MP3, WAV, FLAC and M4A. Source images can be PNG, JPEG or WebP. ## What the brief contains | Input | How it is used | | --- | --- | | Artist, song and exact version | Keep the recording, remix and artist identity consistent | | Real audio and selected hook | Put the correct music into the finished clips | | Occasion | Choose relevant concepts and copy rather than defaulting to “out now” | | Creative direction or references | Keep a coherent visual family and voice | | Primary action and destination | Write relevant captions without inventing links | | Audience, platforms and constraints | Choose useful formats and respect supplied boundaries | For anniversaries, the original release date and campaign date are separate. If the original date is unknown, the agent must obtain it before making dated anniversary claims. A catalog request needs a bounded selection of recordings; it must not silently generate a pack for every track. Research enriches the brief. Missing research or audience metrics should not force unrelated onboarding or fabricated statistics. Existing artwork and supplied preferences can be enough to propose strong creative work. An artist's face is optional; artwork-led and typographic work are valid directions. ## Scope and budget before generation ### Save a direction and choose how involved to be Connections exposing `brief.creative_context` can save an established visual world, a rough idea or an exploratory direction in the same pack. The field is optional; older connections keep their existing brief behavior. It holds attributed references, up to three direction candidates and the selected candidate. **Run with it** uses `working_mode: \"autonomous\"`: the agent records its direction selection and continues within the approved budget. **Show me directions first** uses `working_mode: \"guided\"`: final quoting and generation wait for a selection recorded from the customer's feedback. An agent's own choice does not count as customer selection in guided mode. Save candidates under `directions`, then record `selection.direction_id`, `selection.selected_by` (`customer` or `agent`) and a short `decision_note`. Direction and reference IDs must be unique within this brief; selections cannot point to another pack's candidate. Updating these fields follows the same saved job and expected-revision rules and invalidates its earlier quote. A reference manifest item declares its source, media type and `usage`: `reference_only` is inspiration, while `production` explicitly makes an image eligible as a selected generation input. Only production images referenced by the chosen direction enter the renderer. Together with explicit legacy `reference_image_urls`, at most five distinct production images are supported. The original source manifest stays unchanged when production inputs are resolved. This first slice accepts supplied direction boards through an optional `board_url`. It does not add automatic mood-board generation, public-profile harvesting or new asset types. Discover those capabilities before promising them. An optional customer checkpoint does not authorize additional spending or publication. Preparation and generation are separate operations. Before paid production, the agent shows the proposed direction, deliverables, cost scope and maximum budget. The quote binds the current brief and deliverables. Changing the song or scope requires a new quote; an earlier approval cannot silently authorize different work. The default scope is 15 creative pieces: eight video clips, four quote cards, one artwork, one carousel and one visualizer, with captions. A carousel is one piece; its slides and alternate aspect ratios are identified as components or variants. You can request a smaller scope. The quote must describe the actual selected work, including chargeable stages and any retry allowance. Current quotes charge for image and motion generation; captioning, audio analysis, composition and inspection are included without an added customer fee. The approved amount is held before production; unused stages are refunded. A new paid retry needs its own quote. The older `GET /api/content/estimate` is an advisory per-video estimate. It is not a complete Release Packs quote. On insufficient credits the agent surfaces the returned `billingUrl`; it must not buy credits, switch accounts or retry paid generation automatically. ## One job, with visible progress The pack retains its brief, revision, quote, individual asset states and completed work. Signing in, waiting for a render, or recovering from a failed stage should not make you repeat the request or regenerate the whole pack. The first representative asset is produced and inspected early. The agent then continues the agreed batch within your budget, unless you requested a preview checkpoint. Progress distinguishes requested, generated, inspected and delivered assets. A partly generated pack is reported as partial. ## Review and delivery A finished music-bearing asset must contain the selected recording and the correct audio window. Inspection covers sound, timing, duration, framing, readable text, visual consistency and the campaign brief. A render request, a prompt or a concept is not a finished asset. Static image inspection and video inspection are separate. Delivery includes previews, usable files, captions, a manifest and any unresolved gaps. The agent retains successful work when a stage fails and retries only within the approved scope and budget. Release Packs stops at the assets: posting and scheduling need a separate request. After delivery, you can save confirmed artist preferences for next time. A one-off creative proposal must not overwrite established branding or become a permanent public knowledge-base entry automatically. ## API and connected tools Connected operations are `prepare_release_pack`, `get_release_pack`, `estimate_release_pack`, `generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and `export_release_pack`. Discover their actual schemas in the connected host; older connections may need a refresh. The shared API contract separates preparation, reading, quoting, generation, retry and selected-asset upload. Connected tools use the same account and job rules. Credentials remain with the host; an agent must not extract OAuth tokens into REST requests or ask for an API key to compensate for a missing MCP tool. If a required operation is unavailable, the agent should name that operation, retain the brief and explain the next step. It must not claim the entire account is disconnected or present a plan as completed media. "},{"slug":"api-reference/templates/list","title":"List Templates","description":"List templates","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/agents/templates","spec":"templates.json"},"searchText":"List Templates List templates Agents & Sandboxes Templates GET /api/agents/templates "},{"slug":"api-reference/templates/create","title":"Create Template","description":"Create a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/templates","spec":"templates.json"},"searchText":"Create Template Create a template Agents & Sandboxes Templates POST /api/agents/templates "},{"slug":"api-reference/templates/update","title":"Update Template","description":"Update a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/agents/templates/{id}","spec":"templates.json"},"searchText":"Update Template Update a template Agents & Sandboxes Templates PATCH /api/agents/templates/{id} "},{"slug":"api-reference/templates/delete","title":"Delete Template","description":"Delete a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/agents/templates/{id}","spec":"templates.json"},"searchText":"Delete Template Delete a template Agents & Sandboxes Templates DELETE /api/agents/templates/{id} "},{"slug":"api-reference/templates/favorite","title":"Favorite Template","description":"Toggle favorite on a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/favorite.mdx","body":"","headings":[],"api":{"method":"PUT","path":"/api/agents/templates/{id}/favorite","spec":"templates.json"},"searchText":"Favorite Template Toggle favorite on a template Agents & Sandboxes Templates PUT /api/agents/templates/{id}/favorite "},{"slug":"api-reference/tasks/get","title":"Get Tasks","description":"Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/tasks","spec":"releases.json"},"searchText":"Get Tasks Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id. Agents & Sandboxes Tasks GET /api/tasks "},{"slug":"api-reference/tasks/create","title":"Create Task","description":"Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array).","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/tasks","spec":"releases.json"},"searchText":"Create Task Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array). Agents & Sandboxes Tasks POST /api/tasks "},{"slug":"api-reference/tasks/update","title":"Update Task","description":"Update scheduled task","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/tasks","spec":"releases.json"},"searchText":"Update Task Update scheduled task Agents & Sandboxes Tasks PATCH /api/tasks "},{"slug":"api-reference/tasks/delete","title":"Delete Task","description":"Delete scheduled task","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/tasks","spec":"releases.json"},"searchText":"Delete Task Delete scheduled task Agents & Sandboxes Tasks DELETE /api/tasks "},{"slug":"api-reference/tasks/runs","title":"Get Task Runs","description":"Get task runs","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/runs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/tasks/runs","spec":"releases.json"},"searchText":"Get Task Runs Get task runs Agents & Sandboxes Tasks GET /api/tasks/runs "},{"slug":"api-reference/content-agent/webhook","title":"Slack Webhook","description":"Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread.","category":"Agents & Sandboxes","group":"Content Agent","source":"api-reference/content-agent/webhook.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content-agent/{platform}","spec":"content.json"},"searchText":"Slack Webhook Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread. Agents & Sandboxes Content Agent POST /api/content-agent/{platform} "},{"slug":"api-reference/content-agent/callback","title":"Task Callback","description":"Internal worker callback for a configured content agent. Requires the shared callback secret in x-callback-secret. Public content creation uses POST /api/content/create.","category":"Agents & Sandboxes","group":"Content Agent","source":"api-reference/content-agent/callback.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content-agent/callback","spec":"content.json"},"searchText":"Task Callback Internal worker callback for a configured content agent. Requires the shared callback secret in x-callback-secret. Public content creation uses POST /api/content/create. Agents & Sandboxes Content Agent POST /api/content-agent/callback "},{"slug":"api-reference/sandboxes/list","title":"List Sandboxes","description":"List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandboxes","spec":"content.json"},"searchText":"List Sandboxes List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes GET /api/sandboxes "},{"slug":"api-reference/sandboxes/create","title":"Create Sandbox","description":"Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes","spec":"content.json"},"searchText":"Create Sandbox Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes "},{"slug":"api-reference/sandboxes/snapshot","title":"Update Snapshot","description":"Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/snapshot.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sandboxes","spec":"content.json"},"searchText":"Update Snapshot Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files. Agents & Sandboxes Sandboxes PATCH /api/sandboxes "},{"slug":"api-reference/sandboxes/delete","title":"Delete Sandbox","description":"Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/sandboxes","spec":"content.json"},"searchText":"Delete Sandbox Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes DELETE /api/sandboxes "},{"slug":"api-reference/sandboxes/setup","title":"Setup Sandbox","description":"Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/setup.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/setup","spec":"content.json"},"searchText":"Setup Sandbox Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes/setup "},{"slug":"api-reference/sandboxes/get-file","title":"Get File Contents","description":"Read a file from the authenticated account's Git-backed repository, or an explicitly authorized target account's repository, including resolved submodule paths, on `main`. The repository comes from the [account's snapshot](/api-reference/sandboxes/list). Authenticate with `x-api-key` or an Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/get-file.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandboxes/file","spec":"content.json"},"searchText":"Get File Contents Read a file from the authenticated account's Git-backed repository, or an explicitly authorized target account's repository, including resolved submodule paths, on `main`. The repository comes from the [account's snapshot](/api-reference/sandboxes/list). Authenticate with `x-api-key` or an Authorization Bearer token. Agents & Sandboxes Sandboxes GET /api/sandboxes/file "},{"slug":"api-reference/sandboxes/stage-file","title":"Stage File","description":"Issue a presigned upload token so the browser can upload a file directly to Vercel Blob, then call `POST /api/sandboxes/files` with the resulting blob URL to commit it to the sandbox repo. Use `upload()` from `@vercel/blob/client` rather than calling this route by hand. Max file size 100MB.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/stage-file.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/staged-file","spec":"content.json"},"searchText":"Stage File Issue a presigned upload token so the browser can upload a file directly to Vercel Blob, then call `POST /api/sandboxes/files` with the resulting blob URL to commit it to the sandbox repo. Use `upload()` from `@vercel/blob/client` rather than calling this route by hand. Max file size 100MB. Agents & Sandboxes Sandboxes POST /api/sandboxes/staged-file "},{"slug":"api-reference/sandboxes/upload-files","title":"Upload Files","description":"Upload one or more files to the authenticated account's Git-backed repository. Each file URL is committed separately; paths inside a submodule resolve to that repository. Authenticate with `x-api-key` or an Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/upload-files.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/files","spec":"content.json"},"searchText":"Upload Files Upload one or more files to the authenticated account's Git-backed repository. Each file URL is committed separately; paths inside a submodule resolve to that repository. Authenticate with `x-api-key` or an Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes/files "},{"slug":"api-reference/sessions/create","title":"Create Session","description":"Create session","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions","spec":"sessions.json"},"searchText":"Create Session Create session Agents & Sandboxes Sessions POST /api/sessions "},{"slug":"api-reference/sessions/get","title":"Get Session","description":"Get session by id","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}","spec":"sessions.json"},"searchText":"Get Session Get session by id Agents & Sandboxes Sessions GET /api/sessions/{sessionId} "},{"slug":"api-reference/sessions/patch","title":"Update Session","description":"Rename a session, change lifecycle status, or update line counters.","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/patch.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sessions/{sessionId}","spec":"sessions.json"},"searchText":"Update Session Rename a session, change lifecycle status, or update line counters. Agents & Sandboxes Sessions PATCH /api/sessions/{sessionId} "},{"slug":"api-reference/sessions/list-chats","title":"List Session Chats","description":"List session chats","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/list-chats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}/chats","spec":"sessions.json"},"searchText":"List Session Chats List session chats Agents & Sandboxes Sessions GET /api/sessions/{sessionId}/chats "},{"slug":"api-reference/sessions/create-chat","title":"Create Session Chat","description":"Create session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/create-chat.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions/{sessionId}/chats","spec":"sessions.json"},"searchText":"Create Session Chat Create session chat Agents & Sandboxes Sessions POST /api/sessions/{sessionId}/chats "},{"slug":"api-reference/sessions/get-chat","title":"Get Session Chat","description":"Get session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/get-chat.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Get Session Chat Get session chat Agents & Sandboxes Sessions GET /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/patch-chat","title":"Update Session Chat","description":"Update session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/patch-chat.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Update Session Chat Update session chat Agents & Sandboxes Sessions PATCH /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/delete-chat","title":"Delete Session Chat","description":"Delete session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/delete-chat.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Delete Session Chat Delete session chat Agents & Sandboxes Sessions DELETE /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/mark-chat-read","title":"Mark Chat Read","description":"Marks a session chat as read for the authenticated account.","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/mark-chat-read.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions/{sessionId}/chats/{chatId}/read","spec":"sessions.json"},"searchText":"Mark Chat Read Marks a session chat as read for the authenticated account. Agents & Sandboxes Sessions POST /api/sessions/{sessionId}/chats/{chatId}/read "},{"slug":"api-reference/sandbox/create","title":"Create or restore session sandbox","description":"Create or restore session sandbox","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandbox","spec":"sandbox.json"},"searchText":"Create or restore session sandbox Create or restore session sandbox Agents & Sandboxes Session Sandboxes POST /api/sandbox "},{"slug":"api-reference/sandbox/status","title":"Get session sandbox status","description":"Get session sandbox status","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/status.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandbox/status","spec":"sandbox.json"},"searchText":"Get session sandbox status Get session sandbox status Agents & Sandboxes Session Sandboxes GET /api/sandbox/status "},{"slug":"api-reference/sandbox/reconnect","title":"Reconnect to session sandbox","description":"Reconnect to session sandbox","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/reconnect.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandbox/reconnect","spec":"sandbox.json"},"searchText":"Reconnect to session sandbox Reconnect to session sandbox Agents & Sandboxes Session Sandboxes GET /api/sandbox/reconnect "},{"slug":"api-reference/accounts/id","title":"Get Account ID","description":"Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/id.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/id","spec":"accounts.json"},"searchText":"Get Account ID Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId. Accounts Accounts GET /api/accounts/id "},{"slug":"api-reference/accounts/get","title":"Get Account","description":"Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}","spec":"accounts.json"},"searchText":"Get Account Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses. Accounts Accounts GET /api/accounts/{id} "},{"slug":"api-reference/accounts/create","title":"Create Account","description":"Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts","spec":"accounts.json"},"searchText":"Create Account Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits. Accounts Accounts POST /api/accounts "},{"slug":"api-reference/accounts/update","title":"Update Account","description":"Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/accounts","spec":"accounts.json"},"searchText":"Update Account Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override. Accounts Accounts PATCH /api/accounts "},{"slug":"api-reference/accounts/add-artist","title":"Add Artist to Account","description":"Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/add-artist.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/artists","spec":"accounts.json"},"searchText":"Add Artist to Account Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification. Accounts Accounts POST /api/accounts/artists "},{"slug":"api-reference/subscriptions/sessions-create","title":"Create Subscription Session","description":"Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial.","category":"Accounts","group":"Billing","source":"api-reference/subscriptions/sessions-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/subscriptions/sessions","spec":"accounts.json"},"searchText":"Create Subscription Session Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial. Accounts Billing POST /api/subscriptions/sessions "},{"slug":"api-reference/subscriptions/claim-create","title":"Claim Subscription","description":"Attach a subscription bought through [Create Subscription Session](/api-reference/subscriptions/sessions-create) (anonymous path) to the authenticated account. Needed only when the signed-in email differs from the email typed into Stripe Checkout; when they match, the webhook already linked the subscription and this call is a no-op that returns 200.","category":"Accounts","group":"Billing","source":"api-reference/subscriptions/claim-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/subscriptions/claim","spec":"accounts.json"},"searchText":"Claim Subscription Attach a subscription bought through [Create Subscription Session](/api-reference/subscriptions/sessions-create) (anonymous path) to the authenticated account. Needed only when the signed-in email differs from the email typed into Stripe Checkout; when they match, the webhook already linked the subscription and this call is a no-op that returns 200. Accounts Billing POST /api/subscriptions/claim "},{"slug":"api-reference/accounts/subscription-get","title":"Get Account Subscription","description":"Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/subscription-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/subscription","spec":"accounts.json"},"searchText":"Get Account Subscription Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/subscription "},{"slug":"api-reference/accounts/portal-create","title":"Create Billing Portal Session","description":"Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. The portal opens on the Stripe customer that owns the account's active subscription, so accounts without an active subscription get a 400 even when a tagged customer with a card exists. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with an active subscription.","category":"Accounts","group":"Billing","source":"api-reference/accounts/portal-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/{id}/portal","spec":"accounts.json"},"searchText":"Create Billing Portal Session Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. The portal opens on the Stripe customer that owns the account's active subscription, so accounts without an active subscription get a 400 even when a tagged customer with a card exists. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with an active subscription. Accounts Billing POST /api/accounts/{id}/portal "},{"slug":"api-reference/accounts/payment-method-get","title":"Get Default Payment Method","description":"Retrieve the default payment method on file for an account. An account may be tagged on more than one Stripe customer (for example an organization whose card was saved on one customer and whose invoiced plan lives on another); the card is read from the tagged customer that holds a default payment method. Returns `card: null` when the selected customer has no supported default card, including when no tagged customer exists — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline. Removing the selected card does not remove other saved cards: a later read can select a different remaining card. Auto top-up stays off after successful removal until explicitly re-enabled.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Get Default Payment Method Retrieve the default payment method on file for an account. An account may be tagged on more than one Stripe customer (for example an organization whose card was saved on one customer and whose invoiced plan lives on another); the card is read from the tagged customer that holds a default payment method. Returns `card: null` when the selected customer has no supported default card, including when no tagged customer exists — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline. Removing the selected card does not remove other saved cards: a later read can select a different remaining card. Auto top-up stays off after successful removal until explicitly re-enabled. Accounts Billing GET /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payment-method-create","title":"Save a Payment Method","description":"Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The card is saved on the account's Stripe customer that already holds a default card, or the newest tagged customer; a customer is created (and tagged with the account id) if none exists yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Save a Payment Method Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The card is saved on the account's Stripe customer that already holds a default card, or the newest tagged customer; a customer is created (and tagged with the account id) if none exists yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing POST /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payment-method-delete","title":"Remove the Payment Method","description":"Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Remove the Payment Method Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing DELETE /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payments-get","title":"List Account Payments","description":"List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payments-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/payments","spec":"accounts.json"},"searchText":"List Account Payments List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/payments "},{"slug":"api-reference/accounts/auto-top-up-get","title":"Get Auto Top-up Settings","description":"Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/auto-top-up-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/auto-top-up","spec":"accounts.json"},"searchText":"Get Auto Top-up Settings Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/auto-top-up "},{"slug":"api-reference/accounts/auto-top-up-update","title":"Update Auto Top-up Settings","description":"Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/auto-top-up-update.mdx","body":"","headings":[],"api":{"method":"PUT","path":"/api/accounts/{id}/auto-top-up","spec":"accounts.json"},"searchText":"Update Auto Top-up Settings Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing PUT /api/accounts/{id}/auto-top-up "},{"slug":"api-reference/credits/sessions-create","title":"Create Credits Top-Up Session","description":"Top up credits on the authenticated account.","category":"Accounts","group":"Billing","source":"api-reference/credits/sessions-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/credits/sessions","spec":"accounts.json"},"searchText":"Create Credits Top-Up Session Top up credits on the authenticated account. Accounts Billing POST /api/credits/sessions "},{"slug":"api-reference/accounts/credits-get","title":"Get Account Credits","description":"Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update.","category":"Accounts","group":"Billing","source":"api-reference/accounts/credits-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/credits","spec":"accounts.json"},"searchText":"Get Account Credits Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update. Accounts Billing GET /api/accounts/{id}/credits "},{"slug":"api-reference/accounts/usage-get","title":"Get Account Usage","description":"List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership.","category":"Accounts","group":"Billing","source":"api-reference/accounts/usage-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/usage","spec":"accounts.json"},"searchText":"Get Account Usage List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership. Accounts Billing GET /api/accounts/{id}/usage "},{"slug":"api-reference/pulses/update","title":"Update Pulse","description":"Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint.","category":"Accounts","group":"Pulses","source":"api-reference/pulses/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/pulses","spec":"accounts.json"},"searchText":"Update Pulse Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint. Accounts Pulses PATCH /api/pulses "},{"slug":"api-reference/pulses/list","title":"List Pulses","description":"Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations.","category":"Accounts","group":"Pulses","source":"api-reference/pulses/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/pulses","spec":"accounts.json"},"searchText":"List Pulses Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations. Accounts Pulses GET /api/pulses "},{"slug":"api-reference/organizations/list","title":"Get Organizations","description":"Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations","spec":"accounts.json"},"searchText":"Get Organizations Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to. Accounts Organizations GET /api/organizations "},{"slug":"api-reference/organizations/create","title":"Create Organization","description":"Create a new organization. The creator is automatically added as a member of the organization.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations","spec":"accounts.json"},"searchText":"Create Organization Create a new organization. The creator is automatically added as a member of the organization. Accounts Organizations POST /api/organizations "},{"slug":"api-reference/organizations/add-artist","title":"Add Artist to Organization","description":"Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-artist.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/artists","spec":"accounts.json"},"searchText":"Add Artist to Organization Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records. Accounts Organizations POST /api/organizations/artists "},{"slug":"api-reference/organizations/add-member","title":"Add Member to Organization","description":"Add a member to an organization. This endpoint is idempotent - Adding an existing member returns the existing membership.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-member.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/members","spec":"accounts.json"},"searchText":"Add Member to Organization Add a member to an organization. This endpoint is idempotent - Adding an existing member returns the existing membership. Accounts Organizations POST /api/organizations/members "},{"slug":"api-reference/organizations/remove-member","title":"Remove Member from Organization","description":"Remove a member from an organization. This endpoint is idempotent - Removing an account that is not a member succeeds without error.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/remove-member.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/organizations/members","spec":"accounts.json"},"searchText":"Remove Member from Organization Remove a member from an organization. This endpoint is idempotent - Removing an account that is not a member succeeds without error. Accounts Organizations DELETE /api/organizations/members "},{"slug":"api-reference/organizations/list-domains","title":"List Organization Domains","description":"List the email domains mapped to an organization. Accounts that sign up with an email at a mapped domain automatically join the organization.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/list-domains.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"List Organization Domains List the email domains mapped to an organization. Accounts that sign up with an email at a mapped domain automatically join the organization. Accounts Organizations GET /api/organizations/domains "},{"slug":"api-reference/organizations/add-domain","title":"Add Organization Domain","description":"Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-domain.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"Add Organization Domain Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping. Accounts Organizations POST /api/organizations/domains "},{"slug":"api-reference/organizations/remove-domain","title":"Remove Organization Domain","description":"Remove an email domain mapping from an organization. New signups at this domain will no longer auto-join the organization; existing members are not affected. This endpoint is idempotent.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/remove-domain.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"Remove Organization Domain Remove an email domain mapping from an organization. New signups at this domain will no longer auto-join the organization; existing members are not affected. This endpoint is idempotent. Accounts Organizations DELETE /api/organizations/domains "},{"slug":"api-reference/organizations/professionals","title":"List Professional Roster","description":"List professional roster","category":"Accounts","group":"Organizations","source":"api-reference/organizations/professionals.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations/professionals","spec":"accounts.json"},"searchText":"List Professional Roster List professional roster Accounts Organizations GET /api/organizations/professionals "},{"slug":"api-reference/organizations/professionals-confirm","title":"Confirm Professional Roster Addition","description":"Confirm professional roster addition","category":"Accounts","group":"Organizations","source":"api-reference/organizations/professionals-confirm.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/professionals","spec":"accounts.json"},"searchText":"Confirm Professional Roster Addition Confirm professional roster addition Accounts Organizations POST /api/organizations/professionals "},{"slug":"api-reference/admins/check","title":"Check Admin Status","description":"Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header.","category":"Accounts","group":"Admins","source":"api-reference/admins/check.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins","spec":"accounts.json"},"searchText":"Check Admin Status Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header. Accounts Admins GET /api/admins "},{"slug":"api-reference/admins/sandboxes","title":"List Account Sandboxes (Admin)","description":"Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/sandboxes.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/sandboxes","spec":"accounts.json"},"searchText":"List Account Sandboxes (Admin) Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/sandboxes "},{"slug":"api-reference/admins/sandboxes-orgs","title":"List Org Repo Stats (Admin)","description":"Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/sandboxes-orgs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/sandboxes/orgs","spec":"accounts.json"},"searchText":"List Org Repo Stats (Admin) Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/sandboxes/orgs "},{"slug":"api-reference/admins/emails","title":"List Account Emails (Admin)","description":"Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email).","category":"Accounts","group":"Admins","source":"api-reference/admins/emails.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/emails","spec":"accounts.json"},"searchText":"List Account Emails (Admin) Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email). Accounts Admins GET /api/admins/emails "},{"slug":"api-reference/admins/privy","title":"List Privy Logins (Admin)","description":"Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/privy.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/privy","spec":"accounts.json"},"searchText":"List Privy Logins (Admin) Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/privy "},{"slug":"api-reference/admins/coding-agent-slack-tags","title":"List Coding Agent Slack Tags (Admin)","description":"Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Optional tag filters by the exact, case-sensitive Slack author ID after trimming whitespace. Filtering happens after the existing period collection and before all totals are calculated; omission preserves the unfiltered report, and an unknown ID returns empty tags with zero totals. Empty or whitespace-only tag values return 400 after admin authentication. This is display filtering, not authorization or a reduction in Slack collection work. Collection retains its existing channel access, retention, history/thread pagination and partial-failure limits. No automatic caller, UI, polling, scheduled action or Slack send is added.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-agent-slack-tags.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding/slack","spec":"accounts.json"},"searchText":"List Coding Agent Slack Tags (Admin) Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Optional tag filters by the exact, case-sensitive Slack author ID after trimming whitespace. Filtering happens after the existing period collection and before all totals are calculated; omission preserves the unfiltered report, and an unknown ID returns empty tags with zero totals. Empty or whitespace-only tag values return 400 after admin authentication. This is display filtering, not authorization or a reduction in Slack collection work. Collection retains its existing channel access, retention, history/thread pagination and partial-failure limits. No automatic caller, UI, polling, scheduled action or Slack send is added. Accounts Admins GET /api/admins/coding/slack "},{"slug":"api-reference/admins/coding-agent-slack-authors","title":"List Coding Agent Slack Authors (Admin)","description":"Returns distinct authors of collected Coding Agent mentions for an admin author selector. Requires the authenticated account to be a Recoup admin, using exactly one of x-api-key or Authorization Bearer. No query parameters are defined. Each authorized request runs the existing all-period Slack collector once, then deduplicates by Slack author ID, retains the first collected profile and sorts by display name using localeCompare; identical names do not merge different IDs. The result is authors in that collected data, not a complete all-time Slack directory. Existing channel access, retention, paginated history, first-page thread replies and partial-failure limits remain; partial collection can still produce an incomplete successful result. Thrown collection failures return 500. This call is not free cached metadata: a future caller must account for scan latency and quotas. The release adds no automatic caller, UI, polling, scheduled action, new Slack scope or Slack send. Production admin access, history coverage, latency and quotas were not verified by the source contract tests.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-agent-slack-authors.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding-agent/slack-tags","spec":"accounts.json"},"searchText":"List Coding Agent Slack Authors (Admin) Returns distinct authors of collected Coding Agent mentions for an admin author selector. Requires the authenticated account to be a Recoup admin, using exactly one of x-api-key or Authorization Bearer. No query parameters are defined. Each authorized request runs the existing all-period Slack collector once, then deduplicates by Slack author ID, retains the first collected profile and sorts by display name using localeCompare; identical names do not merge different IDs. The result is authors in that collected data, not a complete all-time Slack directory. Existing channel access, retention, paginated history, first-page thread replies and partial-failure limits remain; partial collection can still produce an incomplete successful result. Thrown collection failures return 500. This call is not free cached metadata: a future caller must account for scan latency and quotas. The release adds no automatic caller, UI, polling, scheduled action, new Slack scope or Slack send. Production admin access, history coverage, latency and quotas were not verified by the source contract tests. Accounts Admins GET /api/admins/coding-agent/slack-tags "},{"slug":"api-reference/admins/coding-pr","title":"Get Coding Agent PR Merged Status (Admin)","description":"Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-pr.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding/pr","spec":"accounts.json"},"searchText":"Get Coding Agent PR Merged Status (Admin) Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/coding/pr "},{"slug":"api-reference/admins/content-slack-tags","title":"List Content Agent Slack Tags (Admin)","description":"Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/content-slack-tags.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/content/slack","spec":"accounts.json"},"searchText":"List Content Agent Slack Tags (Admin) Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/content/slack "},{"slug":"api-reference/admins/agent-signups","title":"Admin signup report availability","description":"An admin key-metadata report is available; the former signup-report URL and broader reporting outcome remain separate.","category":"Accounts","group":"Admins","source":"api-reference/admins/agent-signups.mdx","body":"`GET /api/admins/agent/signups` is not available. The new\n[admin key-metadata report](/api-reference/admins/agent-key-metadata) uses\n`GET /api/admins/agent-signups` (a different URL).\n\nA Recoup admin can use the new report to inspect key-record IDs, names, creation\ntimes and matching current `agent+…` email addresses. It never returns API-key\ncredentials or hashes. Its `total` counts the returned key records; several keys\ncan belong to one account. It does not establish where an account signed up,\nhow many unique agents signed up, which keys are active, or whether people use\nthe product. Current email associations, database visibility and server row limits\nalso prevent a guarantee of complete historical reporting.\n\n## Unfinished reporting outcome\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the\nbroader reporting decision. The bounded metadata route from\n[API #1095](https://github.com/recoupable/api/pull/1095) does not complete the original\n[API #428](https://github.com/recoupable/api/issues/428) customer outcome or restore\nthe former URL. Follow the new route's period, admin-access and collection-limit\nnotes when using it; do not treat key-record counts as signup-origin or adoption\nmeasurements.\n","headings":[{"title":"Unfinished reporting outcome","id":"unfinished-reporting-outcome"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/admins/agent/signups\"\n }), \" is not available. The new\\n\", _jsx(_components.a, {\n href: \"/api-reference/admins/agent-key-metadata\",\n children: \"admin key-metadata report\"\n }), \" uses\\n\", _jsx(_components.code, {\n children: \"GET /api/admins/agent-signups\"\n }), \" (a different URL).\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A Recoup admin can use the new report to inspect key-record IDs, names, creation\\ntimes and matching current \", _jsx(_components.code, {\n children: \"agent+…\"\n }), \" email addresses. It never returns API-key\\ncredentials or hashes. Its \", _jsx(_components.code, {\n children: \"total\"\n }), \" counts the returned key records; several keys\\ncan belong to one account. It does not establish where an account signed up,\\nhow many unique agents signed up, which keys are active, or whether people use\\nthe product. Current email associations, database visibility and server row limits\\nalso prevent a guarantee of complete historical reporting.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"unfinished-reporting-outcome\",\n children: \"Unfinished reporting outcome\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" retains the\\nbroader reporting decision. The bounded metadata route from\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/1095\",\n children: \"API #1095\"\n }), \" does not complete the original\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/issues/428\",\n children: \"API #428\"\n }), \" customer outcome or restore\\nthe former URL. Follow the new route's period, admin-access and collection-limit\\nnotes when using it; do not treat key-record counts as signup-origin or adoption\\nmeasurements.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Admin signup report availability An admin key-metadata report is available; the former signup-report URL and broader reporting outcome remain separate. Accounts Admins `GET /api/admins/agent/signups` is not available. The new [admin key-metadata report](/api-reference/admins/agent-key-metadata) uses `GET /api/admins/agent-signups` (a different URL). A Recoup admin can use the new report to inspect key-record IDs, names, creation times and matching current `agent+…` email addresses. It never returns API-key credentials or hashes. Its `total` counts the returned key records; several keys can belong to one account. It does not establish where an account signed up, how many unique agents signed up, which keys are active, or whether people use the product. Current email associations, database visibility and server row limits also prevent a guarantee of complete historical reporting. ## Unfinished reporting outcome [Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the broader reporting decision. The bounded metadata route from [API #1095](https://github.com/recoupable/api/pull/1095) does not complete the original [API #428](https://github.com/recoupable/api/issues/428) customer outcome or restore the former URL. Follow the new route's period, admin-access and collection-limit notes when using it; do not treat key-record counts as signup-origin or adoption measurements. "},{"slug":"api-reference/admins/agent-key-metadata","title":"List Agent Key Metadata (Admin)","description":"List agent-prefixed API-key metadata (Admin)","category":"Accounts","group":"Admins","source":"api-reference/admins/agent-key-metadata.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/agent-signups","spec":"accounts.json"},"searchText":"List Agent Key Metadata (Admin) List agent-prefixed API-key metadata (Admin) Accounts Admins GET /api/admins/agent-signups "},{"slug":"api-reference/admins/artists-pro","title":"List Pro Artists (Admin)","description":"Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is \"pro\" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts.","category":"Accounts","group":"Admins","source":"api-reference/admins/artists-pro.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/artists/pro","spec":"accounts.json"},"searchText":"List Pro Artists (Admin) Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is \"pro\" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts. Accounts Admins GET /api/admins/artists/pro "},{"slug":"api-reference/admins/credits-rollup","title":"Credit Usage Rollup (Admin)","description":"Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-rollup.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/credits/rollup","spec":"accounts.json"},"searchText":"Credit Usage Rollup (Admin) Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin. Accounts Admins GET /api/admins/credits/rollup "},{"slug":"api-reference/admins/credits-events","title":"Credit Usage Events (Admin)","description":"Returns the raw `usage_events` rows for a single account over the selected period, sorted by `created_at` descending. Powers the drilldown view that expands when a row in the [`/api/admins/credits/rollup`](/api-reference/admins/credits-rollup) table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and `credits_deducted` matching the wallet drop on `credits_usage` for that account.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-events.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/credits/events","spec":"accounts.json"},"searchText":"Credit Usage Events (Admin) Returns the raw `usage_events` rows for a single account over the selected period, sorted by `created_at` descending. Powers the drilldown view that expands when a row in the [`/api/admins/credits/rollup`](/api-reference/admins/credits-rollup) table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and `credits_deducted` matching the wallet drop on `credits_usage` for that account. Accounts Admins GET /api/admins/credits/events "},{"slug":"api-reference/admins/credits-grant","title":"Grant Credits (Admin)","description":"Sets an account's credit balance, and records who set it and why. Requires the authenticated account to be a Recoup admin.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-grant.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/admins/credits","spec":"accounts.json"},"searchText":"Grant Credits (Admin) Sets an account's credit balance, and records who set it and why. Requires the authenticated account to be a Recoup admin. Accounts Admins POST /api/admins/credits "},{"slug":"api-reference/emails/create","title":"Send Email","description":"Send an email to one or more recipients. Emails are sent from `Agent by Recoup `.","category":"Accounts","group":"Emails","source":"api-reference/emails/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/emails","spec":"accounts.json"},"searchText":"Send Email Send an email to one or more recipients. Emails are sent from `Agent by Recoup `. Accounts Emails POST /api/emails "},{"slug":"api-reference/projects/get","title":"Get Project","description":"Get project","category":"Accounts","group":"Projects","source":"api-reference/projects/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}","spec":"projects.json"},"searchText":"Get Project Get project Accounts Projects GET /api/projects/{projectId} "},{"slug":"api-reference/projects/task-get","title":"Get Project Task","description":"Get project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Get Project Task Get project task Accounts Projects GET /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/task-create","title":"Create Project Task","description":"Create project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/projects/{projectId}/tasks","spec":"projects.json"},"searchText":"Create Project Task Create project task Accounts Projects POST /api/projects/{projectId}/tasks "},{"slug":"api-reference/projects/task-update","title":"Update Project Task","description":"Update project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Update Project Task Update project task Accounts Projects PATCH /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/task-delete","title":"Delete Project Task","description":"Delete project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Delete Project Task Delete project task Accounts Projects DELETE /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/comments-get","title":"List Task Comments","description":"List task comments","category":"Accounts","group":"Projects","source":"api-reference/projects/comments-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}/tasks/{taskId}/comments","spec":"projects.json"},"searchText":"List Task Comments List task comments Accounts Projects GET /api/projects/{projectId}/tasks/{taskId}/comments "},{"slug":"api-reference/projects/comments-create","title":"Add Task Comment","description":"Add task comment","category":"Accounts","group":"Projects","source":"api-reference/projects/comments-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/projects/{projectId}/tasks/{taskId}/comments","spec":"projects.json"},"searchText":"Add Task Comment Add task comment Accounts Projects POST /api/projects/{projectId}/tasks/{taskId}/comments "},{"slug":"connectors/ownership","title":"Connection Ownership","description":"The connector connection-ownership and authority contract: who owns a connection, who can act through it, and why roster membership never grants execute rights.","category":"Connectors","group":"Concepts","source":"connectors/ownership.mdx","body":"## Overview\n\nConnectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the **ownership and authority contract** for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it.\n\nThis contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the [Connectors API reference](/api-reference/connectors/list).\n\n---\n\n## Association ≠ Authority\n\nArtists in Recoup are **canonical and shared**. The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections:\n\n- An artist appearing in an account's roster (`account_artist_ids`) grants **read and analytics access only**.\n- An artist appearing in an organization's roster likewise grants **read and analytics access only** to org members.\n- Neither form of association ever grants the right to authorize, execute, or disconnect a connection.\n\n\nRoster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does **not** let Account B post through that connection.\n\n\n---\n\n## Connection Scope\n\nConnections are scoped to the **relationship between an owner and an artist**, not to the bare canonical artist:\n\n| Connection type | Scoped to |\n|-----------------|-----------|\n| Personal | The `(account, artist)` pair |\n| Org-shared | The `(organization, artist)` pair |\n\nThe connection is keyed on the **join row** (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist.\n\n**Whoever establishes a connection owns it.** Ownership is set at authorization time and does not transfer through roster changes.\n\nBecause artists stay canonical and shared, **isolation lives on the connection**: sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it.\n\n---\n\n## Authority Matrix\n\n| Capability | Who has it |\n|------------|-----------|\n| Read / analytics on an artist | Any account or org member with the artist in their roster |\n| Authorize a new connection | The account (or org member, for org-shared) establishing the connection, who then owns it |\n| Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org |\n| Disconnect a connection | The owning account only; for org-shared connections, members of the owning org |\n| Admin override | Recoup staff only (admins of the Recoup internal organization) |\n\n\nThe admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection.\n\n\n---\n\n## Relationship to the Current API Reference\n\nThe [Connectors endpoint reference](/api-reference/connectors/list) currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-`(account, artist)` / per-`(organization, artist)` model defined here. Where the two disagree, **this page is the authority contract**. Endpoint docs will be updated as the re-keyed API ships.\n\nEndpoint request and response shapes for the re-keyed model are deliberately not documented here yet.\n","headings":[{"title":"Overview","id":"overview"},{"title":"Association ≠ Authority","id":"association-authority"},{"title":"Connection Scope","id":"connection-scope"},{"title":"Authority Matrix","id":"authority-matrix"},{"title":"Relationship to the Current API Reference","id":"relationship-to-the-current-api-reference"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n hr: \"hr\",\n li: \"li\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n }, {Note, Warning} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"overview\",\n children: \"Overview\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the \", _jsx(_components.strong, {\n children: \"ownership and authority contract\"\n }), \" for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors API reference\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"association-authority\",\n children: \"Association ≠ Authority\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Artists in Recoup are \", _jsx(_components.strong, {\n children: \"canonical and shared\"\n }), \". The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"An artist appearing in an account's roster (\", _jsx(_components.code, {\n children: \"account_artist_ids\"\n }), \") grants \", _jsx(_components.strong, {\n children: \"read and analytics access only\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"An artist appearing in an organization's roster likewise grants \", _jsx(_components.strong, {\n children: \"read and analytics access only\"\n }), \" to org members.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Neither form of association ever grants the right to authorize, execute, or disconnect a connection.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsxs(_components.p, {\n children: [\"Roster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does \", _jsx(_components.strong, {\n children: \"not\"\n }), \" let Account B post through that connection.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"connection-scope\",\n children: \"Connection Scope\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connections are scoped to the \", _jsx(_components.strong, {\n children: \"relationship between an owner and an artist\"\n }), \", not to the bare canonical artist:\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Connection type\"\n }), _jsx(_components.th, {\n children: \"Scoped to\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Personal\"\n }), _jsxs(_components.td, {\n children: [\"The \", _jsx(_components.code, {\n children: \"(account, artist)\"\n }), \" pair\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Org-shared\"\n }), _jsxs(_components.td, {\n children: [\"The \", _jsx(_components.code, {\n children: \"(organization, artist)\"\n }), \" pair\"]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The connection is keyed on the \", _jsx(_components.strong, {\n children: \"join row\"\n }), \" (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Whoever establishes a connection owns it.\"\n }), \" Ownership is set at authorization time and does not transfer through roster changes.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Because artists stay canonical and shared, \", _jsx(_components.strong, {\n children: \"isolation lives on the connection\"\n }), \": sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"authority-matrix\",\n children: \"Authority Matrix\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Capability\"\n }), _jsx(_components.th, {\n children: \"Who has it\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Read / analytics on an artist\"\n }), _jsx(_components.td, {\n children: \"Any account or org member with the artist in their roster\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Authorize a new connection\"\n }), _jsx(_components.td, {\n children: \"The account (or org member, for org-shared) establishing the connection, who then owns it\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Execute actions through a connection\"\n }), _jsx(_components.td, {\n children: \"The owning account only; for org-shared connections, members of the owning org\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Disconnect a connection\"\n }), _jsx(_components.td, {\n children: \"The owning account only; for org-shared connections, members of the owning org\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Admin override\"\n }), _jsx(_components.td, {\n children: \"Recoup staff only (admins of the Recoup internal organization)\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"The admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection.\"\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"relationship-to-the-current-api-reference\",\n children: \"Relationship to the Current API Reference\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors endpoint reference\"\n }), \" currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-\", _jsx(_components.code, {\n children: \"(account, artist)\"\n }), \" / per-\", _jsx(_components.code, {\n children: \"(organization, artist)\"\n }), \" model defined here. Where the two disagree, \", _jsx(_components.strong, {\n children: \"this page is the authority contract\"\n }), \". Endpoint docs will be updated as the re-keyed API ships.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Endpoint request and response shapes for the re-keyed model are deliberately not documented here yet.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Connection Ownership The connector connection-ownership and authority contract: who owns a connection, who can act through it, and why roster membership never grants execute rights. Connectors Concepts ## Overview Connectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the **ownership and authority contract** for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it. This contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the [Connectors API reference](/api-reference/connectors/list). --- ## Association ≠ Authority Artists in Recoup are **canonical and shared**. The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections: - An artist appearing in an account's roster (`account_artist_ids`) grants **read and analytics access only**. - An artist appearing in an organization's roster likewise grants **read and analytics access only** to org members. - Neither form of association ever grants the right to authorize, execute, or disconnect a connection. Roster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does **not** let Account B post through that connection. --- ## Connection Scope Connections are scoped to the **relationship between an owner and an artist**, not to the bare canonical artist: | Connection type | Scoped to | |-----------------|-----------| | Personal | The `(account, artist)` pair | | Org-shared | The `(organization, artist)` pair | The connection is keyed on the **join row** (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist. **Whoever establishes a connection owns it.** Ownership is set at authorization time and does not transfer through roster changes. Because artists stay canonical and shared, **isolation lives on the connection**: sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it. --- ## Authority Matrix | Capability | Who has it | |------------|-----------| | Read / analytics on an artist | Any account or org member with the artist in their roster | | Authorize a new connection | The account (or org member, for org-shared) establishing the connection, who then owns it | | Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org | | Disconnect a connection | The owning account only; for org-shared connections, members of the owning org | | Admin override | Recoup staff only (admins of the Recoup internal organization) | The admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection. --- ## Relationship to the Current API Reference The [Connectors endpoint reference](/api-reference/connectors/list) currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-`(account, artist)` / per-`(organization, artist)` model defined here. Where the two disagree, **this page is the authority contract**. Endpoint docs will be updated as the re-keyed API ships. Endpoint request and response shapes for the re-keyed model are deliberately not documented here yet. "},{"slug":"api-reference/connectors/list","title":"List Connectors","description":"List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok, YouTube, X (Twitter), LinkedIn) along with whether they are currently connected.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/connectors","spec":"social.json"},"searchText":"List Connectors List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok, YouTube, X (Twitter), LinkedIn) along with whether they are currently connected. Connectors Connectors GET /api/connectors "},{"slug":"api-reference/connectors/authorize","title":"Authorize Connector","description":"Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/authorize.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors","spec":"social.json"},"searchText":"Authorize Connector Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow. Connectors Connectors POST /api/connectors "},{"slug":"api-reference/connectors/disconnect","title":"Disconnect Connector","description":"Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/disconnect.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/connectors","spec":"social.json"},"searchText":"Disconnect Connector Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials. Connectors Connectors DELETE /api/connectors "},{"slug":"api-reference/connectors/list-actions","title":"List Connector Actions","description":"List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/list-actions.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/connectors/actions","spec":"social.json"},"searchText":"List Connector Actions List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors. Connectors Connectors GET /api/connectors/actions "},{"slug":"api-reference/connectors/upload-file","title":"Upload Connector File","description":"Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action).","category":"Connectors","group":"Connectors","source":"api-reference/connectors/upload-file.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors/files","spec":"social.json"},"searchText":"Upload Connector File Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action). Connectors Connectors POST /api/connectors/files "},{"slug":"api-reference/connectors/execute-action","title":"Execute Connector Action","description":"Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/execute-action.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors/actions","spec":"social.json"},"searchText":"Execute Connector Action Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor. Connectors Connectors POST /api/connectors/actions "},{"slug":"api-reference/publishing/create","title":"Create Post","description":"Create post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/posts","spec":"social.json"},"searchText":"Create Post Create post Connectors Publishing POST /api/posts "},{"slug":"api-reference/publishing/list","title":"List Posts","description":"List posts","category":"Connectors","group":"Publishing","source":"api-reference/publishing/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/posts","spec":"social.json"},"searchText":"List Posts List posts Connectors Publishing GET /api/posts "},{"slug":"api-reference/publishing/get","title":"Get Post","description":"Get post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/posts/{id}","spec":"social.json"},"searchText":"Get Post Get post Connectors Publishing GET /api/posts/{id} "},{"slug":"api-reference/publishing/stats","title":"Get Post Stats","description":"Get post stats","category":"Connectors","group":"Publishing","source":"api-reference/publishing/stats.mdx","body":"## Data coverage\n\nLinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds.\n","headings":[{"title":"Data coverage","id":"data-coverage"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"data-coverage\",\n children: \"Data coverage\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"LinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","api":{"method":"GET","path":"/api/posts/{id}/stats","spec":"social.json"},"searchText":"Get Post Stats Get post stats Connectors Publishing GET /api/posts/{id}/stats ## Data coverage LinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds. "},{"slug":"api-reference/publishing/cancel","title":"Cancel Post","description":"Cancel post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/cancel.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/posts/{id}","spec":"social.json"},"searchText":"Cancel Post Cancel post Connectors Publishing DELETE /api/posts/{id} "},{"slug":"api-reference/applications/validate-registration","title":"Check an application proposal","description":"Validate proposed app addresses in your workspace without registering or activating an application.","category":"Sites","group":"Application proposals","source":"api-reference/applications/validate-registration.mdx","body":"\n Pending coordinated release. This checks a proposal; it does not register an\n app or make its origins trusted. Discover tool availability in your connected\n host before use.\n\n\nBefore connecting an external app, check its proposed name, environment, origins\nand return URLs. A successful result means those values passed validation for\nthe selected workspace. It does not prove domain ownership.\n\n## What happens\n\nThe preflight runs after normal Recoup authentication. First-time sign-in can\nperform normal account provisioning and send its welcome email. After that,\nthis validator does not persist an application or issue application credentials.\nIt does not edit provider callbacks, create fan identities or sessions, allocate\ncapacity, or authorize purchases and spending.\n\n`workspace_id` and `billing_owner_id` come from the authenticated account or an\norganization it can access. They describe the proposed owner only. Supplying\n`organization_id` does not grant workspace access. Do not submit account or\nbilling ownership overrides, secrets or tokens in the proposal.\n\nThe result is flat and includes `status: \"validated\"`, `persisted: false` and\n`origins_verified: false`. It contains no application ID or token to install.\n\n## Addresses and environments\n\n- Choose `development` or `production` explicitly for each proposal.\n- Use exact canonical origins such as `https://music.example`, without a trailing\n slash, wildcard, path, credentials, query or fragment. Different hosts and\n ports are different origins.\n- HTTPS is required. Development also accepts HTTP on `localhost`, `127.0.0.1`\n and `[::1]`; these loopback hosts are rejected in production.\n- A return URL must be an exact canonical URL on one of the proposed origins,\n without credentials or fragments. For a bare host use its canonical trailing\n slash, such as `https://music.example/`. Query strings are retained literally.\n- Each list takes 1–32 distinct addresses, each at most 2048 characters. The name\n is trimmed and must then contain 1–120 characters. These are input limits,\n not subscription or usage allowances.\n\nMatching a return URL to a caller-proposed origin does not establish that the\ncaller owns either address. No DNS check, URL fetch or domain proof is performed.\n\n## Standard MCP\n\nOn a standard API-key MCP connection that exposes `validate_application_registration`,\nuse the same proposal fields as HTTP. Account identity comes from the connection;\ndo not add `account_id` or extract a host-managed OAuth token.\n\n```json\n{\n \"name\": \"Release companion\",\n \"environment\": \"production\",\n \"allowed_origins\": [\"https://music.example\"],\n \"return_urls\": [\"https://music.example/listen?connected=spotify\"]\n}\n```\n\nDelegated OAuth excludes this tool, including connections with `mcp:tools`.\nHTTP and standard MCP share proposal validation; their transport-specific error\nenvelopes differ. HTTP authentication errors can use `error` or `message`, while\nhandled preflight errors use `status: \"error\"` and `error`. MCP failures are tool\nerrors or SDK input-validation errors. None confirms registration or activation.\n\nSee [authentication](/authentication) and [MCP connection guidance](/mcp).\nApplication persistence, origin proof/reverification, provider configuration,\nfan bootstrap, suspension and quota policy require their own completed contracts.\n","headings":[{"title":"What happens","id":"what-happens"},{"title":"Addresses and environments","id":"addresses-and-environments"},{"title":"Standard MCP","id":"standard-mcp"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n ul: \"ul\",\n ...props.components\n }, {Warning} = _components;\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Pending coordinated release. This checks a proposal; it does not register an\\napp or make its origins trusted. Discover tool availability in your connected\\nhost before use.\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before connecting an external app, check its proposed name, environment, origins\\nand return URLs. A successful result means those values passed validation for\\nthe selected workspace. It does not prove domain ownership.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-happens\",\n children: \"What happens\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The preflight runs after normal Recoup authentication. First-time sign-in can\\nperform normal account provisioning and send its welcome email. After that,\\nthis validator does not persist an application or issue application credentials.\\nIt does not edit provider callbacks, create fan identities or sessions, allocate\\ncapacity, or authorize purchases and spending.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"workspace_id\"\n }), \" and \", _jsx(_components.code, {\n children: \"billing_owner_id\"\n }), \" come from the authenticated account or an\\norganization it can access. They describe the proposed owner only. Supplying\\n\", _jsx(_components.code, {\n children: \"organization_id\"\n }), \" does not grant workspace access. Do not submit account or\\nbilling ownership overrides, secrets or tokens in the proposal.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The result is flat and includes \", _jsx(_components.code, {\n children: \"status: \\\"validated\\\"\"\n }), \", \", _jsx(_components.code, {\n children: \"persisted: false\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"origins_verified: false\"\n }), \". It contains no application ID or token to install.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"addresses-and-environments\",\n children: \"Addresses and environments\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Choose \", _jsx(_components.code, {\n children: \"development\"\n }), \" or \", _jsx(_components.code, {\n children: \"production\"\n }), \" explicitly for each proposal.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use exact canonical origins such as \", _jsx(_components.code, {\n children: \"https://music.example\"\n }), \", without a trailing\\nslash, wildcard, path, credentials, query or fragment. Different hosts and\\nports are different origins.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"HTTPS is required. Development also accepts HTTP on \", _jsx(_components.code, {\n children: \"localhost\"\n }), \", \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \"\\nand \", _jsx(_components.code, {\n children: \"[::1]\"\n }), \"; these loopback hosts are rejected in production.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"A return URL must be an exact canonical URL on one of the proposed origins,\\nwithout credentials or fragments. For a bare host use its canonical trailing\\nslash, such as \", _jsx(_components.code, {\n children: \"https://music.example/\"\n }), \". Query strings are retained literally.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Each list takes 1–32 distinct addresses, each at most 2048 characters. The name\\nis trimmed and must then contain 1–120 characters. These are input limits,\\nnot subscription or usage allowances.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Matching a return URL to a caller-proposed origin does not establish that the\\ncaller owns either address. No DNS check, URL fetch or domain proof is performed.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"standard-mcp\",\n children: \"Standard MCP\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"On a standard API-key MCP connection that exposes \", _jsx(_components.code, {\n children: \"validate_application_registration\"\n }), \",\\nuse the same proposal fields as HTTP. Account identity comes from the connection;\\ndo not add \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" or extract a host-managed OAuth token.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"name\\\": \\\"Release companion\\\",\\n \\\"environment\\\": \\\"production\\\",\\n \\\"allowed_origins\\\": [\\\"https://music.example\\\"],\\n \\\"return_urls\\\": [\\\"https://music.example/listen?connected=spotify\\\"]\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Delegated OAuth excludes this tool, including connections with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \".\\nHTTP and standard MCP share proposal validation; their transport-specific error\\nenvelopes differ. HTTP authentication errors can use \", _jsx(_components.code, {\n children: \"error\"\n }), \" or \", _jsx(_components.code, {\n children: \"message\"\n }), \", while\\nhandled preflight errors use \", _jsx(_components.code, {\n children: \"status: \\\"error\\\"\"\n }), \" and \", _jsx(_components.code, {\n children: \"error\"\n }), \". MCP failures are tool\\nerrors or SDK input-validation errors. None confirms registration or activation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"authentication\"\n }), \" and \", _jsx(_components.a, {\n href: \"/mcp\",\n children: \"MCP connection guidance\"\n }), \".\\nApplication persistence, origin proof/reverification, provider configuration,\\nfan bootstrap, suspension and quota policy require their own completed contracts.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"POST","path":"/api/applications/registration/validate","spec":"applications.json"},"searchText":"Check an application proposal Validate proposed app addresses in your workspace without registering or activating an application. Sites Application proposals POST /api/applications/registration/validate Pending coordinated release. This checks a proposal; it does not register an app or make its origins trusted. Discover tool availability in your connected host before use. Before connecting an external app, check its proposed name, environment, origins and return URLs. A successful result means those values passed validation for the selected workspace. It does not prove domain ownership. ## What happens The preflight runs after normal Recoup authentication. First-time sign-in can perform normal account provisioning and send its welcome email. After that, this validator does not persist an application or issue application credentials. It does not edit provider callbacks, create fan identities or sessions, allocate capacity, or authorize purchases and spending. `workspace_id` and `billing_owner_id` come from the authenticated account or an organization it can access. They describe the proposed owner only. Supplying `organization_id` does not grant workspace access. Do not submit account or billing ownership overrides, secrets or tokens in the proposal. The result is flat and includes `status: \"validated\"`, `persisted: false` and `origins_verified: false`. It contains no application ID or token to install. ## Addresses and environments - Choose `development` or `production` explicitly for each proposal. - Use exact canonical origins such as `https://music.example`, without a trailing slash, wildcard, path, credentials, query or fragment. Different hosts and ports are different origins. - HTTPS is required. Development also accepts HTTP on `localhost`, `127.0.0.1` and `[::1]`; these loopback hosts are rejected in production. - A return URL must be an exact canonical URL on one of the proposed origins, without credentials or fragments. For a bare host use its canonical trailing slash, such as `https://music.example/`. Query strings are retained literally. - Each list takes 1–32 distinct addresses, each at most 2048 characters. The name is trimmed and must then contain 1–120 characters. These are input limits, not subscription or usage allowances. Matching a return URL to a caller-proposed origin does not establish that the caller owns either address. No DNS check, URL fetch or domain proof is performed. ## Standard MCP On a standard API-key MCP connection that exposes `validate_application_registration`, use the same proposal fields as HTTP. Account identity comes from the connection; do not add `account_id` or extract a host-managed OAuth token. Delegated OAuth excludes this tool, including connections with `mcp:tools`. HTTP and standard MCP share proposal validation; their transport-specific error envelopes differ. HTTP authentication errors can use `error` or `message`, while handled preflight errors use `status: \"error\"` and `error`. MCP failures are tool errors or SDK input-validation errors. None confirms registration or activation. See [authentication](/authentication) and [MCP connection guidance](/mcp). Application persistence, origin proof/reverification, provider configuration, fan bootstrap, suspension and quota policy require their own completed contracts. "},{"slug":"api-reference/sites/overview","title":"Sites","description":"Create, generate, and publish fan experiences through the API or MCP.","category":"Sites","group":"Sites","source":"api-reference/sites/overview.mdx","body":"Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a **private draft**. Generation never publishes it automatically.\n\n## Authentication\n\nPrivate HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`.\nMCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection.\n\nThe caller is derived from authentication. Do not send an `account_id`. An optional `organizationId` selects a workspace the caller can access. Omit it for the authenticated account's workspace.\n\n## Endpoints and tools\n\n| HTTP | MCP tool | Result |\n| --- | --- | --- |\n| `GET /api/sites` | `list_sites` | `{ sites: [...] }` |\n| `POST /api/sites` | `create_site` | `{ site: ... }`, HTTP 201 |\n| `GET /api/sites/{id}` | `get_site` | `{ site: ... }` |\n| `PATCH /api/sites/{id}` action `concepts` | `propose_site_concepts` | Short pitches or missing context |\n| `PATCH /api/sites/{id}` action `generate` | `generate_site` | Generate from an optional customer-selected pitch; otherwise select a concept |\n| `PATCH /api/sites/{id}` action `generation` | `get_site_generation` | Status for the specified generation token |\n| `PATCH /api/sites/{id}` action `publish` | `publish_site` | Publish the saved draft or the playable build selected by `generationToken` |\n| `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained |\n| `PATCH /api/sites/{id}` action `delete` | `delete_site` | `{ \"deleted\": true, \"id\": \"...\" }` |\n| `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 |\n| `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` |\n\nListing accepts optional `organizationId` and `artistId` query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response.\n\n## Create and generate\n\nCreate a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL.\n\n```bash\ncurl https://api.recoupable.dev/api/sites \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"releaseUrl\":\"https://open.spotify.com/track/TRACK_ID\",\"brief\":\"Build a maze game\"}'\n```\n\nOptional creation fields: `name` (120 characters), `brief` (6,000), `organizationId`, `artistId`, and `assets` (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used.\n\nRead `site.id` and `site.revision`, then start automatic generation:\n\n```json\n{\"action\":\"generate\",\"revision\":0}\n```\n\nFor Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused.\n\nTo choose a concept yourself before generation, optionally request pitches:\n\n```json\n{\"action\":\"concepts\",\"revision\":0}\n```\n\nSend this to `PATCH /api/sites/{id}`, or call MCP `propose_site_concepts` with `id` and `revision`. Optional `instruction` and `contextBriefId` apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft.\n\nThe response is `{ concepts: { status, candidates, reason }, revision }`. Status is `ready`, `needs-context`, or `no-good-concept`. Metadata and cover details alone return `needs-context`; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork.\n\nIn the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains `name`, `activity`, `fanMotivation`, `songOrArtistConnection`, and `friendHook`. Pass the selected object unchanged as `approvedConcept`:\n\n```json\n{\n \"action\": \"generate\",\n \"revision\": 0,\n \"approvedConcept\": {\n \"name\": \"CUSTOMER_SELECTED_NAME\",\n \"activity\": \"SELECTED_ACTIVITY\",\n \"fanMotivation\": \"SELECTED_MOTIVATION\",\n \"songOrArtistConnection\": \"SELECTED_CONNECTION\",\n \"friendHook\": \"SELECTED_HOOK\"\n }\n}\n```\n\nMCP `generate_site` accepts the same fields plus `id`, without `action`. A customer-authored concept is also accepted. The optional `approvedConcept` preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context.\n\nGeneration defaults to background execution and returns a generation token; poll `get_site_generation` (HTTP action `generation`) for the result. Set `background: false` only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked `needs-review`; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass.\n\nGeneration failures identify the stopped stage and leave the saved draft unchanged. A `409` means another edit changed the revision; read the site again before retrying.\n\n### Poll background generation\n\nSend this JSON body to `PATCH /api/sites/{id}` using the token returned by the\ngeneration request. MCP `get_site_generation` takes `id` and `token`, without `action`.\nPolling uses `token`; publishing and cancellation use `generationToken`.\n\n```json\n{\"action\":\"generation\",\"token\":\"TOKEN_FROM_GENERATION\"}\n```\n\nThe token is bound to its site and caller and expires. Invalid, expired or\nmismatched tokens return 404 during token verification; a missing or empty token\nis invalid input (400). A running job is not proof that a\nplayable build or a published page exists; read the returned status and progress.\n\n## Generate from saved Context Engine evidence\n\nSave a single-song `creative_direction` brief using the Context Engine `save_brief` action, then pass its snapshot ID when requesting pitches:\n\n```json\n{\n \"action\": \"concepts\",\n \"revision\": 0,\n \"contextBriefId\": \"SAVED_BRIEF_UUID\"\n}\n```\n\nPass the same `contextBriefId` with the selected `approvedConcept` to generation. It is available on both MCP `propose_site_concepts` and `generate_site`. Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied.\n\nThis path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial.\n\nGeneration still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response.\n\n## Publish\n\nAfter reviewing the intended draft or preview, publish through the same PATCH\nendpoint or MCP `publish_site`, using the site's current saved revision.\n\nPublishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports `fanConnection: \"enabled\"`.\n\nFor a custom hosted destination, HTTP callers may include `returnUrl` (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations.\n\nThe public page is `https://chat.recoupable.dev/s/{id}`.\n\n### Publish the saved draft\n\nUse the current revision from the saved site (3 in this example):\n\n```json\n{\"action\":\"publish\",\"revision\":3}\n```\n\nOmitting `generationToken` selects the saved draft, even when a background job has\na newer preview. MCP `publish_site` takes `id` and `revision`, without `action`.\n\n### Publish a working preview\n\nTo publish a specific working preview from a background generation, pass its\ntoken as `generationToken` and the site's current saved revision:\n\n```json\n{\"action\":\"publish\",\"revision\":3,\"generationToken\":\"TOKEN_FROM_GENERATION\"}\n```\n\nMCP `publish_site` uses the same fields plus `id`, without `action`. The token must\nmatch the site and caller. The selected build must contain a completed playable\nbuild step for the current site/workspace/revision; the whole generation job need\nnot already be completed. A preview that is not ready returns 400, a stale build\nreturns 409, and invalid or expired token access returns 404. A temporary saved-build\nfailure may return 503. Without `generationToken`, publication uses the saved draft;\nit does not automatically select the newest background preview.\n\n### Upgrade required\n\nAn ineligible workspace receives HTTP 402 with an error body, for example:\n\n```json\n{\"error\":\"An active paid Recoup subscription is required to publish a site. Subscribe in this site’s workspace, then publish again.\"}\n```\n\nSubscribe in the site's owning workspace before retrying the intended publish.\nThis response does not publish the site or create a checkout session.\n\n### Unpublish\n\nSend `PATCH /api/sites/{id}` with the current revision to remove the public\nsnapshot while retaining the draft. MCP `unpublish_site` takes `id` and `revision`.\n\n```json\n{\"action\":\"unpublish\",\"revision\":3}\n```\n\nAgents should publish, unpublish or delete only when explicitly instructed.\n\n## Delete and cancel generation\n\nDelete only when explicitly instructed. Send `PATCH /api/sites/{id}` with `action: \"delete\"` and the current `revision` in its JSON request body (Content-Type: application/json). Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.\n\nFor example, use the current saved revision and the token returned by a known generation:\n\n```json\n{\"action\":\"delete\",\"revision\":3,\"generationToken\":\"TOKEN_FROM_GENERATION\"}\n```\n\nOmit generationToken when no known generation needs cancellation.\n\nDeletion checks workspace access and revision, then returns `{ \"deleted\": true, \"id\": \"...\" }`. A stale revision returns 409; reload before retrying. Unpublish with `action: \"unpublish\"` when the draft should remain available.\n\n## Uploads\n\nHTTP uploads are multipart forms with a `file` field and optional `organizationId` query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature.\n\nMCP's `upload_site_asset` accepts `name`, `contentType`, `base64` file bytes, and optional `organizationId`. It uses the same validation and storage path as HTTP.\n\n## Public endpoints\n\n- `GET /api/sites/public/{id}` returns `{ snapshot: ... }` for a published site only. Drafts, account identifiers, and signup data are excluded.\n- `POST /api/sites/public/{id}/signup` accepts `{\"email\":\"fan@example.com\",\"consent\":\"yes\"}`. An optional `website` honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups.\n\nPublic pages and the browser music player render in the chat app. The API provides\nsnapshots, generation, uploads, signup persistence and the fan-connection integration\nroutes listed below.\n\n## Route coverage\n\nThe lifecycle and public snapshot/signup operations above are documented here in\nprose; they are not a complete Sites OpenAPI specification. The following existing\nroutes are accounted for as integration surfaces, outside the copyable lifecycle\nexamples. Listing them does not establish live authorization or add an MCP tool.\n\n### Authenticated integration routes\n\n| HTTP | Purpose |\n| --- | --- |\n| `GET /api/sites/{id}/fan-connection` | Read fan-connection configuration |\n| `PUT /api/sites/{id}/fan-connection` | Configure the fan connection through the authenticated integration |\n| `GET /api/sites/{id}/fans` | Fan reporting |\n| `GET /api/sites/{id}/activity` | Activity reporting |\n\n### Browser integration routes\n\n| HTTP | Purpose |\n| --- | --- |\n| `GET /api/sites/apple/config` | Browser music configuration |\n| `POST /api/sites/public/{id}/activity` | Published-site activity collection |\n| `GET /api/sites/public/{id}/spotify` | Show the fan-connection acceptance page |\n| `POST /api/sites/public/{id}/spotify` | Begin Spotify authorization after acceptance |\n\nThese browser flows are not replacements for a private lifecycle request or proof\nof a completed fan connection. Email signup and Spotify connection are distinct.\n\n### Provider callback\n\n`GET /api/sites/spotify/callback` completes the provider redirect flow. It is\nintentionally excluded from agent lifecycle examples; do not invoke it as a\nstandalone operation. OPTIONS preflight handlers are also excluded from the\noperation tables because they serve browser CORS negotiation.\n\n## Errors\n\n- `402`: publication requires an eligible paid workspace.\n\n`400` invalid input; `401` missing/invalid authentication; `403` workspace or artist access denied; `404` missing/unpublished site; `409` stale revision; `422` Spotify metadata unavailable; `503` temporary operation failure.\n","headings":[{"title":"Authentication","id":"authentication"},{"title":"Endpoints and tools","id":"endpoints-and-tools"},{"title":"Create and generate","id":"create-and-generate"},{"title":"Generate from saved Context Engine evidence","id":"generate-from-saved-context-engine-evidence"},{"title":"Publish","id":"publish"},{"title":"Delete and cancel generation","id":"delete-and-cancel-generation"},{"title":"Uploads","id":"uploads"},{"title":"Public endpoints","id":"public-endpoints"},{"title":"Route coverage","id":"route-coverage"},{"title":"Errors","id":"errors"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a \", _jsx(_components.strong, {\n children: \"private draft\"\n }), \". Generation never publishes it automatically.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication\",\n children: \"Authentication\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Private HTTP endpoints accept exactly one of \", _jsx(_components.code, {\n children: \"x-api-key: YOUR_API_KEY\"\n }), \" or \", _jsx(_components.code, {\n children: \"Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN\"\n }), \".\\nMCP uses the existing authenticated \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" connection.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The caller is derived from authentication. Do not send an \", _jsx(_components.code, {\n children: \"account_id\"\n }), \". An optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" selects a workspace the caller can access. Omit it for the authenticated account's workspace.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"endpoints-and-tools\",\n children: \"Endpoints and tools\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"MCP tool\"\n }), _jsx(_components.th, {\n children: \"Result\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"list_sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ sites: [...] }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"create_site\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"{ site: ... }\"\n }), \", HTTP 201\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ site: ... }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"concepts\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"propose_site_concepts\"\n })\n }), _jsx(_components.td, {\n children: \"Short pitches or missing context\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"generate\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"generate_site\"\n })\n }), _jsx(_components.td, {\n children: \"Generate from an optional customer-selected pitch; otherwise select a concept\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"generation\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site_generation\"\n })\n }), _jsx(_components.td, {\n children: \"Status for the specified generation token\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"publish\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"publish_site\"\n })\n }), _jsxs(_components.td, {\n children: [\"Publish the saved draft or the playable build selected by \", _jsx(_components.code, {\n children: \"generationToken\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"unpublish\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"unpublish_site\"\n })\n }), _jsx(_components.td, {\n children: \"Public snapshot removed, draft retained\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"delete\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"delete_site\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ \\\"deleted\\\": true, \\\"id\\\": \\\"...\\\" }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/signups\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site_signups\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"{ signups: [{ email, created_at }] }\"\n }), \", up to 10,000\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/assets\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"upload_site_asset\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ asset: { url, name, type } }\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Listing accepts optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" and \", _jsx(_components.code, {\n children: \"artistId\"\n }), \" query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"create-and-generate\",\n children: \"Create and generate\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Create a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL.\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl https://api.recoupable.dev/api/sites \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"releaseUrl\\\":\\\"https://open.spotify.com/track/TRACK_ID\\\",\\\"brief\\\":\\\"Build a maze game\\\"}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Optional creation fields: \", _jsx(_components.code, {\n children: \"name\"\n }), \" (120 characters), \", _jsx(_components.code, {\n children: \"brief\"\n }), \" (6,000), \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \", \", _jsx(_components.code, {\n children: \"artistId\"\n }), \", and \", _jsx(_components.code, {\n children: \"assets\"\n }), \" (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Read \", _jsx(_components.code, {\n children: \"site.id\"\n }), \" and \", _jsx(_components.code, {\n children: \"site.revision\"\n }), \", then start automatic generation:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"generate\\\",\\\"revision\\\":0}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"For Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"To choose a concept yourself before generation, optionally request pitches:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"concepts\\\",\\\"revision\\\":0}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send this to \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \", or call MCP \", _jsx(_components.code, {\n children: \"propose_site_concepts\"\n }), \" with \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \". Optional \", _jsx(_components.code, {\n children: \"instruction\"\n }), \" and \", _jsx(_components.code, {\n children: \"contextBriefId\"\n }), \" apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response is \", _jsx(_components.code, {\n children: \"{ concepts: { status, candidates, reason }, revision }\"\n }), \". Status is \", _jsx(_components.code, {\n children: \"ready\"\n }), \", \", _jsx(_components.code, {\n children: \"needs-context\"\n }), \", or \", _jsx(_components.code, {\n children: \"no-good-concept\"\n }), \". Metadata and cover details alone return \", _jsx(_components.code, {\n children: \"needs-context\"\n }), \"; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"In the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"activity\"\n }), \", \", _jsx(_components.code, {\n children: \"fanMotivation\"\n }), \", \", _jsx(_components.code, {\n children: \"songOrArtistConnection\"\n }), \", and \", _jsx(_components.code, {\n children: \"friendHook\"\n }), \". Pass the selected object unchanged as \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"action\\\": \\\"generate\\\",\\n \\\"revision\\\": 0,\\n \\\"approvedConcept\\\": {\\n \\\"name\\\": \\\"CUSTOMER_SELECTED_NAME\\\",\\n \\\"activity\\\": \\\"SELECTED_ACTIVITY\\\",\\n \\\"fanMotivation\\\": \\\"SELECTED_MOTIVATION\\\",\\n \\\"songOrArtistConnection\\\": \\\"SELECTED_CONNECTION\\\",\\n \\\"friendHook\\\": \\\"SELECTED_HOOK\\\"\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP \", _jsx(_components.code, {\n children: \"generate_site\"\n }), \" accepts the same fields plus \", _jsx(_components.code, {\n children: \"id\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \". A customer-authored concept is also accepted. The optional \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \" preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Generation defaults to background execution and returns a generation token; poll \", _jsx(_components.code, {\n children: \"get_site_generation\"\n }), \" (HTTP action \", _jsx(_components.code, {\n children: \"generation\"\n }), \") for the result. Set \", _jsx(_components.code, {\n children: \"background: false\"\n }), \" only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked \", _jsx(_components.code, {\n children: \"needs-review\"\n }), \"; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Generation failures identify the stopped stage and leave the saved draft unchanged. A \", _jsx(_components.code, {\n children: \"409\"\n }), \" means another edit changed the revision; read the site again before retrying.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"poll-background-generation\",\n children: \"Poll background generation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send this JSON body to \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" using the token returned by the\\ngeneration request. MCP \", _jsx(_components.code, {\n children: \"get_site_generation\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"token\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \".\\nPolling uses \", _jsx(_components.code, {\n children: \"token\"\n }), \"; publishing and cancellation use \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"generation\\\",\\\"token\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"The token is bound to its site and caller and expires. Invalid, expired or\\nmismatched tokens return 404 during token verification; a missing or empty token\\nis invalid input (400). A running job is not proof that a\\nplayable build or a published page exists; read the returned status and progress.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"generate-from-saved-context-engine-evidence\",\n children: \"Generate from saved Context Engine evidence\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save a single-song \", _jsx(_components.code, {\n children: \"creative_direction\"\n }), \" brief using the Context Engine \", _jsx(_components.code, {\n children: \"save_brief\"\n }), \" action, then pass its snapshot ID when requesting pitches:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"action\\\": \\\"concepts\\\",\\n \\\"revision\\\": 0,\\n \\\"contextBriefId\\\": \\\"SAVED_BRIEF_UUID\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass the same \", _jsx(_components.code, {\n children: \"contextBriefId\"\n }), \" with the selected \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \" to generation. It is available on both MCP \", _jsx(_components.code, {\n children: \"propose_site_concepts\"\n }), \" and \", _jsx(_components.code, {\n children: \"generate_site\"\n }), \". Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Generation still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"publish\",\n children: \"Publish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"After reviewing the intended draft or preview, publish through the same PATCH\\nendpoint or MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \", using the site's current saved revision.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Publishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports \", _jsx(_components.code, {\n children: \"fanConnection: \\\"enabled\\\"\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a custom hosted destination, HTTP callers may include \", _jsx(_components.code, {\n children: \"returnUrl\"\n }), \" (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The public page is \", _jsx(_components.code, {\n children: \"https://chat.recoupable.dev/s/{id}\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"publish-the-saved-draft\",\n children: \"Publish the saved draft\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the current revision from the saved site (3 in this example):\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"publish\\\",\\\"revision\\\":3}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Omitting \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" selects the saved draft, even when a background job has\\na newer preview. MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"publish-a-working-preview\",\n children: \"Publish a working preview\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To publish a specific working preview from a background generation, pass its\\ntoken as \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" and the site's current saved revision:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"publish\\\",\\\"revision\\\":3,\\\"generationToken\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \" uses the same fields plus \", _jsx(_components.code, {\n children: \"id\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \". The token must\\nmatch the site and caller. The selected build must contain a completed playable\\nbuild step for the current site/workspace/revision; the whole generation job need\\nnot already be completed. A preview that is not ready returns 400, a stale build\\nreturns 409, and invalid or expired token access returns 404. A temporary saved-build\\nfailure may return 503. Without \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \", publication uses the saved draft;\\nit does not automatically select the newest background preview.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"upgrade-required\",\n children: \"Upgrade required\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"An ineligible workspace receives HTTP 402 with an error body, for example:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"error\\\":\\\"An active paid Recoup subscription is required to publish a site. Subscribe in this site’s workspace, then publish again.\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Subscribe in the site's owning workspace before retrying the intended publish.\\nThis response does not publish the site or create a checkout session.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"unpublish\",\n children: \"Unpublish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" with the current revision to remove the public\\nsnapshot while retaining the draft. MCP \", _jsx(_components.code, {\n children: \"unpublish_site\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"unpublish\\\",\\\"revision\\\":3}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Agents should publish, unpublish or delete only when explicitly instructed.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"delete-and-cancel-generation\",\n children: \"Delete and cancel generation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Delete only when explicitly instructed. Send \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" with \", _jsx(_components.code, {\n children: \"action: \\\"delete\\\"\"\n }), \" and the current \", _jsx(_components.code, {\n children: \"revision\"\n }), \" in its JSON request body (Content-Type: application/json). Include \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For example, use the current saved revision and the token returned by a known generation:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"delete\\\",\\\"revision\\\":3,\\\"generationToken\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Omit generationToken when no known generation needs cancellation.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Deletion checks workspace access and revision, then returns \", _jsx(_components.code, {\n children: \"{ \\\"deleted\\\": true, \\\"id\\\": \\\"...\\\" }\"\n }), \". A stale revision returns 409; reload before retrying. Unpublish with \", _jsx(_components.code, {\n children: \"action: \\\"unpublish\\\"\"\n }), \" when the draft should remain available.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"uploads\",\n children: \"Uploads\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP uploads are multipart forms with a \", _jsx(_components.code, {\n children: \"file\"\n }), \" field and optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP's \", _jsx(_components.code, {\n children: \"upload_site_asset\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"contentType\"\n }), \", \", _jsx(_components.code, {\n children: \"base64\"\n }), \" file bytes, and optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \". It uses the same validation and storage path as HTTP.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"public-endpoints\",\n children: \"Public endpoints\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{id}\"\n }), \" returns \", _jsx(_components.code, {\n children: \"{ snapshot: ... }\"\n }), \" for a published site only. Drafts, account identifiers, and signup data are excluded.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/signup\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{\\\"email\\\":\\\"fan@example.com\\\",\\\"consent\\\":\\\"yes\\\"}\"\n }), \". An optional \", _jsx(_components.code, {\n children: \"website\"\n }), \" honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Public pages and the browser music player render in the chat app. The API provides\\nsnapshots, generation, uploads, signup persistence and the fan-connection integration\\nroutes listed below.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"route-coverage\",\n children: \"Route coverage\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The lifecycle and public snapshot/signup operations above are documented here in\\nprose; they are not a complete Sites OpenAPI specification. The following existing\\nroutes are accounted for as integration surfaces, outside the copyable lifecycle\\nexamples. Listing them does not establish live authorization or add an MCP tool.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"authenticated-integration-routes\",\n children: \"Authenticated integration routes\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"Purpose\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/fan-connection\"\n })\n }), _jsx(_components.td, {\n children: \"Read fan-connection configuration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"PUT /api/sites/{id}/fan-connection\"\n })\n }), _jsx(_components.td, {\n children: \"Configure the fan connection through the authenticated integration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/fans\"\n })\n }), _jsx(_components.td, {\n children: \"Fan reporting\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/activity\"\n })\n }), _jsx(_components.td, {\n children: \"Activity reporting\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"browser-integration-routes\",\n children: \"Browser integration routes\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"Purpose\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/apple/config\"\n })\n }), _jsx(_components.td, {\n children: \"Browser music configuration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/activity\"\n })\n }), _jsx(_components.td, {\n children: \"Published-site activity collection\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/public/{id}/spotify\"\n })\n }), _jsx(_components.td, {\n children: \"Show the fan-connection acceptance page\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/spotify\"\n })\n }), _jsx(_components.td, {\n children: \"Begin Spotify authorization after acceptance\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"These browser flows are not replacements for a private lifecycle request or proof\\nof a completed fan connection. Email signup and Spotify connection are distinct.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"provider-callback\",\n children: \"Provider callback\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/spotify/callback\"\n }), \" completes the provider redirect flow. It is\\nintentionally excluded from agent lifecycle examples; do not invoke it as a\\nstandalone operation. OPTIONS preflight handlers are also excluded from the\\noperation tables because they serve browser CORS negotiation.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"errors\",\n children: \"Errors\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"402\"\n }), \": publication requires an eligible paid workspace.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"400\"\n }), \" invalid input; \", _jsx(_components.code, {\n children: \"401\"\n }), \" missing/invalid authentication; \", _jsx(_components.code, {\n children: \"403\"\n }), \" workspace or artist access denied; \", _jsx(_components.code, {\n children: \"404\"\n }), \" missing/unpublished site; \", _jsx(_components.code, {\n children: \"409\"\n }), \" stale revision; \", _jsx(_components.code, {\n children: \"422\"\n }), \" Spotify metadata unavailable; \", _jsx(_components.code, {\n children: \"503\"\n }), \" temporary operation failure.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Sites Create, generate, and publish fan experiences through the API or MCP. Sites Sites Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a **private draft**. Generation never publishes it automatically. ## Authentication Private HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`. MCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection. The caller is derived from authentication. Do not send an `account_id`. An optional `organizationId` selects a workspace the caller can access. Omit it for the authenticated account's workspace. ## Endpoints and tools | HTTP | MCP tool | Result | | --- | --- | --- | | `GET /api/sites` | `list_sites` | `{ sites: [...] }` | | `POST /api/sites` | `create_site` | `{ site: ... }`, HTTP 201 | | `GET /api/sites/{id}` | `get_site` | `{ site: ... }` | | `PATCH /api/sites/{id}` action `concepts` | `propose_site_concepts` | Short pitches or missing context | | `PATCH /api/sites/{id}` action `generate` | `generate_site` | Generate from an optional customer-selected pitch; otherwise select a concept | | `PATCH /api/sites/{id}` action `generation` | `get_site_generation` | Status for the specified generation token | | `PATCH /api/sites/{id}` action `publish` | `publish_site` | Publish the saved draft or the playable build selected by `generationToken` | | `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained | | `PATCH /api/sites/{id}` action `delete` | `delete_site` | `{ \"deleted\": true, \"id\": \"...\" }` | | `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 | | `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` | Listing accepts optional `organizationId` and `artistId` query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response. ## Create and generate Create a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL. Optional creation fields: `name` (120 characters), `brief` (6,000), `organizationId`, `artistId`, and `assets` (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used. Read `site.id` and `site.revision`, then start automatic generation: For Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused. To choose a concept yourself before generation, optionally request pitches: Send this to `PATCH /api/sites/{id}`, or call MCP `propose_site_concepts` with `id` and `revision`. Optional `instruction` and `contextBriefId` apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft. The response is `{ concepts: { status, candidates, reason }, revision }`. Status is `ready`, `needs-context`, or `no-good-concept`. Metadata and cover details alone return `needs-context`; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork. In the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains `name`, `activity`, `fanMotivation`, `songOrArtistConnection`, and `friendHook`. Pass the selected object unchanged as `approvedConcept`: MCP `generate_site` accepts the same fields plus `id`, without `action`. A customer-authored concept is also accepted. The optional `approvedConcept` preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context. Generation defaults to background execution and returns a generation token; poll `get_site_generation` (HTTP action `generation`) for the result. Set `background: false` only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked `needs-review`; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass. Generation failures identify the stopped stage and leave the saved draft unchanged. A `409` means another edit changed the revision; read the site again before retrying. ### Poll background generation Send this JSON body to `PATCH /api/sites/{id}` using the token returned by the generation request. MCP `get_site_generation` takes `id` and `token`, without `action`. Polling uses `token`; publishing and cancellation use `generationToken`. The token is bound to its site and caller and expires. Invalid, expired or mismatched tokens return 404 during token verification; a missing or empty token is invalid input (400). A running job is not proof that a playable build or a published page exists; read the returned status and progress. ## Generate from saved Context Engine evidence Save a single-song `creative_direction` brief using the Context Engine `save_brief` action, then pass its snapshot ID when requesting pitches: Pass the same `contextBriefId` with the selected `approvedConcept` to generation. It is available on both MCP `propose_site_concepts` and `generate_site`. Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied. This path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial. Generation still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response. ## Publish After reviewing the intended draft or preview, publish through the same PATCH endpoint or MCP `publish_site`, using the site's current saved revision. Publishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports `fanConnection: \"enabled\"`. For a custom hosted destination, HTTP callers may include `returnUrl` (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations. The public page is `https://chat.recoupable.dev/s/{id}`. ### Publish the saved draft Use the current revision from the saved site (3 in this example): Omitting `generationToken` selects the saved draft, even when a background job has a newer preview. MCP `publish_site` takes `id` and `revision`, without `action`. ### Publish a working preview To publish a specific working preview from a background generation, pass its token as `generationToken` and the site's current saved revision: MCP `publish_site` uses the same fields plus `id`, without `action`. The token must match the site and caller. The selected build must contain a completed playable build step for the current site/workspace/revision; the whole generation job need not already be completed. A preview that is not ready returns 400, a stale build returns 409, and invalid or expired token access returns 404. A temporary saved-build failure may return 503. Without `generationToken`, publication uses the saved draft; it does not automatically select the newest background preview. ### Upgrade required An ineligible workspace receives HTTP 402 with an error body, for example: Subscribe in the site's owning workspace before retrying the intended publish. This response does not publish the site or create a checkout session. ### Unpublish Send `PATCH /api/sites/{id}` with the current revision to remove the public snapshot while retaining the draft. MCP `unpublish_site` takes `id` and `revision`. Agents should publish, unpublish or delete only when explicitly instructed. ## Delete and cancel generation Delete only when explicitly instructed. Send `PATCH /api/sites/{id}` with `action: \"delete\"` and the current `revision` in its JSON request body (Content-Type: application/json). Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job. For example, use the current saved revision and the token returned by a known generation: Omit generationToken when no known generation needs cancellation. Deletion checks workspace access and revision, then returns `{ \"deleted\": true, \"id\": \"...\" }`. A stale revision returns 409; reload before retrying. Unpublish with `action: \"unpublish\"` when the draft should remain available. ## Uploads HTTP uploads are multipart forms with a `file` field and optional `organizationId` query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature. MCP's `upload_site_asset` accepts `name`, `contentType`, `base64` file bytes, and optional `organizationId`. It uses the same validation and storage path as HTTP. ## Public endpoints - `GET /api/sites/public/{id}` returns `{ snapshot: ... }` for a published site only. Drafts, account identifiers, and signup data are excluded. - `POST /api/sites/public/{id}/signup` accepts `{\"email\":\"fan@example.com\",\"consent\":\"yes\"}`. An optional `website` honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups. Public pages and the browser music player render in the chat app. The API provides snapshots, generation, uploads, signup persistence and the fan-connection integration routes listed below. ## Route coverage The lifecycle and public snapshot/signup operations above are documented here in prose; they are not a complete Sites OpenAPI specification. The following existing routes are accounted for as integration surfaces, outside the copyable lifecycle examples. Listing them does not establish live authorization or add an MCP tool. ### Authenticated integration routes | HTTP | Purpose | | --- | --- | | `GET /api/sites/{id}/fan-connection` | Read fan-connection configuration | | `PUT /api/sites/{id}/fan-connection` | Configure the fan connection through the authenticated integration | | `GET /api/sites/{id}/fans` | Fan reporting | | `GET /api/sites/{id}/activity` | Activity reporting | ### Browser integration routes | HTTP | Purpose | | --- | --- | | `GET /api/sites/apple/config` | Browser music configuration | | `POST /api/sites/public/{id}/activity` | Published-site activity collection | | `GET /api/sites/public/{id}/spotify` | Show the fan-connection acceptance page | | `POST /api/sites/public/{id}/spotify` | Begin Spotify authorization after acceptance | These browser flows are not replacements for a private lifecycle request or proof of a completed fan connection. Email signup and Spotify connection are distinct. ### Provider callback `GET /api/sites/spotify/callback` completes the provider redirect flow. It is intentionally excluded from agent lifecycle examples; do not invoke it as a standalone operation. OPTIONS preflight handlers are also excluded from the operation tables because they serve browser CORS negotiation. ## Errors - `402`: publication requires an eligible paid workspace. `400` invalid input; `401` missing/invalid authentication; `403` workspace or artist access denied; `404` missing/unpublished site; `409` stale revision; `422` Spotify metadata unavailable; `503` temporary operation failure. "},{"slug":"essentials/site-fan-connection","title":"Connect Spotify fans to a site","description":"Configure paid fan connection from an artist agent and retrieve fans attributed to its site.","category":"Sites","group":"Sites","source":"essentials/site-fan-connection.mdx","body":"Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: `https://api.recoupable.dev`.\n\nPrivate calls use `x-api-key: $RECOUP_API_KEY` (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key.\n\n## Customer and site\n\n- `GET /api/accounts/id`: verify the current credential.\n- `POST /api/agents/signup` with `{ \"email\": \"customer@example.com\" }`: request email verification.\n- `POST /api/agents/verify` with `{ \"email\": \"customer@example.com\", \"code\": \"123456\" }`: receive `api_key`; never echo it.\n- `GET /api/artists`: inspect the caller's roster and choose the artist's account ID.\n- `GET /api/sites`: inspect existing site records.\n- `POST /api/sites` with `{ \"name\": \"Release experience\", \"artistId\": \"ARTIST_ACCOUNT_UUID\", \"releaseUrl\": \"https://open.spotify.com/track/TRACK_ID\" }`: register a site. Add `organizationId` only for a selected authorized workspace. Read the returned `site.id`. Omit owner/account ID fields; ownership comes from authentication.\n\n## Configure\n\n`GET /api/sites/{siteId}/fan-connection` returns:\n\n```json\n{\n \"siteId\": \"SITE_UUID\",\n \"ownerId\": \"WORKSPACE_ACCOUNT_UUID\",\n \"artistId\": \"ARTIST_ACCOUNT_UUID\",\n \"config\": null,\n \"connectUrl\": null\n}\n```\n\nExisting `config` contains `site_id`, `return_url`, `marketing_text`, `enabled` and `revision`. Update with `PUT /api/sites/{siteId}/fan-connection`:\n\n```json\n{\n \"returnUrl\": \"https://artist.example/release\",\n \"marketingText\": \"I agree to receive release announcements and offers by email from Example Artist.\",\n \"enabled\": true,\n \"revision\": 0\n}\n```\n\nUse the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public `connectUrl`; always use that returned URL.\n\n- 400: invalid input or missing artist attribution.\n- 401/403: reconnect the customer or select an authorized workspace.\n- 402: no eligible paid subscription for the site's owning account.\n- 404: missing site or API not deployed; inspect the actual response.\n- 409: another configuration update won; reload and reconcile before retry.\n- 503: provider, billing or storage unavailable; surface the dependency.\n\nSpotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing `POST /api/subscriptions/sessions` accepts `{plan: \"starter\" | \"pro\", successUrl, cancelUrl?}` and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature.\n\n## Public fan journey\n\n`GET /api/sites/public/{siteId}/spotify` displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's `/api/sites/spotify/callback`; Recoup then returns to the configured site URL with `recoup_spotify=connected`, `cancelled` or `failed`.\n\nOnly a successful provider exchange with `user-read-email` and `user-read-private` creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site.\n\n## Read fans\n\n`GET /api/sites/{siteId}/fans?offset=0&limit=50` (private):\n\n```json\n{\n \"fans\": [],\n \"total\": 0,\n \"offset\": 0,\n \"limit\": 50\n}\n```\n\nEach fan has `id`, `site_id`, `spotify_id`, `display_name`, `email`, first/last connection timestamps and nested `site_fan_connections` with `site_fan_permissions` and `site_fan_marketing_consents`. Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data.\n\nStarter Checkout can return HTTP 400 `starter_unavailable` when its price is not\nconfigured. Explain the unavailable option and use a configured plan; do not retry\nit as a transient provider failure.\n\n## Recoup operator setup\n\nOperators must apply `20260928010000_site_fan_connections.sql`, configure `SITES_SPOTIFY_CLIENT_ID`, register an HTTPS callback ending `/api/sites/spotify/callback`, set `SITES_FAN_SPOTIFY_REDIRECT_URI`. This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate.\n\n## Activity reporting\n\n`GET /api/sites/{siteId}/activity` returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. `POST /api/sites/public/{siteId}/activity` accepts `{id: EVENT_UUID, visitId: VISIT_UUID, event: \"visit\" | \"start\" | \"complete\" | \"replay\" | \"share\"}`. Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history.\n\nRecoup-hosted generated sites use the trusted host bridge: `window.recoup.track(event)` reports approved events; `window.recoup.join()` reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server.\n\n## Playback for Premium and Free listeners\n\nThe hosted player reads the connected Spotify profile's `product` field. Premium listeners use the Spotify Web Playback SDK. Free (`free` or `open`) listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording.\n\n`GET /api/sites/public/{siteId}` includes `playbackAudioUrl`, a fresh signed audio URL valid for one hour, or `null` when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans.\n\nFile playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable.\n","headings":[{"title":"Customer and site","id":"customer-and-site"},{"title":"Configure","id":"configure"},{"title":"Public fan journey","id":"public-fan-journey"},{"title":"Read fans","id":"read-fans"},{"title":"Recoup operator setup","id":"recoup-operator-setup"},{"title":"Activity reporting","id":"activity-reporting"},{"title":"Playback for Premium and Free listeners","id":"playback-for-premium-and-free-listeners"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Private calls use \", _jsx(_components.code, {\n children: \"x-api-key: $RECOUP_API_KEY\"\n }), \" (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"customer-and-site\",\n children: \"Customer and site\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n }), \": verify the current credential.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"email\\\": \\\"customer@example.com\\\" }\"\n }), \": request email verification.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"email\\\": \\\"customer@example.com\\\", \\\"code\\\": \\\"123456\\\" }\"\n }), \": receive \", _jsx(_components.code, {\n children: \"api_key\"\n }), \"; never echo it.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/artists\"\n }), \": inspect the caller's roster and choose the artist's account ID.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites\"\n }), \": inspect existing site records.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/sites\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"name\\\": \\\"Release experience\\\", \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\", \\\"releaseUrl\\\": \\\"https://open.spotify.com/track/TRACK_ID\\\" }\"\n }), \": register a site. Add \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" only for a selected authorized workspace. Read the returned \", _jsx(_components.code, {\n children: \"site.id\"\n }), \". Omit owner/account ID fields; ownership comes from authentication.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"configure\",\n children: \"Configure\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/fan-connection\"\n }), \" returns:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"siteId\\\": \\\"SITE_UUID\\\",\\n \\\"ownerId\\\": \\\"WORKSPACE_ACCOUNT_UUID\\\",\\n \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\",\\n \\\"config\\\": null,\\n \\\"connectUrl\\\": null\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Existing \", _jsx(_components.code, {\n children: \"config\"\n }), \" contains \", _jsx(_components.code, {\n children: \"site_id\"\n }), \", \", _jsx(_components.code, {\n children: \"return_url\"\n }), \", \", _jsx(_components.code, {\n children: \"marketing_text\"\n }), \", \", _jsx(_components.code, {\n children: \"enabled\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \". Update with \", _jsx(_components.code, {\n children: \"PUT /api/sites/{siteId}/fan-connection\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"returnUrl\\\": \\\"https://artist.example/release\\\",\\n \\\"marketingText\\\": \\\"I agree to receive release announcements and offers by email from Example Artist.\\\",\\n \\\"enabled\\\": true,\\n \\\"revision\\\": 0\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public \", _jsx(_components.code, {\n children: \"connectUrl\"\n }), \"; always use that returned URL.\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"400: invalid input or missing artist attribution.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"401/403: reconnect the customer or select an authorized workspace.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"402: no eligible paid subscription for the site's owning account.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"404: missing site or API not deployed; inspect the actual response.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"409: another configuration update won; reload and reconcile before retry.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"503: provider, billing or storage unavailable; surface the dependency.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Spotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing \", _jsx(_components.code, {\n children: \"POST /api/subscriptions/sessions\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{plan: \\\"starter\\\" | \\\"pro\\\", successUrl, cancelUrl?}\"\n }), \" and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"public-fan-journey\",\n children: \"Public fan journey\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{siteId}/spotify\"\n }), \" displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's \", _jsx(_components.code, {\n children: \"/api/sites/spotify/callback\"\n }), \"; Recoup then returns to the configured site URL with \", _jsx(_components.code, {\n children: \"recoup_spotify=connected\"\n }), \", \", _jsx(_components.code, {\n children: \"cancelled\"\n }), \" or \", _jsx(_components.code, {\n children: \"failed\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Only a successful provider exchange with \", _jsx(_components.code, {\n children: \"user-read-email\"\n }), \" and \", _jsx(_components.code, {\n children: \"user-read-private\"\n }), \" creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"read-fans\",\n children: \"Read fans\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/fans?offset=0&limit=50\"\n }), \" (private):\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"fans\\\": [],\\n \\\"total\\\": 0,\\n \\\"offset\\\": 0,\\n \\\"limit\\\": 50\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each fan has \", _jsx(_components.code, {\n children: \"id\"\n }), \", \", _jsx(_components.code, {\n children: \"site_id\"\n }), \", \", _jsx(_components.code, {\n children: \"spotify_id\"\n }), \", \", _jsx(_components.code, {\n children: \"display_name\"\n }), \", \", _jsx(_components.code, {\n children: \"email\"\n }), \", first/last connection timestamps and nested \", _jsx(_components.code, {\n children: \"site_fan_connections\"\n }), \" with \", _jsx(_components.code, {\n children: \"site_fan_permissions\"\n }), \" and \", _jsx(_components.code, {\n children: \"site_fan_marketing_consents\"\n }), \". Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Starter Checkout can return HTTP 400 \", _jsx(_components.code, {\n children: \"starter_unavailable\"\n }), \" when its price is not\\nconfigured. Explain the unavailable option and use a configured plan; do not retry\\nit as a transient provider failure.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"recoup-operator-setup\",\n children: \"Recoup operator setup\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Operators must apply \", _jsx(_components.code, {\n children: \"20260928010000_site_fan_connections.sql\"\n }), \", configure \", _jsx(_components.code, {\n children: \"SITES_SPOTIFY_CLIENT_ID\"\n }), \", register an HTTPS callback ending \", _jsx(_components.code, {\n children: \"/api/sites/spotify/callback\"\n }), \", set \", _jsx(_components.code, {\n children: \"SITES_FAN_SPOTIFY_REDIRECT_URI\"\n }), \". This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"activity-reporting\",\n children: \"Activity reporting\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/activity\"\n }), \" returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. \", _jsx(_components.code, {\n children: \"POST /api/sites/public/{siteId}/activity\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{id: EVENT_UUID, visitId: VISIT_UUID, event: \\\"visit\\\" | \\\"start\\\" | \\\"complete\\\" | \\\"replay\\\" | \\\"share\\\"}\"\n }), \". Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Recoup-hosted generated sites use the trusted host bridge: \", _jsx(_components.code, {\n children: \"window.recoup.track(event)\"\n }), \" reports approved events; \", _jsx(_components.code, {\n children: \"window.recoup.join()\"\n }), \" reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"playback-for-premium-and-free-listeners\",\n children: \"Playback for Premium and Free listeners\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The hosted player reads the connected Spotify profile's \", _jsx(_components.code, {\n children: \"product\"\n }), \" field. Premium listeners use the Spotify Web Playback SDK. Free (\", _jsx(_components.code, {\n children: \"free\"\n }), \" or \", _jsx(_components.code, {\n children: \"open\"\n }), \") listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{siteId}\"\n }), \" includes \", _jsx(_components.code, {\n children: \"playbackAudioUrl\"\n }), \", a fresh signed audio URL valid for one hour, or \", _jsx(_components.code, {\n children: \"null\"\n }), \" when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"File playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Connect Spotify fans to a site Configure paid fan connection from an artist agent and retrieve fans attributed to its site. Sites Sites Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: `https://api.recoupable.dev`. Private calls use `x-api-key: $RECOUP_API_KEY` (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key. ## Customer and site - `GET /api/accounts/id`: verify the current credential. - `POST /api/agents/signup` with `{ \"email\": \"customer@example.com\" }`: request email verification. - `POST /api/agents/verify` with `{ \"email\": \"customer@example.com\", \"code\": \"123456\" }`: receive `api_key`; never echo it. - `GET /api/artists`: inspect the caller's roster and choose the artist's account ID. - `GET /api/sites`: inspect existing site records. - `POST /api/sites` with `{ \"name\": \"Release experience\", \"artistId\": \"ARTIST_ACCOUNT_UUID\", \"releaseUrl\": \"https://open.spotify.com/track/TRACK_ID\" }`: register a site. Add `organizationId` only for a selected authorized workspace. Read the returned `site.id`. Omit owner/account ID fields; ownership comes from authentication. ## Configure `GET /api/sites/{siteId}/fan-connection` returns: Existing `config` contains `site_id`, `return_url`, `marketing_text`, `enabled` and `revision`. Update with `PUT /api/sites/{siteId}/fan-connection`: Use the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public `connectUrl`; always use that returned URL. - 400: invalid input or missing artist attribution. - 401/403: reconnect the customer or select an authorized workspace. - 402: no eligible paid subscription for the site's owning account. - 404: missing site or API not deployed; inspect the actual response. - 409: another configuration update won; reload and reconcile before retry. - 503: provider, billing or storage unavailable; surface the dependency. Spotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing `POST /api/subscriptions/sessions` accepts `{plan: \"starter\" | \"pro\", successUrl, cancelUrl?}` and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature. ## Public fan journey `GET /api/sites/public/{siteId}/spotify` displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's `/api/sites/spotify/callback`; Recoup then returns to the configured site URL with `recoup_spotify=connected`, `cancelled` or `failed`. Only a successful provider exchange with `user-read-email` and `user-read-private` creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site. ## Read fans `GET /api/sites/{siteId}/fans?offset=0&limit=50` (private): Each fan has `id`, `site_id`, `spotify_id`, `display_name`, `email`, first/last connection timestamps and nested `site_fan_connections` with `site_fan_permissions` and `site_fan_marketing_consents`. Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data. Starter Checkout can return HTTP 400 `starter_unavailable` when its price is not configured. Explain the unavailable option and use a configured plan; do not retry it as a transient provider failure. ## Recoup operator setup Operators must apply `20260928010000_site_fan_connections.sql`, configure `SITES_SPOTIFY_CLIENT_ID`, register an HTTPS callback ending `/api/sites/spotify/callback`, set `SITES_FAN_SPOTIFY_REDIRECT_URI`. This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate. ## Activity reporting `GET /api/sites/{siteId}/activity` returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. `POST /api/sites/public/{siteId}/activity` accepts `{id: EVENT_UUID, visitId: VISIT_UUID, event: \"visit\" | \"start\" | \"complete\" | \"replay\" | \"share\"}`. Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history. Recoup-hosted generated sites use the trusted host bridge: `window.recoup.track(event)` reports approved events; `window.recoup.join()` reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server. ## Playback for Premium and Free listeners The hosted player reads the connected Spotify profile's `product` field. Premium listeners use the Spotify Web Playback SDK. Free (`free` or `open`) listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording. `GET /api/sites/public/{siteId}` includes `playbackAudioUrl`, a fresh signed audio URL valid for one hour, or `null` when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans. File playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable. "},{"slug":"essentials/release-player","title":"One player for every release","description":"Create a listening page or embed Spotify and Apple Music playback on your artist website.","category":"Players","group":"Release players","source":"essentials/release-player.mdx","body":"Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.\n\n## Create and publish\n\nUse the [Recoup API](/api-reference/players/create) or the `create_release_player` MCP tool. Choose an artist you can access, name the player, and provide a `spotifyUrl`, an `appleUrl`, or both. Use `organizationId` to create it in your organization workspace.\n\nFor website embeds, add the exact website origins to `allowedOrigins`. An origin includes the scheme, hostname and any non-default port, such as `https://artist.example:8443`. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.\n\nExample create request:\n\n```json\n{\n \"artistId\": \"ARTIST_ACCOUNT_UUID\",\n \"organizationId\": \"ORGANIZATION_UUID\",\n \"name\": \"Release title\",\n \"spotifyUrl\": \"https://open.spotify.com/album/ALBUM_ID\",\n \"appleUrl\": \"https://music.apple.com/us/album/release/APPLE_ID\",\n \"allowedOrigins\": [\"https://artist.example\", \"https://www.artist.example\"]\n}\n```\n\nNew players start unpublished. Review the music links, then publish with `update_release_player`, passing `id`, the current `revision`, and `enabled: true`. Publishing requires an active paid Recoup workspace.\n\nUse the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.\n\nSee [update a release player](/api-reference/players/update) for the REST request and fields.\n\n## Share a listening page\n\nUse the returned `listenUrl` as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.\n\nTo track campaign traffic, add `source`, `medium`, `campaign`, and `content` query parameters. The listening page also accepts `utm_source`, `utm_medium`, `utm_campaign`, and `utm_content`. Use campaign labels, such as `instagram` and `release`; keep personal information out of links.\n\n## Embed on your website\n\nUse the returned `spotifyEmbedUrl` or `appleEmbedUrl` for each configured service. The `parent` parameter must match an approved website origin.\n\n```html\n\n```\n\nKeep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.\n\nFor Spotify Free handoffs, the embed sends a `recoup:open-dsp` message with `provider: \"spotify\"`. Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.\n\n## What fans can play\n\nSpotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.\n\nSpotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.\n\nApple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.\n\n## Optional uploaded audio for Spotify Free fans\n\nYou can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set `freePlayback: \"audio\"` and provide `audioUrl`. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.\n\nUpload an MP3 or WAV through `POST /api/sites/assets` in the same workspace, then use the returned `asset.url`. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.\n\nMCP arguments for `update_release_player`:\n\n```json\n{\n \"id\": \"PLAYER_UUID\",\n \"revision\": 1,\n \"freePlayback\": \"audio\",\n \"audioUrl\": \"WORKSPACE_UPLOADED_ASSET_URL\"\n}\n```\n\nFor REST, send `PATCH /api/players/PLAYER_UUID` with the same body except `id`; the player ID belongs in the URL.\n\nAudio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.\n\nTo restore the Spotify handoff, set `freePlayback: \"spotify\"`. You can also clear `audioUrl` by setting it to `null`.\n\n## Fan contacts belong to your workspace\n\nSpotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.\n\nIf that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.\n\n- Use `get_workspace_player_fans` or [read workspace player fans](/api-reference/players/workspace-fans) to list contacts and their artist relationships.\n- Use `get_release_player_fans` or [read artist player fans](/api-reference/players/fans) to list fan relationships across that artist's players in the workspace.\n\n`contact_id` identifies the workspace contact. Each artist relationship has its own `id`; activity records refer to that relationship as `fan_id`.\n\nSpotify sign-in does **not** grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.\n\n## Measure listening activity\n\nUse `get_release_player_activity` or [read listening activity](/api-reference/players/activity) for 30-day campaign totals and individual track, play, pause and skip events.\n\nThese reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are **not confirmed music-service stream counts** and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.\n\n## Check your fan journey\n\nBefore promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.\n","headings":[{"title":"Create and publish","id":"create-and-publish"},{"title":"Share a listening page","id":"share-a-listening-page"},{"title":"Embed on your website","id":"embed-on-your-website"},{"title":"What fans can play","id":"what-fans-can-play"},{"title":"Optional uploaded audio for Spotify Free fans","id":"optional-uploaded-audio-for-spotify-free-fans"},{"title":"Fan contacts belong to your workspace","id":"fan-contacts-belong-to-your-workspace"},{"title":"Measure listening activity","id":"measure-listening-activity"},{"title":"Check your fan journey","id":"check-your-fan-journey"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"create-and-publish\",\n children: \"Create and publish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the \", _jsx(_components.a, {\n href: \"/api-reference/players/create\",\n children: \"Recoup API\"\n }), \" or the \", _jsx(_components.code, {\n children: \"create_release_player\"\n }), \" MCP tool. Choose an artist you can access, name the player, and provide a \", _jsx(_components.code, {\n children: \"spotifyUrl\"\n }), \", an \", _jsx(_components.code, {\n children: \"appleUrl\"\n }), \", or both. Use \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" to create it in your organization workspace.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For website embeds, add the exact website origins to \", _jsx(_components.code, {\n children: \"allowedOrigins\"\n }), \". An origin includes the scheme, hostname and any non-default port, such as \", _jsx(_components.code, {\n children: \"https://artist.example:8443\"\n }), \". Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Example create request:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\",\\n \\\"organizationId\\\": \\\"ORGANIZATION_UUID\\\",\\n \\\"name\\\": \\\"Release title\\\",\\n \\\"spotifyUrl\\\": \\\"https://open.spotify.com/album/ALBUM_ID\\\",\\n \\\"appleUrl\\\": \\\"https://music.apple.com/us/album/release/APPLE_ID\\\",\\n \\\"allowedOrigins\\\": [\\\"https://artist.example\\\", \\\"https://www.artist.example\\\"]\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"New players start unpublished. Review the music links, then publish with \", _jsx(_components.code, {\n children: \"update_release_player\"\n }), \", passing \", _jsx(_components.code, {\n children: \"id\"\n }), \", the current \", _jsx(_components.code, {\n children: \"revision\"\n }), \", and \", _jsx(_components.code, {\n children: \"enabled: true\"\n }), \". Publishing requires an active paid Recoup workspace.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/players/update\",\n children: \"update a release player\"\n }), \" for the REST request and fields.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"share-a-listening-page\",\n children: \"Share a listening page\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the returned \", _jsx(_components.code, {\n children: \"listenUrl\"\n }), \" as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To track campaign traffic, add \", _jsx(_components.code, {\n children: \"source\"\n }), \", \", _jsx(_components.code, {\n children: \"medium\"\n }), \", \", _jsx(_components.code, {\n children: \"campaign\"\n }), \", and \", _jsx(_components.code, {\n children: \"content\"\n }), \" query parameters. The listening page also accepts \", _jsx(_components.code, {\n children: \"utm_source\"\n }), \", \", _jsx(_components.code, {\n children: \"utm_medium\"\n }), \", \", _jsx(_components.code, {\n children: \"utm_campaign\"\n }), \", and \", _jsx(_components.code, {\n children: \"utm_content\"\n }), \". Use campaign labels, such as \", _jsx(_components.code, {\n children: \"instagram\"\n }), \" and \", _jsx(_components.code, {\n children: \"release\"\n }), \"; keep personal information out of links.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"embed-on-your-website\",\n children: \"Embed on your website\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the returned \", _jsx(_components.code, {\n children: \"spotifyEmbedUrl\"\n }), \" or \", _jsx(_components.code, {\n children: \"appleEmbedUrl\"\n }), \" for each configured service. The \", _jsx(_components.code, {\n children: \"parent\"\n }), \" parameter must match an approved website origin.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-html\",\n children: \"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For Spotify Free handoffs, the embed sends a \", _jsx(_components.code, {\n children: \"recoup:open-dsp\"\n }), \" message with \", _jsx(_components.code, {\n children: \"provider: \\\"spotify\\\"\"\n }), \". Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-fans-can-play\",\n children: \"What fans can play\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"optional-uploaded-audio-for-spotify-free-fans\",\n children: \"Optional uploaded audio for Spotify Free fans\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set \", _jsx(_components.code, {\n children: \"freePlayback: \\\"audio\\\"\"\n }), \" and provide \", _jsx(_components.code, {\n children: \"audioUrl\"\n }), \". This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Upload an MP3 or WAV through \", _jsx(_components.code, {\n children: \"POST /api/sites/assets\"\n }), \" in the same workspace, then use the returned \", _jsx(_components.code, {\n children: \"asset.url\"\n }), \". The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP arguments for \", _jsx(_components.code, {\n children: \"update_release_player\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"id\\\": \\\"PLAYER_UUID\\\",\\n \\\"revision\\\": 1,\\n \\\"freePlayback\\\": \\\"audio\\\",\\n \\\"audioUrl\\\": \\\"WORKSPACE_UPLOADED_ASSET_URL\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For REST, send \", _jsx(_components.code, {\n children: \"PATCH /api/players/PLAYER_UUID\"\n }), \" with the same body except \", _jsx(_components.code, {\n children: \"id\"\n }), \"; the player ID belongs in the URL.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To restore the Spotify handoff, set \", _jsx(_components.code, {\n children: \"freePlayback: \\\"spotify\\\"\"\n }), \". You can also clear \", _jsx(_components.code, {\n children: \"audioUrl\"\n }), \" by setting it to \", _jsx(_components.code, {\n children: \"null\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"fan-contacts-belong-to-your-workspace\",\n children: \"Fan contacts belong to your workspace\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_workspace_player_fans\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/workspace-fans\",\n children: \"read workspace player fans\"\n }), \" to list contacts and their artist relationships.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_release_player_fans\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/fans\",\n children: \"read artist player fans\"\n }), \" to list fan relationships across that artist's players in the workspace.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"contact_id\"\n }), \" identifies the workspace contact. Each artist relationship has its own \", _jsx(_components.code, {\n children: \"id\"\n }), \"; activity records refer to that relationship as \", _jsx(_components.code, {\n children: \"fan_id\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Spotify sign-in does \", _jsx(_components.strong, {\n children: \"not\"\n }), \" grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"measure-listening-activity\",\n children: \"Measure listening activity\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_release_player_activity\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/activity\",\n children: \"read listening activity\"\n }), \" for 30-day campaign totals and individual track, play, pause and skip events.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are \", _jsx(_components.strong, {\n children: \"not confirmed music-service stream counts\"\n }), \" and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"check-your-fan-journey\",\n children: \"Check your fan journey\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"One player for every release Create a listening page or embed Spotify and Apple Music playback on your artist website. Players Release players Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting. ## Create and publish Use the [Recoup API](/api-reference/players/create) or the `create_release_player` MCP tool. Choose an artist you can access, name the player, and provide a `spotifyUrl`, an `appleUrl`, or both. Use `organizationId` to create it in your organization workspace. For website embeds, add the exact website origins to `allowedOrigins`. An origin includes the scheme, hostname and any non-default port, such as `https://artist.example:8443`. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page. Example create request: New players start unpublished. Review the music links, then publish with `update_release_player`, passing `id`, the current `revision`, and `enabled: true`. Publishing requires an active paid Recoup workspace. Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect. See [update a release player](/api-reference/players/update) for the REST request and fields. ## Share a listening page Use the returned `listenUrl` as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player. To track campaign traffic, add `source`, `medium`, `campaign`, and `content` query parameters. The listening page also accepts `utm_source`, `utm_medium`, `utm_campaign`, and `utm_content`. Use campaign labels, such as `instagram` and `release`; keep personal information out of links. ## Embed on your website Use the returned `spotifyEmbedUrl` or `appleEmbedUrl` for each configured service. The `parent` parameter must match an approved website origin. Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable. For Spotify Free handoffs, the embed sends a `recoup:open-dsp` message with `provider: \"spotify\"`. Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message. ## What fans can play Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify. Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free. Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup. ## Optional uploaded audio for Spotify Free fans You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set `freePlayback: \"audio\"` and provide `audioUrl`. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify. Upload an MP3 or WAV through `POST /api/sites/assets` in the same workspace, then use the returned `asset.url`. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback. MCP arguments for `update_release_player`: For REST, send `PATCH /api/players/PLAYER_UUID` with the same body except `id`; the player ID belongs in the URL. Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link. To restore the Spotify handoff, set `freePlayback: \"spotify\"`. You can also clear `audioUrl` by setting it to `null`. ## Fan contacts belong to your workspace Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace. If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans. - Use `get_workspace_player_fans` or [read workspace player fans](/api-reference/players/workspace-fans) to list contacts and their artist relationships. - Use `get_release_player_fans` or [read artist player fans](/api-reference/players/fans) to list fan relationships across that artist's players in the workspace. `contact_id` identifies the workspace contact. Each artist relationship has its own `id`; activity records refer to that relationship as `fan_id`. Spotify sign-in does **not** grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts. ## Measure listening activity Use `get_release_player_activity` or [read listening activity](/api-reference/players/activity) for 30-day campaign totals and individual track, play, pause and skip events. These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are **not confirmed music-service stream counts** and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance. ## Check your fan journey Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace. "},{"slug":"api-reference/players/create","title":"Create a release player","description":"Create a release player","category":"Players","group":"Release players","source":"api-reference/players/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/players","spec":"players.json"},"searchText":"Create a release player Create a release player Players Release players POST /api/players "},{"slug":"api-reference/players/list","title":"List release players","description":"List release players","category":"Players","group":"Release players","source":"api-reference/players/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players","spec":"players.json"},"searchText":"List release players List release players Players Release players GET /api/players "},{"slug":"api-reference/players/get","title":"Read a release player","description":"Read a release player","category":"Players","group":"Release players","source":"api-reference/players/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}","spec":"players.json"},"searchText":"Read a release player Read a release player Players Release players GET /api/players/{id} "},{"slug":"api-reference/players/update","title":"Update a release player","description":"Update a release player","category":"Players","group":"Release players","source":"api-reference/players/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/players/{id}","spec":"players.json"},"searchText":"Update a release player Update a release player Players Release players PATCH /api/players/{id} "},{"slug":"api-reference/players/activity","title":"Read listening activity","description":"Read player listening activity","category":"Players","group":"Release players","source":"api-reference/players/activity.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}/activity","spec":"players.json"},"searchText":"Read listening activity Read player listening activity Players Release players GET /api/players/{id}/activity "},{"slug":"api-reference/players/fans","title":"Read artist player fans","description":"Read artist player fans","category":"Players","group":"Release players","source":"api-reference/players/fans.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}/fans","spec":"players.json"},"searchText":"Read artist player fans Read artist player fans Players Release players GET /api/players/{id}/fans "},{"slug":"api-reference/players/workspace-fans","title":"Read workspace player fans","description":"Read workspace player fans","category":"Players","group":"Release players","source":"api-reference/players/workspace-fans.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/fans","spec":"players.json"},"searchText":"Read workspace player fans Read workspace player fans Players Release players GET /api/players/fans "},{"slug":"api-reference/complete/content/post-content-packs","title":"POST /api/content/packs","description":"Release rollout pending; discover current host capabilities before execution. Prepare a resumable pack brief. No artist profile or GitHub repository required; no paid generation.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs","spec":"content.json"},"searchText":"POST /api/content/packs Release rollout pending; discover current host capabilities before execution. Prepare a resumable pack brief. No artist profile or GitHub repository required; no paid generation."},{"slug":"api-reference/complete/content/get-content-packs-id","title":"GET /api/content/packs/{id}","description":"Release rollout pending; discover current host capabilities before execution. Read current owned job, assets, gaps and next action.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"GET","path":"/api/content/packs/{id}","spec":"content.json"},"searchText":"GET /api/content/packs/{id} Release rollout pending; discover current host capabilities before execution. Read current owned job, assets, gaps and next action."},{"slug":"api-reference/complete/content/patch-content-packs-id","title":"PATCH /api/content/packs/{id}","description":"Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"PATCH","path":"/api/content/packs/{id}","spec":"content.json"},"searchText":"PATCH /api/content/packs/{id} Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes."},{"slug":"api-reference/complete/content/post-content-packs-id-estimate","title":"POST /api/content/packs/{id}/estimate","description":"Release rollout pending; discover current host capabilities before execution. Quote complete scope at existing house image/video rates. Caption, inspection and composition are included at no additional customer charge.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/estimate","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/estimate Release rollout pending; discover current host capabilities before execution. Quote complete scope at existing house image/video rates. Caption, inspection and composition are included at no additional customer charge."},{"slug":"api-reference/complete/content/post-content-packs-id-generate","title":"POST /api/content/packs/{id}/generate","description":"Release rollout pending; discover current host capabilities before execution. Approve the current quote and budget ceiling. Start or resume the same job without duplicate submission.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/generate","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/generate Release rollout pending; discover current host capabilities before execution. Approve the current quote and budget ceiling. Start or resume the same job without duplicate submission."},{"slug":"api-reference/complete/content/post-content-packs-id-retry","title":"POST /api/content/packs/{id}/retry","description":"Release rollout pending; discover current host capabilities before execution. Retry only the selected failed asset within approved scope and ceiling; retain successful work.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/retry","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/retry Release rollout pending; discover current host capabilities before execution. Retry only the selected failed asset within approved scope and ceiling; retain successful work."},{"slug":"api-reference/complete/content/post-content-packs-assets","title":"POST /api/content/packs/assets","description":"Release rollout pending; discover current host capabilities before execution. Upload explicitly selected audio or reference artwork to owned private storage; return a temporary locator.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/assets","spec":"content.json"},"searchText":"POST /api/content/packs/assets Release rollout pending; discover current host capabilities before execution. Upload explicitly selected audio or reference artwork to owned private storage; return a temporary locator."},{"slug":"api-reference/complete/content/get-content-packs-id-export","title":"GET /api/content/packs/{id}/export","description":"Release rollout pending; discover current host capabilities before execution. Retrieve an authenticated JSON manifest with captions, gaps and refreshed signed file URLs. Does not publish.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"GET","path":"/api/content/packs/{id}/export","spec":"content.json"},"searchText":"GET /api/content/packs/{id}/export Release rollout pending; discover current host capabilities before execution. Retrieve an authenticated JSON manifest with captions, gaps and refreshed signed file URLs. Does not publish."},{"slug":"api-reference/complete/players/get-players-public-id","title":"Read public player metadata without creating a session","description":"Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"GET","path":"/api/players/public/{id}","spec":"players.json"},"searchText":"GET /api/players/public/{id} Read public player metadata without creating a session Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials."},{"slug":"api-reference/complete/players/post-players-events","title":"Record reported listening","description":"Internal trusted Recoup player transport. Requires its Origin plus signed flow; browser-facing same-origin app proxy forwards to API. Provider and fan attribution come from the stored session. Event UUID makes retries idempotent, listenedMs is capped at 30 seconds and checked against elapsed server time. Recording failures do not stop music.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/events","spec":"players.json"},"searchText":"POST /api/players/events Record reported listening Internal trusted Recoup player transport. Requires its Origin plus signed flow; browser-facing same-origin app proxy forwards to API. Provider and fan attribution come from the stored session. Event UUID makes retries idempotent, listenedMs is capped at 30 seconds and checked against elapsed server time. Recording failures do not stop music."},{"slug":"api-reference/complete/players/post-players-spotify-session","title":"Exchange player Spotify authorization","description":"Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/spotify/session","spec":"players.json"},"searchText":"POST /api/players/spotify/session Exchange player Spotify authorization Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent."},{"slug":"api-reference/complete/players/post-players-public-id-session","title":"Acquire or resume a registered player session","description":"Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/public/{id}/session","spec":"players.json"},"searchText":"POST /api/players/public/{id}/session Acquire or resume a registered player session Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials."}] \ No newline at end of file diff --git a/content/docs/source/api-reference/openapi/research.json b/content/docs/source/api-reference/openapi/research.json index 001fcef..184bde1 100644 --- a/content/docs/source/api-reference/openapi/research.json +++ b/content/docs/source/api-reference/openapi/research.json @@ -509,12 +509,12 @@ "/api/chats/{id}/messages/trailing": { "delete": { "operationId": "deleteChatsByIdMessagesTrailing", - "description": "Delete all messages in a chat from a given message onward (inclusive), identified by `from_message_id`.", + "description": "Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override.\n\nThe caller must ensure there are no concurrent or outstanding message writers, including queued persistence and other edits. Any observed nonnull workflow slot returns `409` without cancelling work or clearing the slot. A null slot or a successful Stop does not prove that outstanding writers have finished. Concurrent edit/resend is unsupported.\n\nThe delete is scoped to this chat and includes the anchor, messages with a later timestamp, and messages at the same timestamp whose UUID sorts at or after the anchor UUID. Earlier UUIDs at the same timestamp survive; timestamp precision is preserved.\n\n`200` means the delete statement succeeded, possibly affecting zero rows. It does not report a deleted-row count or guarantee durable absence or prevent later message recreation. A transport failure can leave the commit outcome unknown: refresh authoritative history before deciding what to do next, rather than blindly resending a turn.", "parameters": [ { "name": "id", "in": "path", - "description": "The unique identifier (UUID) of the chat room.", + "description": "UUID of the owned Workflow chat.", "required": true, "schema": { "type": "string", @@ -524,27 +524,46 @@ { "name": "from_message_id", "in": "query", - "description": "The message UUID from which trailing messages should be deleted (inclusive).", + "description": "UUID of the persisted message in this Workflow chat to use as the inclusive created_at, id boundary. Any persisted message role is eligible.", "required": true, "schema": { "type": "string", "format": "uuid" } + }, + { + "name": "account_id", + "in": "query", + "required": false, + "description": "Optional effective account override, accepted only when current authentication authorizes access to that account. It does not grant access by itself.", + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Trailing messages deleted successfully", + "description": "Delete statement succeeded, including a possible zero-row result. No deleted count, durable-absence or concurrent edit/resend guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTrailingChatMessagesResponse" + }, + "examples": { + "statementSuccess": { + "value": { + "status": "success", + "chat_id": "11111111-1111-4111-8111-111111111111", + "from_message_id": "22222222-2222-4222-8222-222222222222" + } + } } } } }, "400": { - "description": "Bad request - invalid or missing query/path parameters or message does not belong to chat", + "description": "Invalid chat UUID or missing/invalid from_message_id query UUID.", "content": { "application/json": { "schema": { @@ -554,17 +573,17 @@ } }, "401": { - "description": "Unauthorized - invalid or missing credentials", + "description": "Missing, conflicting or invalid credentials. Authentication errors retain the error or message envelope returned by the selected authentication path.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse" + "$ref": "#/components/schemas/DeleteTrailingChatAuthenticationErrorResponse" } } } }, "403": { - "description": "Forbidden - access denied to this chat", + "description": "Access denied to the requested account_id override or the effective account does not own the Workflow chat session.", "content": { "application/json": { "schema": { @@ -574,7 +593,7 @@ } }, "404": { - "description": "Not found - chat or message does not exist", + "description": "Workflow chat/session is absent, or the anchor is absent from this chat (including a foreign-chat anchor).", "content": { "application/json": { "schema": { @@ -584,7 +603,7 @@ } }, "500": { - "description": "Server error - failed to delete trailing messages", + "description": "Authentication/storage failure, chat/session/anchor read failure, invalid stored boundary, or delete failure. A transport failure may leave the commit outcome unknown; refresh history before further action.", "content": { "application/json": { "schema": { @@ -592,8 +611,34 @@ } } } + }, + "409": { + "description": "An occupied workflow slot was observed. Pending reservations and other nonnull values are rejected without provider calls, cancellation or slot mutation. This check is not a concurrency lock.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse" + }, + "examples": { + "occupiedSlot": { + "value": { + "status": "error", + "error": "Chat has an active workflow reservation; retry after it clears" + } + } + } + } + } } - } + }, + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ] } }, "/api/chats/compact": { @@ -6825,6 +6870,52 @@ } }, "additionalProperties": true + }, + "DeleteTrailingChatAuthenticationErrorResponse": { + "anyOf": [ + { + "type": "object", + "properties": { + "status": { + "description": "Always `error`.", + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "description": "Human-readable error message or documented error code.", + "type": "string" + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": {} + }, + { + "type": "object", + "properties": { + "status": { + "description": "Always `error`.", + "type": "string", + "enum": [ + "error" + ] + }, + "message": { + "description": "Human-readable authentication error message.", + "type": "string" + } + }, + "required": [ + "status", + "message" + ], + "additionalProperties": {} + } + ] } }, "responses": { diff --git a/content/docs/source/llms-full.txt b/content/docs/source/llms-full.txt index d46b2e9..b066a0e 100644 --- a/content/docs/source/llms-full.txt +++ b/content/docs/source/llms-full.txt @@ -7510,7 +7510,7 @@ The supplied specification does not declare an OpenAPI security object for this Source: https://docs.recoupable.dev/api-reference/chat/messages-trailing-delete -Delete all messages in a chat from a given message onward (inclusive), identified by `from_message_id`. +Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override. ## DELETE /api/chats/{id}/messages/trailing @@ -7518,7 +7518,7 @@ Full OpenAPI specification: https://docs.recoupable.dev/spec/research.json ## Authentication -The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it. +This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification. [Authentication guide](https://docs.recoupable.dev/authentication) @@ -7544,12 +7544,12 @@ The supplied specification does not declare an OpenAPI security object for this "/api/chats/{id}/messages/trailing": { "delete": { "operationId": "deleteChatsByIdMessagesTrailing", - "description": "Delete all messages in a chat from a given message onward (inclusive), identified by `from_message_id`.", + "description": "Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override.\n\nThe caller must ensure there are no concurrent or outstanding message writers, including queued persistence and other edits. Any observed nonnull workflow slot returns `409` without cancelling work or clearing the slot. A null slot or a successful Stop does not prove that outstanding writers have finished. Concurrent edit/resend is unsupported.\n\nThe delete is scoped to this chat and includes the anchor, messages with a later timestamp, and messages at the same timestamp whose UUID sorts at or after the anchor UUID. Earlier UUIDs at the same timestamp survive; timestamp precision is preserved.\n\n`200` means the delete statement succeeded, possibly affecting zero rows. It does not report a deleted-row count or guarantee durable absence or prevent later message recreation. A transport failure can leave the commit outcome unknown: refresh authoritative history before deciding what to do next, rather than blindly resending a turn.", "parameters": [ { "name": "id", "in": "path", - "description": "The unique identifier (UUID) of the chat room.", + "description": "UUID of the owned Workflow chat.", "required": true, "schema": { "type": "string", @@ -7559,27 +7559,46 @@ The supplied specification does not declare an OpenAPI security object for this { "name": "from_message_id", "in": "query", - "description": "The message UUID from which trailing messages should be deleted (inclusive).", + "description": "UUID of the persisted message in this Workflow chat to use as the inclusive created_at, id boundary. Any persisted message role is eligible.", "required": true, "schema": { "type": "string", "format": "uuid" } + }, + { + "name": "account_id", + "in": "query", + "required": false, + "description": "Optional effective account override, accepted only when current authentication authorizes access to that account. It does not grant access by itself.", + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Trailing messages deleted successfully", + "description": "Delete statement succeeded, including a possible zero-row result. No deleted count, durable-absence or concurrent edit/resend guarantee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTrailingChatMessagesResponse" + }, + "examples": { + "statementSuccess": { + "value": { + "status": "success", + "chat_id": "11111111-1111-4111-8111-111111111111", + "from_message_id": "22222222-2222-4222-8222-222222222222" + } + } } } } }, "400": { - "description": "Bad request - invalid or missing query/path parameters or message does not belong to chat", + "description": "Invalid chat UUID or missing/invalid from_message_id query UUID.", "content": { "application/json": { "schema": { @@ -7589,17 +7608,17 @@ The supplied specification does not declare an OpenAPI security object for this } }, "401": { - "description": "Unauthorized - invalid or missing credentials", + "description": "Missing, conflicting or invalid credentials. Authentication errors retain the error or message envelope returned by the selected authentication path.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse" + "$ref": "#/components/schemas/DeleteTrailingChatAuthenticationErrorResponse" } } } }, "403": { - "description": "Forbidden - access denied to this chat", + "description": "Access denied to the requested account_id override or the effective account does not own the Workflow chat session.", "content": { "application/json": { "schema": { @@ -7609,7 +7628,7 @@ The supplied specification does not declare an OpenAPI security object for this } }, "404": { - "description": "Not found - chat or message does not exist", + "description": "Workflow chat/session is absent, or the anchor is absent from this chat (including a foreign-chat anchor).", "content": { "application/json": { "schema": { @@ -7618,8 +7637,26 @@ The supplied specification does not declare an OpenAPI security object for this } } }, + "409": { + "description": "An occupied workflow slot was observed. Pending reservations and other nonnull values are rejected without provider calls, cancellation or slot mutation. This check is not a concurrency lock.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse" + }, + "examples": { + "occupiedSlot": { + "value": { + "status": "error", + "error": "Chat has an active workflow reservation; retry after it clears" + } + } + } + } + } + }, "500": { - "description": "Server error - failed to delete trailing messages", + "description": "Authentication/storage failure, chat/session/anchor read failure, invalid stored boundary, or delete failure. A transport failure may leave the commit outcome unknown; refresh history before further action.", "content": { "application/json": { "schema": { @@ -7628,7 +7665,15 @@ The supplied specification does not declare an OpenAPI security object for this } } } - } + }, + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ] } } }, @@ -7688,6 +7733,64 @@ The supplied specification does not declare an OpenAPI security object for this "description": "List of missing or invalid parameter fields (when validation fails)." } } + }, + "DeleteTrailingChatAuthenticationErrorResponse": { + "anyOf": [ + { + "type": "object", + "properties": { + "status": { + "description": "Always `error`.", + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "description": "Human-readable error message or documented error code.", + "type": "string" + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": {} + }, + { + "type": "object", + "properties": { + "status": { + "description": "Always `error`.", + "type": "string", + "enum": [ + "error" + ] + }, + "message": { + "description": "Human-readable authentication error message.", + "type": "string" + } + }, + "required": [ + "status", + "message" + ], + "additionalProperties": {} + } + ] + } + }, + "securitySchemes": { + "apiKeyAuth": { + "type": "apiKey", + "in": "header", + "name": "x-api-key", + "description": "Your Recoup API key. [Learn more](https://docs.recoupable.dev/quickstart#api-keys)." + }, + "bearerAuth": { + "type": "http", + "scheme": "bearer" } } } diff --git a/scripts/build_published_docs_record.py b/scripts/build_published_docs_record.py index d8f7395..790136a 100644 --- a/scripts/build_published_docs_record.py +++ b/scripts/build_published_docs_record.py @@ -135,4 +135,12 @@ def build_published_docs_record(specs, source, root, schema_hash, response_schem for name, method, path in [('start', 'post', '/api/chat'), ('resume', 'get', '/api/chat/{chatId}/stream')] } + trailing = research['paths']['/api/chats/{id}/messages/trailing']['delete'] + record['chatTrailingDelete'] = { + 'method': 'DELETE', 'path': '/api/chats/{id}/messages/trailing', + 'description': trailing['description'], 'parameters': trailing['parameters'], + 'security': trailing['security'], + 'responseDescriptions': {status: response['description'] + for status, response in trailing['responses'].items()}, + } return record diff --git a/scripts/build_response_contracts.py b/scripts/build_response_contracts.py index 45739fc..c59ff4b 100644 --- a/scripts/build_response_contracts.py +++ b/scripts/build_response_contracts.py @@ -6,6 +6,7 @@ SCHEMA_TARGETS = [ + ('research.json', 'DeleteTrailingChatAuthenticationErrorResponse', 'AuthenticationErrorResponse'), ('releases.json', 'ArtistPublicProfileErrorResponse', 'ErrorResponse'), ('releases.json', 'TaskAuthenticationErrorResponse', 'AuthenticationErrorResponse'), ('releases.json', 'TaskFailureErrorResponse', 'ErrorResponse'), @@ -22,6 +23,10 @@ ('releases.json', 'GET', '/api/tasks', 500), ('releases.json', 'POST', '/api/tasks', 500), ] +TRAILING_DELETE_TARGETS = [ + ('research.json', 'DELETE', '/api/chats/{id}/messages/trailing', status) + for status in (200, 400, 401, 403, 404, 409, 500) +] RESPONSE_TARGETS = [ ('releases.json', 'GET', '/api/artists/{id}/profile', 404), ('projects.json', 'GET', '/api/projects/{projectId}', 401), @@ -44,7 +49,7 @@ ('releases.json', 'POST', '/api/tasks', 401), ('releases.json', 'PATCH', '/api/tasks', 401), ('releases.json', 'DELETE', '/api/tasks', 401), -] + TASK_FAILURE_TARGETS +] + TASK_FAILURE_TARGETS + TRAILING_DELETE_TARGETS def build_response_contracts(specs, source, api, check=False): @@ -89,7 +94,8 @@ def build_response_contracts(specs, source, api, check=False): 'mediaType': 'application/json', 'schema': resolve_response_schema(response['content']['application/json']['schema'], document), } - if ((name, method, path, status) in TASK_FAILURE_TARGETS + if ((name, method, path, status) in TRAILING_DELETE_TARGETS + or (name, method, path, status) in TASK_FAILURE_TARGETS or (path, status) == ('/api/chat/{chatId}/stop', 503)): record['examples'] = { key: value['value'] diff --git a/scripts/test_chat_trailing_contracts.py b/scripts/test_chat_trailing_contracts.py new file mode 100644 index 0000000..82824ab --- /dev/null +++ b/scripts/test_chat_trailing_contracts.py @@ -0,0 +1,38 @@ +"""Freeze the bounded trailing-delete reference without claiming writer serialization.""" +import json +import subprocess +from response_contract_test_case import ResponseContractTestCase + + +class ChatTrailingContractsTest(ResponseContractTestCase): + def test_status_schemas_and_authored_operation_survive_export(self): + record = json.loads((self.marketing / 'content/docs/contracts/example-cases.json').read_text()) + operation = record['chatTrailingDelete'] + parameters = {p['name']: p for p in operation['parameters']} + self.assertEqual(parameters['from_message_id']['in'], 'query') + self.assertTrue(parameters['from_message_id']['required']) + self.assertFalse(parameters['account_id']['required']) + self.assertEqual(operation['security'], [{'apiKeyAuth': []}, {'bearerAuth': []}]) + responses = {r['status']: r for r in record['responseSchemas'] if r['path'] == operation['path']} + self.assertEqual(set(responses), {200, 400, 401, 403, 404, 409, 500}) + self.assertEqual(responses[200]['schema']['required'], ['status', 'chat_id', 'from_message_id']) + self.assertIn('anyOf', responses[401]['schema']) + self.assertEqual(responses[409]['examples']['occupiedSlot']['error'], + 'Chat has an active workflow reservation; retry after it clears') + self.assertIn('possibly affecting zero rows', operation['description']) + self.assertIn('Concurrent edit/resend is unsupported', operation['description']) + + def test_export_reads_authored_narrative_and_examples(self): + path = self.marketing / 'content/docs/source/api-reference/openapi/research.json' + spec = json.loads(path.read_text()) + operation = spec['paths']['/api/chats/{id}/messages/trailing']['delete'] + operation['description'] = 'Changed bounded operation description' + operation['responses']['409']['description'] = 'Changed conflict description' + operation['responses']['409']['content']['application/json']['examples']['occupiedSlot']['value']['error'] = 'Changed example' + path.write_text(json.dumps(spec, indent=2) + '\n') + subprocess.run(self.command, check=True, capture_output=True, text=True) + record = json.loads((self.marketing / 'content/docs/contracts/example-cases.json').read_text()) + self.assertEqual(record['chatTrailingDelete']['description'], operation['description']) + self.assertEqual(record['chatTrailingDelete']['responseDescriptions']['409'], 'Changed conflict description') + response = next(r for r in record['responseSchemas'] if r['path'] == '/api/chats/{id}/messages/trailing' and r['status'] == 409) + self.assertEqual(response['examples']['occupiedSlot']['error'], 'Changed example') From 6e1c718b3298472872578e3c47e4d82060bb3687 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Sun, 25 Oct 2026 17:13:00 -0500 Subject: [PATCH 2/2] KISS: trailing-delete description in three sentences Review on #5: operation descriptions stay at 2-3 sentences (4 max). The 13-sentence description becomes three; parameters, security and per-status responses keep the detail. The producer test now enforces the limit. Regenerated example-cases.json, the research.json inventory hash, manifest and llms-full.txt. The matching API fixture is api#1160; the inventory re-pins to its merge commit once it lands. Co-Authored-By: Claude Opus 5.5 --- content/docs/contracts/example-cases.json | 4 ++-- content/docs/contracts/operation-inventory.json | 2 +- content/docs/manifest.json | 2 +- content/docs/source/api-reference/openapi/research.json | 2 +- content/docs/source/llms-full.txt | 4 ++-- scripts/test_chat_trailing_contracts.py | 3 +++ 6 files changed, 10 insertions(+), 7 deletions(-) diff --git a/content/docs/contracts/example-cases.json b/content/docs/contracts/example-cases.json index 2d32d30..3e54d94 100644 --- a/content/docs/contracts/example-cases.json +++ b/content/docs/contracts/example-cases.json @@ -1232,7 +1232,7 @@ "sourceHashes": { "content/docs/source/api-reference/openapi/accounts.json": "1a5a04f9ec358a15b8339b7029c9fed5fe69c6f042c8b03b6b4f03f3aafdeeed", "content/docs/source/api-reference/openapi/content.json": "a59fa965788414731d19e031ec4b44f4a83319bdc651cb0aa49fba5a534317b0", - "content/docs/source/api-reference/openapi/research.json": "19100841a55ed3a793ce4ebc04038916f431150c529d54d38ddb1958484fbfdd", + "content/docs/source/api-reference/openapi/research.json": "6559809afceb26786f697b53f6d92b09d55eecd5a592edad9a1da32ba595507d", "content/docs/source/api-reference/openapi/releases.json": "7bfbdee327e8b3e27ba39cea3fcfe1fe930997d2ea05cb19a707f926ae3bdba2", "content/docs/source/api-reference/openapi/social.json": "5bd167a78cf6a17c46724486e2921882be20969ea32f3c0297f5b7e7ba9a30aa", "content/docs/source/api-reference/openapi/context.json": "2d28305aa357b3771a12bc1fbc26df78e2b9bbacd459642e31b1b1e13a314875", @@ -4372,7 +4372,7 @@ "chatTrailingDelete": { "method": "DELETE", "path": "/api/chats/{id}/messages/trailing", - "description": "Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override.\n\nThe caller must ensure there are no concurrent or outstanding message writers, including queued persistence and other edits. Any observed nonnull workflow slot returns `409` without cancelling work or clearing the slot. A null slot or a successful Stop does not prove that outstanding writers have finished. Concurrent edit/resend is unsupported.\n\nThe delete is scoped to this chat and includes the anchor, messages with a later timestamp, and messages at the same timestamp whose UUID sorts at or after the anchor UUID. Earlier UUIDs at the same timestamp survive; timestamp precision is preserved.\n\n`200` means the delete statement succeeded, possibly affecting zero rows. It does not report a deleted-row count or guarantee durable absence or prevent later message recreation. A transport failure can leave the commit outcome unknown: refresh authoritative history before deciding what to do next, rather than blindly resending a turn.", + "description": "Delete a message in a Workflow chat and every message after it, ordered by `created_at` then `id`. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns `409`. `200` means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending.", "parameters": [ { "name": "id", diff --git a/content/docs/contracts/operation-inventory.json b/content/docs/contracts/operation-inventory.json index bd95527..f6cdd05 100644 --- a/content/docs/contracts/operation-inventory.json +++ b/content/docs/contracts/operation-inventory.json @@ -3750,7 +3750,7 @@ "content/docs/source/api-reference/openapi/players.json": "4a4c90583fe1de6487444581b293a32b1cc04622fc929965ab90f365feb8bc94", "content/docs/source/api-reference/openapi/projects.json": "b059cf8baa83a7f73a3c15db19f54fa56e46a3840e91bd42979b83550f543ace", "content/docs/source/api-reference/openapi/releases.json": "7bfbdee327e8b3e27ba39cea3fcfe1fe930997d2ea05cb19a707f926ae3bdba2", - "content/docs/source/api-reference/openapi/research.json": "19100841a55ed3a793ce4ebc04038916f431150c529d54d38ddb1958484fbfdd", + "content/docs/source/api-reference/openapi/research.json": "6559809afceb26786f697b53f6d92b09d55eecd5a592edad9a1da32ba595507d", "content/docs/source/api-reference/openapi/sandbox.json": "c61a2bb965b9c9a1eade2e226fdc8af0cb1aa2213f23236d8607d13b65dbec15", "content/docs/source/api-reference/openapi/sessions.json": "85af56cc150374b28c25541c45db15849c71fdeb6288cf90dc2beb08f494e83e", "content/docs/source/api-reference/openapi/social.json": "5bd167a78cf6a17c46724486e2921882be20969ea32f3c0297f5b7e7ba9a30aa", diff --git a/content/docs/manifest.json b/content/docs/manifest.json index 8278879..d2fa5b0 100644 --- a/content/docs/manifest.json +++ b/content/docs/manifest.json @@ -1 +1 @@ -[{"slug":"","title":"Recoup API Documentation","description":"Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints.","category":"Quickstart","group":"Getting started","source":"index.mdx","body":"These guides cover the authenticated music-platform API. For anonymous search,\nreading, and website tools, use the separate [public website API](/public-website-api)\nand its [OpenAPI specification](https://recoupable.dev/openapi.json).\n\n## Connect your account\n\nFor an AI host, start with [MCP OAuth](/mcp-oauth): sign in to your real account,\napprove the intended scope and verify access with a read. For REST integrations,\ncreate an API key in your [account settings](https://chat.recoupable.dev/keys), or\nfollow the [verified email/PIN flow](/agents). Keep credentials in a secret facility.\nAn empty roster can be valid; do not create a disposable account to recover access.\n\n## What is Recoup?\n\nRecoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.\n\nThis is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.\n\n## Platform base URL\n\nPlatform API requests should be made to:\n\n```bash\nhttps://api.recoupable.dev/api\n```\n\n## Authentication\n\nMost API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key.\n\n1. Navigate to the [API Keys Management Page](https://chat.recoupable.dev/keys)\n2. Sign in with your account\n3. Create a new API key and copy it immediately (it's only shown once)\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/artists?accountId=YOUR_ACCOUNT_ID\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n\nKeep your API key secure. Do not share it publicly or commit it to version control.\n\n\n## Get Started\n\n\n \n Verify your email and obtain a separate REST API key.\n \n \n Get your API key and make your first request in minutes.\n \n \n Install and use the Recoup CLI to interact with the platform from your terminal.\n \n \n Connect Claude to Recoup through MCP OAuth, then add optional workflow skills.\n \n \n Connect Recoup to AI assistants via the Model Context Protocol.\n \n\n\n## API Sections\n\nThe API includes these major sections. Use these links to jump to the right area.\n\n\n \n Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements.\n \n \n Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.\n \n \n Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.\n \n \n Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.\n \n \n Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.\n \n \n Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools.\n \n \n Hosted listening pages, embeddable players, event reporting and fan connections.\n \n\n\n## Agents\n\n\n \n Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.\n \n \n API key authentication, account-scoped access, and organization-level permissions.\n \n\n\n## Quick Reference for LLMs\n\nIf you are an LLM navigating these docs, here is a summary of the endpoint structure:\n\n- **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile)\n- **`/api/research/*`** — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits.\n- **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)\n- **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact)\n- **Songs and catalogs** — Read songs with `/api/songs`; import songs into an accessible catalog with `/api/catalogs/songs`. Analysis, catalog management and catalog-song reads/deletes have their own references. [Standalone song creation is not available](/api-reference/songs/create).\n- **`/api/tasks/*`** — Task automation (get, create, update, delete, runs)\n- **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album)\n- **`/api/instagram/*`** — Instagram (comments, profiles)\n- **`/api/x/*`** — X/Twitter (search, trends)\n- **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect)\n- **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist)\n- **`/api/organizations/*`** — Organizations (list, create, add-artist)\n- **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload)\n- **`/api/players/*`** — Release Players (list, create, update, activity and fans)\n- **`/api/content-agent/*`** — Content agent webhooks (webhook, callback)\n- **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required\n\nBase URL: `https://api.recoupable.dev/api`\n\n[OpenAPI Specification](https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi)\n\n## Need Help?\n\n\n Reach out to our team at agent@recoupable.dev for assistance with the Recoup API.\n\n","headings":[{"title":"Connect your account","id":"connect-your-account"},{"title":"What is Recoup?","id":"what-is-recoup"},{"title":"Platform base URL","id":"platform-base-url"},{"title":"Authentication","id":"authentication"},{"title":"Get Started","id":"get-started"},{"title":"API Sections","id":"api-sections"},{"title":"Agents","id":"agents"},{"title":"Quick Reference for LLMs","id":"quick-reference-for-llms"},{"title":"Need Help?","id":"need-help"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n }, {Card, CardGroup, Warning} = _components;\n if (!Card) _missingMdxReference(\"Card\", true);\n if (!CardGroup) _missingMdxReference(\"CardGroup\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"These guides cover the authenticated music-platform API. For anonymous search,\\nreading, and website tools, use the separate \", _jsx(_components.a, {\n href: \"/public-website-api\",\n children: \"public website API\"\n }), \"\\nand its \", _jsx(_components.a, {\n href: \"https://recoupable.dev/openapi.json\",\n children: \"OpenAPI specification\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"connect-your-account\",\n children: \"Connect your account\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For an AI host, start with \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \": sign in to your real account,\\napprove the intended scope and verify access with a read. For REST integrations,\\ncreate an API key in your \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"account settings\"\n }), \", or\\nfollow the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"verified email/PIN flow\"\n }), \". Keep credentials in a secret facility.\\nAn empty roster can be valid; do not create a disposable account to recover access.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-is-recoup\",\n children: \"What is Recoup?\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"platform-base-url\",\n children: \"Platform base URL\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Platform API requests should be made to:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"https://api.recoupable.dev/api\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication\",\n children: \"Authentication\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Most API endpoints are authenticated using an API key passed in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header. The only exceptions are the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"agent onboarding\"\n }), \" endpoints — \", _jsx(_components.a, {\n href: \"/api-reference/agents/signup\",\n children: _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/agents/verify\",\n children: _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n })\n }), \" — which are intentionally unauthenticated so agents can obtain their first API key.\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys Management Page\"\n })]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Sign in with your account\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Create a new API key and copy it immediately (it's only shown once)\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/artists?accountId=YOUR_ACCOUNT_ID\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Keep your API key secure. Do not share it publicly or commit it to version control.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"get-started\",\n children: \"Get Started\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Agent Signup\",\n icon: \"user-plus\",\n href: \"/agents\",\n children: _jsx(_components.p, {\n children: \"Verify your email and obtain a separate REST API key.\"\n })\n }), _jsx(Card, {\n title: \"Quickstart\",\n icon: \"rocket\",\n href: \"/quickstart\",\n children: _jsx(_components.p, {\n children: \"Get your API key and make your first request in minutes.\"\n })\n }), _jsx(Card, {\n title: \"CLI\",\n icon: \"terminal\",\n href: \"/cli\",\n children: _jsx(_components.p, {\n children: \"Install and use the Recoup CLI to interact with the platform from your terminal.\"\n })\n }), _jsx(Card, {\n title: \"Claude\",\n icon: \"sparkles\",\n href: \"/claude\",\n children: _jsx(_components.p, {\n children: \"Connect Claude to Recoup through MCP OAuth, then add optional workflow skills.\"\n })\n }), _jsx(Card, {\n title: \"MCP Server\",\n icon: \"plug\",\n href: \"/mcp\",\n children: _jsx(_components.p, {\n children: \"Connect Recoup to AI assistants via the Model Context Protocol.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"api-sections\",\n children: \"API Sections\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The API includes these major sections. Use these links to jump to the right area.\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Research\",\n icon: \"magnifying-glass-chart\",\n href: \"/api-reference/research/search\",\n children: _jsx(_components.p, {\n children: \"Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements.\"\n })\n }), _jsx(Card, {\n title: \"Content Creation\",\n icon: \"wand-magic-sparkles\",\n href: \"/api-reference/content/create\",\n children: _jsx(_components.p, {\n children: \"Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.\"\n })\n }), _jsx(Card, {\n title: \"Chat\",\n icon: \"comments\",\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.p, {\n children: \"Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.\"\n })\n }), _jsx(Card, {\n title: \"Social Media\",\n icon: \"share-nodes\",\n href: \"/api-reference/connectors/list\",\n children: _jsx(_components.p, {\n children: \"Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.\"\n })\n }), _jsx(Card, {\n title: \"Releases\",\n icon: \"music\",\n href: \"/api-reference/songs/songs\",\n children: _jsx(_components.p, {\n children: \"Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.\"\n })\n }), _jsx(Card, {\n title: \"Accounts\",\n icon: \"building\",\n href: \"/api-reference/pulses/update\",\n children: _jsx(_components.p, {\n children: \"Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools.\"\n })\n }), _jsx(Card, {\n title: \"Release Players\",\n icon: \"play\",\n href: \"/essentials/release-player\",\n children: _jsx(_components.p, {\n children: \"Hosted listening pages, embeddable players, event reporting and fan connections.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"agents\",\n children: \"Agents\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Content Agent\",\n icon: \"robot\",\n href: \"/content-agent\",\n children: _jsx(_components.p, {\n children: \"Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.\"\n })\n }), _jsx(Card, {\n title: \"Authentication\",\n icon: \"key\",\n href: \"/authentication\",\n children: _jsx(_components.p, {\n children: \"API key authentication, account-scoped access, and organization-level permissions.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"quick-reference-for-llms\",\n children: \"Quick Reference for LLMs\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you are an LLM navigating these docs, here is a summary of the endpoint structure:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/artists/*\"\n })\n }), \" — Artist management (list, create, socials, socials-scrape, profile)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/research/*\"\n })\n }), \" — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/content/*\"\n })\n }), \" — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/chat/*\"\n })\n }), \" — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Songs and catalogs\"\n }), \" — Read songs with \", _jsx(_components.code, {\n children: \"/api/songs\"\n }), \"; import songs into an accessible catalog with \", _jsx(_components.code, {\n children: \"/api/catalogs/songs\"\n }), \". Analysis, catalog management and catalog-song reads/deletes have their own references. \", _jsx(_components.a, {\n href: \"/api-reference/songs/create\",\n children: \"Standalone song creation is not available\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/tasks/*\"\n })\n }), \" — Task automation (get, create, update, delete, runs)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/spotify/*\"\n })\n }), \" — Spotify (search, artist, artist-albums, artist-top-tracks, album)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/instagram/*\"\n })\n }), \" — Instagram (comments, profiles)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/x/*\"\n })\n }), \" — X/Twitter (search, trends)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/connectors/*\"\n })\n }), \" — OAuth connectors (list, authorize, disconnect)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/accounts/*\"\n })\n }), \" — Accounts (get, id, create, update, add-artist)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/organizations/*\"\n })\n }), \" — Organizations (list, create, add-artist)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/sandboxes/*\"\n })\n }), \" — Sandboxes (list, create, snapshot, delete, setup, file, upload)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/players/*\"\n })\n }), \" — Release Players (list, create, update, activity and fans)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/content-agent/*\"\n })\n }), \" — Content agent webhooks (webhook, callback)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/agents/*\"\n })\n }), \" — Agent onboarding (signup, verify) — no auth required\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Base URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/api\"\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi\",\n children: \"OpenAPI Specification\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"need-help\",\n children: \"Need Help?\"\n }), \"\\n\", _jsx(Card, {\n title: \"Contact Support\",\n icon: \"envelope\",\n href: \"mailto:agent@recoupable.dev\",\n children: _jsxs(_components.p, {\n children: [\"Reach out to our team at \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \" for assistance with the Recoup API.\"]\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Recoup API Documentation Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints. Quickstart Getting started These guides cover the authenticated music-platform API. For anonymous search, reading, and website tools, use the separate [public website API](/public-website-api) and its [OpenAPI specification](https://recoupable.dev/openapi.json). ## Connect your account For an AI host, start with [MCP OAuth](/mcp-oauth): sign in to your real account, approve the intended scope and verify access with a read. For REST integrations, create an API key in your [account settings](https://chat.recoupable.dev/keys), or follow the [verified email/PIN flow](/agents). Keep credentials in a secret facility. An empty roster can be valid; do not create a disposable account to recover access. ## What is Recoup? Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools. This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. ## Platform base URL Platform API requests should be made to: ## Authentication Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key. 1. Navigate to the [API Keys Management Page](https://chat.recoupable.dev/keys) 2. Sign in with your account 3. Create a new API key and copy it immediately (it's only shown once) Keep your API key secure. Do not share it publicly or commit it to version control. ## Get Started Verify your email and obtain a separate REST API key. Get your API key and make your first request in minutes. Install and use the Recoup CLI to interact with the platform from your terminal. Connect Claude to Recoup through MCP OAuth, then add optional workflow skills. Connect Recoup to AI assistants via the Model Context Protocol. ## API Sections The API includes these major sections. Use these links to jump to the right area. Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements. Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs. Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history. Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors. Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation. Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools. Hosted listening pages, embeddable players, event reporting and fan connections. ## Agents Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically. API key authentication, account-scoped access, and organization-level permissions. ## Quick Reference for LLMs If you are an LLM navigating these docs, here is a summary of the endpoint structure: - **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile) - **`/api/research/*`** — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits. - **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate) - **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact) - **Songs and catalogs** — Read songs with `/api/songs`; import songs into an accessible catalog with `/api/catalogs/songs`. Analysis, catalog management and catalog-song reads/deletes have their own references. [Standalone song creation is not available](/api-reference/songs/create). - **`/api/tasks/*`** — Task automation (get, create, update, delete, runs) - **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album) - **`/api/instagram/*`** — Instagram (comments, profiles) - **`/api/x/*`** — X/Twitter (search, trends) - **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect) - **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist) - **`/api/organizations/*`** — Organizations (list, create, add-artist) - **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload) - **`/api/players/*`** — Release Players (list, create, update, activity and fans) - **`/api/content-agent/*`** — Content agent webhooks (webhook, callback) - **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required Base URL: `https://api.recoupable.dev/api` [OpenAPI Specification](https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi) ## Need Help? Reach out to our team at agent@recoupable.dev for assistance with the Recoup API. "},{"slug":"quickstart","title":"Quickstart","description":"Connect your real account and make your first authenticated request.","category":"Quickstart","group":"Getting started","source":"quickstart.mdx","body":"## Connect first\n\nUse [MCP OAuth](/mcp-oauth) for a supported AI host. For the REST examples below,\ncreate a personal API key in [account settings](https://chat.recoupable.dev/keys)\nor follow the [Agents email verification guide](/agents). Store the key as\n`RECOUP_API_KEY` through your secret facility or an approved environment file.\nNever paste credentials into agent instructions or create a disposable account\nto access an existing customer's data.\n\nVerify the REST credential before continuing:\n\n```bash\ncurl --fail-with-body -sS -H \"x-api-key: $RECOUP_API_KEY\" \\\n https://api.recoupable.dev/api/accounts/id\n```\n\n## Base URL\n\nFor a language client, use the [Recoup SDK guide](/sdks). It includes the\npublished Go package, Python source installation, and the Node CLI.\n\nAll API requests should be made to:\n\n```bash\nhttps://api.recoupable.dev/api\n```\n\n## Your First Request\n\nOnce you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks:\n\n\n\n```bash cURL\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n```python Python\nimport requests\n\nheaders = {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\"\n}\n\nresponse = requests.get(\n \"https://api.recoupable.dev/api/tasks\",\n headers=headers\n)\nprint(response.json())\n```\n\n```javascript JavaScript\nconst response = await fetch(\"https://api.recoupable.dev/api/tasks\", {\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\",\n },\n});\nconst data = await response.json();\nconsole.log(data);\n```\n\n```typescript TypeScript\ninterface Task {\n id: string;\n title: string;\n prompt: string;\n schedule: string;\n account_id: string;\n artist_account_id: string;\n enabled: boolean;\n}\n\ninterface TasksResponse {\n status: \"success\" | \"error\";\n tasks: Task[];\n}\n\nconst response = await fetch(\"https://api.recoupable.dev/api/tasks\", {\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\",\n },\n});\nconst data: TasksResponse = await response.json();\nconsole.log(data.tasks);\n```\n\n\n\n**Example Response:**\n\n```json\n{\n \"status\": \"success\",\n \"tasks\": [\n {\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"title\": \"Daily Fan Report\",\n \"prompt\": \"Generate a summary of new fans from the past 24 hours\",\n \"schedule\": \"0 9 * * *\",\n \"account_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"artist_account_id\": \"987fcdeb-51a2-3b4c-d5e6-789012345678\",\n \"enabled\": true\n }\n ]\n}\n```\n\n\nFor full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get).\n\n\n## Prefer the dashboard?\n\nIf you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:\n\n1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.dev/keys)\n2. Sign in with your account\n3. Enter a descriptive name (e.g. \"Production Server\")\n4. Click **Create API Key**\n\n\nCopy and securely store your API key immediately — it will only be shown once.\n\n\n## Next Steps\n\nWith your API key ready, you can now:\n\n\n \n Fetch artists' social accounts and follower counts.\n \n \n Access fan data across all connected social platforms.\n \n \n Build AI-powered conversations with artist context.\n \n \n Schedule and automate recurring tasks.\n \n\n\n## Support\n\nIf you need help or have questions about the API, please contact our support team at [agent@recoupable.dev](mailto:agent@recoupable.dev).\n","headings":[{"title":"Connect first","id":"connect-first"},{"title":"Base URL","id":"base-url"},{"title":"Your First Request","id":"your-first-request"},{"title":"Prefer the dashboard?","id":"prefer-the-dashboard"},{"title":"Next Steps","id":"next-steps"},{"title":"Support","id":"support"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ...props.components\n }, {Card, CardGroup, CodeGroup, Info, Warning} = _components;\n if (!Card) _missingMdxReference(\"Card\", true);\n if (!CardGroup) _missingMdxReference(\"CardGroup\", true);\n if (!CodeGroup) _missingMdxReference(\"CodeGroup\", true);\n if (!Info) _missingMdxReference(\"Info\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"connect-first\",\n children: \"Connect first\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for a supported AI host. For the REST examples below,\\ncreate a personal API key in \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"account settings\"\n }), \"\\nor follow the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents email verification guide\"\n }), \". Store the key as\\n\", _jsx(_components.code, {\n children: \"RECOUP_API_KEY\"\n }), \" through your secret facility or an approved environment file.\\nNever paste credentials into agent instructions or create a disposable account\\nto access an existing customer's data.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Verify the REST credential before continuing:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl --fail-with-body -sS -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n https://api.recoupable.dev/api/accounts/id\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"base-url\",\n children: \"Base URL\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a language client, use the \", _jsx(_components.a, {\n href: \"/sdks\",\n children: \"Recoup SDK guide\"\n }), \". It includes the\\npublished Go package, Python source installation, and the Node CLI.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"All API requests should be made to:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"https://api.recoupable.dev/api\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"your-first-request\",\n children: \"Your First Request\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once you have an API key, include it in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header on every request. Here's a simple call that retrieves your scheduled tasks:\"]\n }), \"\\n\", _jsxs(CodeGroup, {\n children: [_jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-python\",\n children: \"import requests\\n\\nheaders = {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\"\\n}\\n\\nresponse = requests.get(\\n \\\"https://api.recoupable.dev/api/tasks\\\",\\n headers=headers\\n)\\nprint(response.json())\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-javascript\",\n children: \"const response = await fetch(\\\"https://api.recoupable.dev/api/tasks\\\", {\\n headers: {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\",\\n },\\n});\\nconst data = await response.json();\\nconsole.log(data);\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-typescript\",\n children: \"interface Task {\\n id: string;\\n title: string;\\n prompt: string;\\n schedule: string;\\n account_id: string;\\n artist_account_id: string;\\n enabled: boolean;\\n}\\n\\ninterface TasksResponse {\\n status: \\\"success\\\" | \\\"error\\\";\\n tasks: Task[];\\n}\\n\\nconst response = await fetch(\\\"https://api.recoupable.dev/api/tasks\\\", {\\n headers: {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\",\\n },\\n});\\nconst data: TasksResponse = await response.json();\\nconsole.log(data.tasks);\\n\"\n })\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"Example Response:\"\n })\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"status\\\": \\\"success\\\",\\n \\\"tasks\\\": [\\n {\\n \\\"id\\\": \\\"550e8400-e29b-41d4-a716-446655440000\\\",\\n \\\"title\\\": \\\"Daily Fan Report\\\",\\n \\\"prompt\\\": \\\"Generate a summary of new fans from the past 24 hours\\\",\\n \\\"schedule\\\": \\\"0 9 * * *\\\",\\n \\\"account_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\\n \\\"artist_account_id\\\": \\\"987fcdeb-51a2-3b4c-d5e6-789012345678\\\",\\n \\\"enabled\\\": true\\n }\\n ]\\n}\\n\"\n })\n }), \"\\n\", _jsx(Info, {\n children: _jsxs(_components.p, {\n children: [\"For full documentation on the Tasks API including filtering options, see the \", _jsx(_components.a, {\n href: \"/api-reference/tasks/get\",\n children: \"Tasks API Reference\"\n }), \".\"]\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"prefer-the-dashboard\",\n children: \"Prefer the dashboard?\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"Recoup API Keys Management Page\"\n })]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Sign in with your account\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Enter a descriptive name (e.g. \\\"Production Server\\\")\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Click \", _jsx(_components.strong, {\n children: \"Create API Key\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Copy and securely store your API key immediately — it will only be shown once.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"next-steps\",\n children: \"Next Steps\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"With your API key ready, you can now:\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Artist Data\",\n icon: \"user\",\n href: \"/api-reference/artists/socials\",\n children: _jsx(_components.p, {\n children: \"Fetch artists' social accounts and follower counts.\"\n })\n }), _jsx(Card, {\n title: \"Fan Analytics\",\n icon: \"users\",\n href: \"/api-reference/fans/get\",\n children: _jsx(_components.p, {\n children: \"Access fan data across all connected social platforms.\"\n })\n }), _jsx(Card, {\n title: \"Chat API\",\n icon: \"comments\",\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.p, {\n children: \"Build AI-powered conversations with artist context.\"\n })\n }), _jsx(Card, {\n title: \"Task Management\",\n icon: \"list-check\",\n href: \"/api-reference/tasks/get\",\n children: _jsx(_components.p, {\n children: \"Schedule and automate recurring tasks.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"support\",\n children: \"Support\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you need help or have questions about the API, please contact our support team at \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Quickstart Connect your real account and make your first authenticated request. Quickstart Getting started ## Connect first Use [MCP OAuth](/mcp-oauth) for a supported AI host. For the REST examples below, create a personal API key in [account settings](https://chat.recoupable.dev/keys) or follow the [Agents email verification guide](/agents). Store the key as `RECOUP_API_KEY` through your secret facility or an approved environment file. Never paste credentials into agent instructions or create a disposable account to access an existing customer's data. Verify the REST credential before continuing: ## Base URL For a language client, use the [Recoup SDK guide](/sdks). It includes the published Go package, Python source installation, and the Node CLI. All API requests should be made to: ## Your First Request Once you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks: **Example Response:** For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). ## Prefer the dashboard? If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint: 1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.dev/keys) 2. Sign in with your account 3. Enter a descriptive name (e.g. \"Production Server\") 4. Click **Create API Key** Copy and securely store your API key immediately — it will only be shown once. ## Next Steps With your API key ready, you can now: Fetch artists' social accounts and follower counts. Access fan data across all connected social platforms. Build AI-powered conversations with artist context. Schedule and automate recurring tasks. ## Support If you need help or have questions about the API, please contact our support team at [agent@recoupable.dev](mailto:agent@recoupable.dev). "},{"slug":"sdks","title":"Recoup SDKs: Go and Python clients for the music API","description":"Install the official Recoup Python SDK from PyPI, the Go SDK from its module registry, and the Node CLI from npm. Includes authentication, response handling, and package links.","category":"Quickstart","group":"Getting started","source":"sdks.mdx","body":"Use the official Recoup clients to call the platform's JSON API from your application.\nBoth SDKs support an API key or an existing Bearer token, bounded responses,\nstructured HTTP errors, and an account-identity helper. Their licenses are MIT.\n\n## Packages\n\n| Language | Package | Availability |\n| --- | --- | --- |\n| Go 1.23+ | [github.com/recoupable/marketing/sdk/go](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) | Version `v0.1.0` is published and indexed. |\n| Python 3.10+ | [recoupable on PyPI](https://pypi.org/project/recoupable/0.1.0/) | Version `0.1.0` is published. |\n| Node.js CLI | [@recoupable/cli on npm](https://www.npmjs.com/package/@recoupable/cli) | The terminal client is published. See the [CLI guide](/cli) for supported commands. |\n\nThe Go and Python SDKs handle JSON endpoints. They do not implement streaming,\nmultipart uploads, OAuth login, automatic pagination, or generated methods for\nevery endpoint. Use each endpoint's reference to check its availability, required\npermissions, request shape, and response type. A package installation does not\ngrant account access.\n\n## Go\n\nInstall the published version:\n\n```sh\ngo get github.com/recoupable/marketing/sdk/go@v0.1.0\n```\n\nRead an existing API key from your application's secret environment:\n\n```go\npackage main\n\nimport (\n \"context\"\n \"log\"\n \"os\"\n\n recoupable \"github.com/recoupable/marketing/sdk/go\"\n)\n\nfunc main() {\n client, err := recoupable.New(recoupable.Options{\n APIKey: os.Getenv(\"RECOUP_API_KEY\"),\n })\n if err != nil { log.Fatal(err) }\n account, err := client.GetAccountID(context.Background())\n if err != nil { log.Fatal(err) }\n log.Print(account.AccountID)\n}\n```\n\nUse `Options{AccessToken: ...}` for an existing Bearer token. The generic\n`Request(ctx, method, path, query, body, out)` method supports other documented\nJSON endpoints. Pass query parameters as `url.Values` and an unencoded `/api/` path.\nSee the [Go package reference](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0)\nfor method signatures and error types.\n\n## Python\n\nInstall the published version:\n\n```sh\npython -m pip install recoupable==0.1.0\n```\n\n```python\nimport os\nfrom recoupable import Client\n\nclient = Client(api_key=os.environ[\"RECOUP_API_KEY\"])\naccount = client.get_account_id()\nprint(account[\"accountId\"])\n```\n\nUse `Client(access_token=...)` for an existing Bearer token. The generic\n`request(method, path, query=..., body=...)` method returns decoded JSON or `None`\nfor an empty successful response. Read the [Python client reference](https://github.com/recoupable/marketing/tree/main/sdk/python)\nfor configuration and error handling.\n\n## Authentication and response handling\n\nSupply exactly one credential. Create a key in [Recoup account settings](https://chat.recoupable.dev/keys),\nor follow the [authentication guide](/authentication) for supported access methods.\nThe default API origin is `https://api.recoupable.dev`. A custom HTTPS origin is\nan explicit destination for your credential. Redirects are not followed.\n\nBoth clients cap responses at 16 MiB by default and accept empty successful\nresponses. Python uses a 30-second timeout per blocking socket operation; Go\nuses a 30-second total request deadline and supports earlier context deadlines.\nThese limits are configurable.\n\nHTTP errors retain their status and headers, including `Retry-After`; oversized\nerror bodies are truncated. Inspect the error's fields when deciding what to do.\nError messages omit credentials and response bodies. Treat a response body as\npotentially private if you log it.\n\nThe SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent\nrequest on a reused connection. A transport failure can occur after a write has\ncompleted; check the operation's outcome before repeating it.\n","headings":[{"title":"Packages","id":"packages"},{"title":"Go","id":"go"},{"title":"Python","id":"python"},{"title":"Authentication and response handling","id":"authentication-and-response-handling"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Use the official Recoup clients to call the platform's JSON API from your application.\\nBoth SDKs support an API key or an existing Bearer token, bounded responses,\\nstructured HTTP errors, and an account-identity helper. Their licenses are MIT.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"packages\",\n children: \"Packages\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Language\"\n }), _jsx(_components.th, {\n children: \"Package\"\n }), _jsx(_components.th, {\n children: \"Availability\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Go 1.23+\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0\",\n children: \"github.com/recoupable/marketing/sdk/go\"\n })\n }), _jsxs(_components.td, {\n children: [\"Version \", _jsx(_components.code, {\n children: \"v0.1.0\"\n }), \" is published and indexed.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Python 3.10+\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://pypi.org/project/recoupable/0.1.0/\",\n children: \"recoupable on PyPI\"\n })\n }), _jsxs(_components.td, {\n children: [\"Version \", _jsx(_components.code, {\n children: \"0.1.0\"\n }), \" is published.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Node.js CLI\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://www.npmjs.com/package/@recoupable/cli\",\n children: \"@recoupable/cli on npm\"\n })\n }), _jsxs(_components.td, {\n children: [\"The terminal client is published. See the \", _jsx(_components.a, {\n href: \"/cli\",\n children: \"CLI guide\"\n }), \" for supported commands.\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The Go and Python SDKs handle JSON endpoints. They do not implement streaming,\\nmultipart uploads, OAuth login, automatic pagination, or generated methods for\\nevery endpoint. Use each endpoint's reference to check its availability, required\\npermissions, request shape, and response type. A package installation does not\\ngrant account access.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"go\",\n children: \"Go\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Install the published version:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-sh\",\n children: \"go get github.com/recoupable/marketing/sdk/go@v0.1.0\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Read an existing API key from your application's secret environment:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-go\",\n children: \"package main\\n\\nimport (\\n \\\"context\\\"\\n \\\"log\\\"\\n \\\"os\\\"\\n\\n recoupable \\\"github.com/recoupable/marketing/sdk/go\\\"\\n)\\n\\nfunc main() {\\n client, err := recoupable.New(recoupable.Options{\\n APIKey: os.Getenv(\\\"RECOUP_API_KEY\\\"),\\n })\\n if err != nil { log.Fatal(err) }\\n account, err := client.GetAccountID(context.Background())\\n if err != nil { log.Fatal(err) }\\n log.Print(account.AccountID)\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"Options{AccessToken: ...}\"\n }), \" for an existing Bearer token. The generic\\n\", _jsx(_components.code, {\n children: \"Request(ctx, method, path, query, body, out)\"\n }), \" method supports other documented\\nJSON endpoints. Pass query parameters as \", _jsx(_components.code, {\n children: \"url.Values\"\n }), \" and an unencoded \", _jsx(_components.code, {\n children: \"/api/\"\n }), \" path.\\nSee the \", _jsx(_components.a, {\n href: \"https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0\",\n children: \"Go package reference\"\n }), \"\\nfor method signatures and error types.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"python\",\n children: \"Python\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Install the published version:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-sh\",\n children: \"python -m pip install recoupable==0.1.0\\n\"\n })\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-python\",\n children: \"import os\\nfrom recoupable import Client\\n\\nclient = Client(api_key=os.environ[\\\"RECOUP_API_KEY\\\"])\\naccount = client.get_account_id()\\nprint(account[\\\"accountId\\\"])\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"Client(access_token=...)\"\n }), \" for an existing Bearer token. The generic\\n\", _jsx(_components.code, {\n children: \"request(method, path, query=..., body=...)\"\n }), \" method returns decoded JSON or \", _jsx(_components.code, {\n children: \"None\"\n }), \"\\nfor an empty successful response. Read the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketing/tree/main/sdk/python\",\n children: \"Python client reference\"\n }), \"\\nfor configuration and error handling.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication-and-response-handling\",\n children: \"Authentication and response handling\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Supply exactly one credential. Create a key in \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"Recoup account settings\"\n }), \",\\nor follow the \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"authentication guide\"\n }), \" for supported access methods.\\nThe default API origin is \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \". A custom HTTPS origin is\\nan explicit destination for your credential. Redirects are not followed.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Both clients cap responses at 16 MiB by default and accept empty successful\\nresponses. Python uses a 30-second timeout per blocking socket operation; Go\\nuses a 30-second total request deadline and supports earlier context deadlines.\\nThese limits are configurable.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP errors retain their status and headers, including \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \"; oversized\\nerror bodies are truncated. Inspect the error's fields when deciding what to do.\\nError messages omit credentials and response bodies. Treat a response body as\\npotentially private if you log it.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent\\nrequest on a reused connection. A transport failure can occur after a write has\\ncompleted; check the operation's outcome before repeating it.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Recoup SDKs: Go and Python clients for the music API Install the official Recoup Python SDK from PyPI, the Go SDK from its module registry, and the Node CLI from npm. Includes authentication, response handling, and package links. Quickstart Getting started Use the official Recoup clients to call the platform's JSON API from your application. Both SDKs support an API key or an existing Bearer token, bounded responses, structured HTTP errors, and an account-identity helper. Their licenses are MIT. ## Packages | Language | Package | Availability | | --- | --- | --- | | Go 1.23+ | [github.com/recoupable/marketing/sdk/go](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) | Version `v0.1.0` is published and indexed. | | Python 3.10+ | [recoupable on PyPI](https://pypi.org/project/recoupable/0.1.0/) | Version `0.1.0` is published. | | Node.js CLI | [@recoupable/cli on npm](https://www.npmjs.com/package/@recoupable/cli) | The terminal client is published. See the [CLI guide](/cli) for supported commands. | The Go and Python SDKs handle JSON endpoints. They do not implement streaming, multipart uploads, OAuth login, automatic pagination, or generated methods for every endpoint. Use each endpoint's reference to check its availability, required permissions, request shape, and response type. A package installation does not grant account access. ## Go Install the published version: Read an existing API key from your application's secret environment: Use `Options{AccessToken: ...}` for an existing Bearer token. The generic `Request(ctx, method, path, query, body, out)` method supports other documented JSON endpoints. Pass query parameters as `url.Values` and an unencoded `/api/` path. See the [Go package reference](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) for method signatures and error types. ## Python Install the published version: Use `Client(access_token=...)` for an existing Bearer token. The generic `request(method, path, query=..., body=...)` method returns decoded JSON or `None` for an empty successful response. Read the [Python client reference](https://github.com/recoupable/marketing/tree/main/sdk/python) for configuration and error handling. ## Authentication and response handling Supply exactly one credential. Create a key in [Recoup account settings](https://chat.recoupable.dev/keys), or follow the [authentication guide](/authentication) for supported access methods. The default API origin is `https://api.recoupable.dev`. A custom HTTPS origin is an explicit destination for your credential. Redirects are not followed. Both clients cap responses at 16 MiB by default and accept empty successful responses. Python uses a 30-second timeout per blocking socket operation; Go uses a 30-second total request deadline and supports earlier context deadlines. These limits are configurable. HTTP errors retain their status and headers, including `Retry-After`; oversized error bodies are truncated. Inspect the error's fields when deciding what to do. Error messages omit credentials and response bodies. Treat a response body as potentially private if you log it. The SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent request on a reused connection. A transport failure can occur after a write has completed; check the operation's outcome before repeating it. "},{"slug":"public-website-api","title":"Recoup public website API","description":"Search and read public Recoup content, use bounded website tools, and batch independent operations without an account.","category":"Quickstart","group":"Getting started","source":"public-website-api.mdx","body":"The public website API searches and reads published Recoup pages, calculates\nworkflow scenarios from supplied inputs, and prepares unsubmitted project briefs.\nIt is free and requires no account, API key, or payment method.\n\nMusic-platform operations use the separate authenticated\n[platform API](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot\nread account data, manage artists, publish content, or send an inquiry.\n\n## Specification and first request\n\nThe [website OpenAPI specification](https://recoupable.dev/openapi.json) defines\nevery HTTP operation, its input and response schemas, and typed errors.\nThe [API catalog](https://recoupable.dev/.well-known/api-catalog) links this\nspecification alongside the platform specifications.\n\n```bash\ncurl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'\n```\n\nThe response contains `results`, `total`, and `nextCursor`. An empty result list\nis a successful search. Use a returned content ID with\n`GET /agent-api/v1/read?id=CONTENT_ID`; continue at the returned `nextOffset`\nuntil it is null. The reader accepts registry IDs, never arbitrary private URLs.\n\nUse `GET /agent-api/v1/markdown?path=/blog` for a complete public page as Markdown.\nThe [website agent guide](https://recoupable.dev/agents.md) explains all five tools,\npagination, draft behavior, and the browser interface.\n\n## Batch independent operations\n\n`POST https://recoupable.dev/agent-api/v1/batch` accepts one to ten operations.\n\n```bash\ncurl 'https://recoupable.dev/agent-api/v1/batch' \\\n -H 'Content-Type: application/json' \\\n --data '{\"operations\":[{\"name\":\"search_recoup\",\"arguments\":{\"query\":\"royalty\",\"limit\":1}},{\"name\":\"read_recoup_page\",\"arguments\":{\"id\":\"page:/services\",\"maxLength\":500}}]}'\n```\n\nThe `results` array preserves input order. Each entry has its own `status` and\n`result` or `error`. An individual failure does not cancel successful reads.\nThe batch is not a transaction. Its entire request body must fit within 16 KB.\nDraft operations return `submitted: false`; nothing is sent or saved as a lead.\n\n## Hosted quotas and errors\n\nHTTP and MCP website tools share a limit of 120 requests per 60-second fixed\nwindow, per IP address and serving region. A batch counts as one request.\n`RateLimit-Limit` and `RateLimit-Policy` describe that enforced policy on live\nresponses. Regional counters are not a global account allowance.\n\nOn HTTP 429, wait the `Retry-After` duration before retrying. HTTP 503 means the\nrequest could not be completed; retry later. JSON tool endpoints return structured\nerrors with a code, message, and recovery guidance for invalid arguments or missing content.\nLocal development does not enforce the hosted quota.\n\n## Versioning and deprecation\n\nWebsite HTTP operations use `/agent-api/v1`. Additive response fields are\ncompatible; clients should ignore fields they do not recognize. Incompatible\nchanges require a new major URL version.\n\nNo v1 deprecation or sunset is scheduled. A future retirement will be announced\nin the [agent guide](https://recoupable.dev/agents.md) with a migration guide and\n`Deprecation`, `Sunset`, and `Link` response headers when dates are known.\nThis policy applies to the public website API.\n\n## MCP connection\n\nConnect to `https://recoupable.dev/mcp` over Streamable HTTP without credentials.\nThe [public manifest](https://recoupable.dev/.well-known/mcp.json) identifies\nthe server. Its five tools share the website HTTP capabilities and hosted quota.\nTo use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead.\n","headings":[{"title":"Specification and first request","id":"specification-and-first-request"},{"title":"Batch independent operations","id":"batch-independent-operations"},{"title":"Hosted quotas and errors","id":"hosted-quotas-and-errors"},{"title":"Versioning and deprecation","id":"versioning-and-deprecation"},{"title":"MCP connection","id":"mcp-connection"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"The public website API searches and reads published Recoup pages, calculates\\nworkflow scenarios from supplied inputs, and prepares unsubmitted project briefs.\\nIt is free and requires no account, API key, or payment method.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Music-platform operations use the separate authenticated\\n\", _jsx(_components.a, {\n href: \"/quickstart\",\n children: \"platform API\"\n }), \" and \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"platform MCP\"\n }), \". Website tools cannot\\nread account data, manage artists, publish content, or send an inquiry.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"specification-and-first-request\",\n children: \"Specification and first request\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"https://recoupable.dev/openapi.json\",\n children: \"website OpenAPI specification\"\n }), \" defines\\nevery HTTP operation, its input and response schemas, and typed errors.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/.well-known/api-catalog\",\n children: \"API catalog\"\n }), \" links this\\nspecification alongside the platform specifications.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response contains \", _jsx(_components.code, {\n children: \"results\"\n }), \", \", _jsx(_components.code, {\n children: \"total\"\n }), \", and \", _jsx(_components.code, {\n children: \"nextCursor\"\n }), \". An empty result list\\nis a successful search. Use a returned content ID with\\n\", _jsx(_components.code, {\n children: \"GET /agent-api/v1/read?id=CONTENT_ID\"\n }), \"; continue at the returned \", _jsx(_components.code, {\n children: \"nextOffset\"\n }), \"\\nuntil it is null. The reader accepts registry IDs, never arbitrary private URLs.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"GET /agent-api/v1/markdown?path=/blog\"\n }), \" for a complete public page as Markdown.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/agents.md\",\n children: \"website agent guide\"\n }), \" explains all five tools,\\npagination, draft behavior, and the browser interface.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"batch-independent-operations\",\n children: \"Batch independent operations\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST https://recoupable.dev/agent-api/v1/batch\"\n }), \" accepts one to ten operations.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl 'https://recoupable.dev/agent-api/v1/batch' \\\\\\n -H 'Content-Type: application/json' \\\\\\n --data '{\\\"operations\\\":[{\\\"name\\\":\\\"search_recoup\\\",\\\"arguments\\\":{\\\"query\\\":\\\"royalty\\\",\\\"limit\\\":1}},{\\\"name\\\":\\\"read_recoup_page\\\",\\\"arguments\\\":{\\\"id\\\":\\\"page:/services\\\",\\\"maxLength\\\":500}}]}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.code, {\n children: \"results\"\n }), \" array preserves input order. Each entry has its own \", _jsx(_components.code, {\n children: \"status\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"result\"\n }), \" or \", _jsx(_components.code, {\n children: \"error\"\n }), \". An individual failure does not cancel successful reads.\\nThe batch is not a transaction. Its entire request body must fit within 16 KB.\\nDraft operations return \", _jsx(_components.code, {\n children: \"submitted: false\"\n }), \"; nothing is sent or saved as a lead.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hosted-quotas-and-errors\",\n children: \"Hosted quotas and errors\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP and MCP website tools share a limit of 120 requests per 60-second fixed\\nwindow, per IP address and serving region. A batch counts as one request.\\n\", _jsx(_components.code, {\n children: \"RateLimit-Limit\"\n }), \" and \", _jsx(_components.code, {\n children: \"RateLimit-Policy\"\n }), \" describe that enforced policy on live\\nresponses. Regional counters are not a global account allowance.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"On HTTP 429, wait the \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" duration before retrying. HTTP 503 means the\\nrequest could not be completed; retry later. JSON tool endpoints return structured\\nerrors with a code, message, and recovery guidance for invalid arguments or missing content.\\nLocal development does not enforce the hosted quota.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"versioning-and-deprecation\",\n children: \"Versioning and deprecation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Website HTTP operations use \", _jsx(_components.code, {\n children: \"/agent-api/v1\"\n }), \". Additive response fields are\\ncompatible; clients should ignore fields they do not recognize. Incompatible\\nchanges require a new major URL version.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"No v1 deprecation or sunset is scheduled. A future retirement will be announced\\nin the \", _jsx(_components.a, {\n href: \"https://recoupable.dev/agents.md\",\n children: \"agent guide\"\n }), \" with a migration guide and\\n\", _jsx(_components.code, {\n children: \"Deprecation\"\n }), \", \", _jsx(_components.code, {\n children: \"Sunset\"\n }), \", and \", _jsx(_components.code, {\n children: \"Link\"\n }), \" response headers when dates are known.\\nThis policy applies to the public website API.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"mcp-connection\",\n children: \"MCP connection\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connect to \", _jsx(_components.code, {\n children: \"https://recoupable.dev/mcp\"\n }), \" over Streamable HTTP without credentials.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/.well-known/mcp.json\",\n children: \"public manifest\"\n }), \" identifies\\nthe server. Its five tools share the website HTTP capabilities and hosted quota.\\nTo use your music-platform account, follow \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" instead.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Recoup public website API Search and read public Recoup content, use bounded website tools, and batch independent operations without an account. Quickstart Getting started The public website API searches and reads published Recoup pages, calculates workflow scenarios from supplied inputs, and prepares unsubmitted project briefs. It is free and requires no account, API key, or payment method. Music-platform operations use the separate authenticated [platform API](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot read account data, manage artists, publish content, or send an inquiry. ## Specification and first request The [website OpenAPI specification](https://recoupable.dev/openapi.json) defines every HTTP operation, its input and response schemas, and typed errors. The [API catalog](https://recoupable.dev/.well-known/api-catalog) links this specification alongside the platform specifications. The response contains `results`, `total`, and `nextCursor`. An empty result list is a successful search. Use a returned content ID with `GET /agent-api/v1/read?id=CONTENT_ID`; continue at the returned `nextOffset` until it is null. The reader accepts registry IDs, never arbitrary private URLs. Use `GET /agent-api/v1/markdown?path=/blog` for a complete public page as Markdown. The [website agent guide](https://recoupable.dev/agents.md) explains all five tools, pagination, draft behavior, and the browser interface. ## Batch independent operations `POST https://recoupable.dev/agent-api/v1/batch` accepts one to ten operations. The `results` array preserves input order. Each entry has its own `status` and `result` or `error`. An individual failure does not cancel successful reads. The batch is not a transaction. Its entire request body must fit within 16 KB. Draft operations return `submitted: false`; nothing is sent or saved as a lead. ## Hosted quotas and errors HTTP and MCP website tools share a limit of 120 requests per 60-second fixed window, per IP address and serving region. A batch counts as one request. `RateLimit-Limit` and `RateLimit-Policy` describe that enforced policy on live responses. Regional counters are not a global account allowance. On HTTP 429, wait the `Retry-After` duration before retrying. HTTP 503 means the request could not be completed; retry later. JSON tool endpoints return structured errors with a code, message, and recovery guidance for invalid arguments or missing content. Local development does not enforce the hosted quota. ## Versioning and deprecation Website HTTP operations use `/agent-api/v1`. Additive response fields are compatible; clients should ignore fields they do not recognize. Incompatible changes require a new major URL version. No v1 deprecation or sunset is scheduled. A future retirement will be announced in the [agent guide](https://recoupable.dev/agents.md) with a migration guide and `Deprecation`, `Sunset`, and `Link` response headers when dates are known. This policy applies to the public website API. ## MCP connection Connect to `https://recoupable.dev/mcp` over Streamable HTTP without credentials. The [public manifest](https://recoupable.dev/.well-known/mcp.json) identifies the server. Its five tools share the website HTTP capabilities and hosted quota. To use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead. "},{"slug":"cli","title":"CLI","description":"Install the Recoup CLI and interact with the platform from your terminal.","category":"Quickstart","group":"Getting started","source":"cli.mdx","body":"The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.\n\n\n**The CLI is in beta.** The reference below follows the v0.1.15 source command set. Check `recoup --version` and `--help` for the package installed in your environment. For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up.\n\n**Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.\n\n\n## Install\n\n```bash\nnpm install -g @recoupable/cli\n```\n\n## Authenticate\n\nSet your API key as an environment variable:\n\n```bash\nexport RECOUP_API_KEY=your-api-key\n```\n\nVerify it works:\n\n```bash\nrecoup whoami\n```\n\n\nGet an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) for instant key generation.\n\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `RECOUP_API_KEY` | Yes | — | Your Recoup API key |\n| `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override; set `https://api.recoupable.dev` to use the canonical API domain |\n\nAll commands support `--json` for machine-readable output and `--help` for usage info.\n\n---\n\n## Commands\n\n### whoami\n\nShow the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id).\n\n```bash\nrecoup whoami\nrecoup whoami --json\n```\n\n### orgs\n\nList organizations. See [`GET /api/organizations`](/api-reference/organizations/list).\n\n```bash\nrecoup orgs list\nrecoup orgs list --account \n```\n\n### artists\n\nList artists. See [`GET /api/artists`](/api-reference/artists/list).\n\n```bash\nrecoup artists list\nrecoup artists list --org \nrecoup artists list --account \n```\n\n### emails\n\nSend an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create).\n\n```bash\nrecoup emails --subject \"Pulse Report\" --text \"Here's your weekly summary.\"\nrecoup emails --subject \"Update\" --html \"

Report

Details here.

\"\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--subject ` | No | Email subject line; defaults from the body when omitted |\n| `--text ` | No | Plain text or Markdown body |\n| `--html ` | No | Raw HTML body (takes precedence over `--text`) |\n| `--cc ` | No | CC recipient (repeatable) |\n| `--chat-id ` | No | Chat ID for a chat link in the email footer |\n| `--account ` | No | Send to a specific account (org keys only) |\n\n### chats\n\nManage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create).\n\n```bash\nrecoup chats list\nrecoup chats create --name \"My Topic\"\nrecoup chats create --name \"My Topic\" --artist \n```\n\n### sandboxes\n\nManage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create).\n\n```bash\nrecoup sandboxes list\nrecoup sandboxes create\nrecoup sandboxes create --command \"ls -la\"\n```\n\n### tasks\n\nCheck background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs).\n\n```bash\nrecoup tasks status --run \n```\n\n### songs\n\nRun AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets).\n\n```bash\nrecoup songs presets\nrecoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3\nrecoup songs analyze --prompt \"Describe the production style\" --audio https://example.com/track.mp3\n```\n\nExactly one of `--preset` or `--prompt` is required, together with `--audio`. The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API.\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. |\n| `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. |\n| `--audio ` | Yes | Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported. |\n| `--max-tokens ` | No | Max tokens to generate (default 512). |\n\n---\n\n## content\n\nContent creation pipeline — generate AI-powered social videos for artists.\n\n### List templates\n\n```bash\nrecoup content templates\n```\n\n### Validate an artist\n\nCheck that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate).\n\n```bash\nrecoup content validate --artist \n```\n\n### Estimate cost\n\nPreview estimated cost and duration before kicking off the pipeline. See [`GET /api/content/estimate`](/api-reference/content/estimate).\n\n```bash\nrecoup content estimate\nrecoup content estimate --lipsync --batch 2 --compare\n```\n\n### Create content\n\nRun the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create).\n\n```bash\nrecoup content create --artist \nrecoup content create --artist --template --lipsync --upscale\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--artist ` | Yes | Artist account ID |\n| `--template ` | No | Template name (default: random) |\n| `--lipsync` | No | Enable lipsync mode |\n| `--upscale` | No | Enable upscaling |\n| `--caption-length ` | No | Max caption length in characters |\n\n\nFor finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands.\n\n","headings":[{"title":"Install","id":"install"},{"title":"Authenticate","id":"authenticate"},{"title":"Configuration","id":"configuration"},{"title":"Commands","id":"commands"},{"title":"content","id":"content"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n }, {Note, Tip} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Tip) _missingMdxReference(\"Tip\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"The Recoup CLI (\", _jsx(_components.code, {\n children: \"@recoupable/cli\"\n }), \") wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.\"]\n }), \"\\n\", _jsxs(Note, {\n children: [_jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"The CLI is in beta.\"\n }), \" The reference below follows the v0.1.15 source command set. Check \", _jsx(_components.code, {\n children: \"recoup --version\"\n }), \" and \", _jsx(_components.code, {\n children: \"--help\"\n }), \" for the package installed in your environment. For research workflows and most content operations, call the \", _jsx(_components.a, {\n href: \"/api-reference\",\n children: \"REST API\"\n }), \" directly — the CLI is gradually catching up.\"]\n }), _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Agents:\"\n }), \" if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.\"]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"install\",\n children: \"Install\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"npm install -g @recoupable/cli\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authenticate\",\n children: \"Authenticate\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Set your API key as an environment variable:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"export RECOUP_API_KEY=your-api-key\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Verify it works:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup whoami\\n\"\n })\n }), \"\\n\", _jsx(Tip, {\n children: _jsxs(_components.p, {\n children: [\"Get an API key from the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys page\"\n }), \" or use the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"agent signup\"\n }), \" for instant key generation.\"]\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"configuration\",\n children: \"Configuration\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Variable\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Default\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"RECOUP_API_KEY\"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"—\"\n }), _jsx(_components.td, {\n children: \"Your Recoup API key\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"RECOUP_API_URL\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"https://recoup-api.vercel.app\"\n })\n }), _jsxs(_components.td, {\n children: [\"API base URL override; set \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \" to use the canonical API domain\"]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"All commands support \", _jsx(_components.code, {\n children: \"--json\"\n }), \" for machine-readable output and \", _jsx(_components.code, {\n children: \"--help\"\n }), \" for usage info.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"commands\",\n children: \"Commands\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"whoami\",\n children: \"whoami\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Show the authenticated account. See \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup whoami\\nrecoup whoami --json\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"orgs\",\n children: \"orgs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"List organizations. See \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/organizations\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup orgs list\\nrecoup orgs list --account \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"artists\",\n children: \"artists\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"List artists. See \", _jsx(_components.a, {\n href: \"/api-reference/artists/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/artists\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup artists list\\nrecoup artists list --org \\nrecoup artists list --account \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"emails\",\n children: \"emails\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send an email to the authenticated account. See \", _jsx(_components.a, {\n href: \"/api-reference/emails/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/emails\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup emails --subject \\\"Pulse Report\\\" --text \\\"Here's your weekly summary.\\\"\\nrecoup emails --subject \\\"Update\\\" --html \\\"

Report

Details here.

\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--subject \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Email subject line; defaults from the body when omitted\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--text \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Plain text or Markdown body\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--html \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsxs(_components.td, {\n children: [\"Raw HTML body (takes precedence over \", _jsx(_components.code, {\n children: \"--text\"\n }), \")\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--cc \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"CC recipient (repeatable)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--chat-id \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Chat ID for a chat link in the email footer\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--account \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Send to a specific account (org keys only)\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"chats\",\n children: \"chats\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Manage chats. See \", _jsx(_components.a, {\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.code, {\n children: \"GET /api/chats\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/chat/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/chats\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup chats list\\nrecoup chats create --name \\\"My Topic\\\"\\nrecoup chats create --name \\\"My Topic\\\" --artist \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"sandboxes\",\n children: \"sandboxes\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Manage sandboxes. See \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/sandboxes\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup sandboxes list\\nrecoup sandboxes create\\nrecoup sandboxes create --command \\\"ls -la\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"tasks\",\n children: \"tasks\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Check background task status. See \", _jsx(_components.a, {\n href: \"/api-reference/tasks/runs\",\n children: _jsx(_components.code, {\n children: \"GET /api/tasks/runs\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup tasks status --run \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"songs\",\n children: \"songs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Run AI music analysis. See \", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze-presets\",\n children: _jsx(_components.code, {\n children: \"GET /api/songs/analyze/presets\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup songs presets\\nrecoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3\\nrecoup songs analyze --prompt \\\"Describe the production style\\\" --audio https://example.com/track.mp3\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Exactly one of \", _jsx(_components.code, {\n children: \"--preset\"\n }), \" or \", _jsx(_components.code, {\n children: \"--prompt\"\n }), \" is required, together with \", _jsx(_components.code, {\n children: \"--audio\"\n }), \". The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--preset \"\n })\n }), _jsx(_components.td, {\n children: \"Conditional\"\n }), _jsxs(_components.td, {\n children: [\"Curated analysis preset. Required when \", _jsx(_components.code, {\n children: \"--prompt\"\n }), \" is omitted.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--prompt \"\n })\n }), _jsx(_components.td, {\n children: \"Conditional\"\n }), _jsxs(_components.td, {\n children: [\"Custom text prompt. Required when \", _jsx(_components.code, {\n children: \"--preset\"\n }), \" is omitted.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--audio \"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--max-tokens \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Max tokens to generate (default 512).\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"content\",\n children: \"content\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Content creation pipeline — generate AI-powered social videos for artists.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"list-templates\",\n children: \"List templates\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content templates\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"validate-an-artist\",\n children: \"Validate an artist\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Check that an artist has the required assets before creating content. See \", _jsx(_components.a, {\n href: \"/api-reference/content/validate\",\n children: _jsx(_components.code, {\n children: \"GET /api/content/validate\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content validate --artist \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"estimate-cost\",\n children: \"Estimate cost\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Preview estimated cost and duration before kicking off the pipeline. See \", _jsx(_components.a, {\n href: \"/api-reference/content/estimate\",\n children: _jsx(_components.code, {\n children: \"GET /api/content/estimate\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content estimate\\nrecoup content estimate --lipsync --batch 2 --compare\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"create-content\",\n children: \"Create content\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Run the full content-creation pipeline for an artist. See \", _jsx(_components.a, {\n href: \"/api-reference/content/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/content/create\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content create --artist \\nrecoup content create --artist --template --lipsync --upscale\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--artist \"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Artist account ID\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--template \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Template name (default: random)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--lipsync\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Enable lipsync mode\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--upscale\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Enable upscaling\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--caption-length \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Max caption length in characters\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(Tip, {\n children: _jsxs(_components.p, {\n children: [\"For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the \", _jsx(_components.a, {\n href: \"/api-reference/content/generate-image\",\n children: \"content REST endpoints\"\n }), \" directly. Those primitives aren't yet exposed as individual CLI subcommands.\"]\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"CLI Install the Recoup CLI and interact with the platform from your terminal. Quickstart Getting started The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments. **The CLI is in beta.** The reference below follows the v0.1.15 source command set. Check `recoup --version` and `--help` for the package installed in your environment. For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up. **Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command. ## Install ## Authenticate Set your API key as an environment variable: Verify it works: Get an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) for instant key generation. ## Configuration | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `RECOUP_API_KEY` | Yes | — | Your Recoup API key | | `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override; set `https://api.recoupable.dev` to use the canonical API domain | All commands support `--json` for machine-readable output and `--help` for usage info. --- ## Commands ### whoami Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id). ### orgs List organizations. See [`GET /api/organizations`](/api-reference/organizations/list). ### artists List artists. See [`GET /api/artists`](/api-reference/artists/list). ### emails Send an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create). | Flag | Required | Description | |------|----------|-------------| | `--subject ` | No | Email subject line; defaults from the body when omitted | | `--text ` | No | Plain text or Markdown body | | `--html ` | No | Raw HTML body (takes precedence over `--text`) | | `--cc ` | No | CC recipient (repeatable) | | `--chat-id ` | No | Chat ID for a chat link in the email footer | | `--account ` | No | Send to a specific account (org keys only) | ### chats Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create). ### sandboxes Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create). ### tasks Check background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs). ### songs Run AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets). Exactly one of `--preset` or `--prompt` is required, together with `--audio`. The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API. | Flag | Required | Description | |------|----------|-------------| | `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. | | `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. | | `--audio ` | Yes | Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported. | | `--max-tokens ` | No | Max tokens to generate (default 512). | --- ## content Content creation pipeline — generate AI-powered social videos for artists. ### List templates ### Validate an artist Check that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate). ### Estimate cost Preview estimated cost and duration before kicking off the pipeline. See [`GET /api/content/estimate`](/api-reference/content/estimate). ### Create content Run the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create). | Flag | Required | Description | |------|----------|-------------| | `--artist ` | Yes | Artist account ID | | `--template ` | No | Template name (default: random) | | `--lipsync` | No | Enable lipsync mode | | `--upscale` | No | Enable upscaling | | `--caption-length ` | No | Max caption length in characters | For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands. "},{"slug":"claude","title":"Claude","description":"Connect Claude to Recoup and install optional workflow instructions.","category":"Quickstart","group":"Getting started","source":"claude.mdx","body":"Add `https://api.recoupable.dev/mcp` in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See [MCP OAuth](/mcp-oauth) for the dated client verification record and troubleshooting.\n\nAfter connecting, refresh tools and call the discovered `list_artists` tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account.\n\nFor workflow instructions, install the consolidated Recoup package from the [Recoup marketplace](https://github.com/recoupable/marketplace), using the manifest/package name shown there. Skills-only installation with `npx skills add recoupable/skills` does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed.\n\nMCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access.\n\nStart a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow.\n","headings":[],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Add \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for the dated client verification record and troubleshooting.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"After connecting, refresh tools and call the discovered \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For workflow instructions, install the consolidated Recoup package from the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketplace\",\n children: \"Recoup marketplace\"\n }), \", using the manifest/package name shown there. Skills-only installation with \", _jsx(_components.code, {\n children: \"npx skills add recoupable/skills\"\n }), \" does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"MCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Start a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Claude Connect Claude to Recoup and install optional workflow instructions. Quickstart Getting started Add `https://api.recoupable.dev/mcp` in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See [MCP OAuth](/mcp-oauth) for the dated client verification record and troubleshooting. After connecting, refresh tools and call the discovered `list_artists` tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account. For workflow instructions, install the consolidated Recoup package from the [Recoup marketplace](https://github.com/recoupable/marketplace), using the manifest/package name shown there. Skills-only installation with `npx skills add recoupable/skills` does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed. MCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access. Start a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow. "},{"slug":"mcp","title":"MCP","description":"Connect an agent to Recoup through OAuth and discover its authorized tools.","category":"Quickstart","group":"Getting started","source":"mcp.mdx","body":"Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](/mcp-oauth).\n\nUse `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result.\n\n`mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.\n\nSandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](/api-reference/sandboxes/create) with a separate authorized credential when required.\n\nFor an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.\n\n## Context results\n\nThe [Context reference](/api-reference/context/operate) pairs each supported action\nwith its success status, response model and synthetic request/result examples.\nUse the status declared for that action: `ingest` returns 202, while the specific\ncatalog, artist, release and text ingestion actions return 200. A 202 verification\nreceipt means queued after existing readiness checks, not completed work.\nHTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt;\ndelegated OAuth omits it. The examples do not verify hosted access or enable collection.\n\n## Plan a catalog lookup\n\nA catalog manager with an existing catalog Context request can plan a lookup for\nits current expanded recording members. Standard MCP uses `context` with\n`action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research`\nwith the same input fields and no `action`. Discover the tool in the connected\nclient before use; this source mapping does not prove hosted availability.\n\nChoose `recording_candidates`, `recording_work_candidates` or `platform_metadata`.\nThese plan possible recording matches, linked works or platform track information.\nThe response preserves the existing module values and node IDs, returns each node\nblocked and has `collectionPermitted: false`. It does not fetch data, verify rights,\nstart collection or grant spending permission. The [Context reference](/api-reference/context/operate)\nlists all accepted compatibility values, required IDs, page cursors and the complete response.\n\n## Continue a catalog case\n\nThe source contract adds `save_catalog_case`, `read_catalog_case` and\n`list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the\ntools in the connected host before using them. They also use the `context` tool\nwith the corresponding `action`. The catalog-case database and API release must\nbe deployed before this source contract is available.\n\nA case keeps versioned sources, assessments, findings, proposed actions, attempts\nand outcomes for the authorized workspace. No artist or ingestion request is\nrequired. The stored snapshot is `customer_assertion` evidence and always returns\n`external_actions: unsupported`: saving a record does not submit a registration,\nsend a claim, confirm a provider decision or verify a bank receipt.\n\nFor a new case, save with `expected_revision: 0` and `snapshot.revision: 0`.\nFor subsequent saves, use the current revision. Supply a unique idempotency key\nfor each new save. After an uncertain response, retry the unchanged payload with\nthe same key and expected revision.\nReads can withhold withdrawn evidence and its dependent records; explicitly\nreassemble a partial snapshot before another save. The [Context reference](/api-reference/context/operate)\ndefines the complete bounded schema, historical-source rules, revision conflicts,\nresponse fields and list pagination.\n\n## Check an application proposal\n\nThe pending standard MCP tool `validate_application_registration` checks an\nauthorized workspace's proposed name, environment, exact origins and return URLs.\nIt returns `persisted: false` and `origins_verified: false`; it does not register\nan application, prove domain ownership or issue application credentials.\nDelegated OAuth excludes this tool, including grants with `mcp:tools`. Discover\nit in a standard connection before use. See the [proposal preflight reference](/api-reference/applications/validate-registration)\nfor inputs, normal authentication effects and the limits of a successful result.\n\n## Release Packs\n\nWhen deployed and exposed by the current grant, the pack catalog includes\n`prepare_release_pack`, `get_release_pack`, `estimate_release_pack`,\n`generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and\n`export_release_pack`. These use the same account ownership, brief revisions,\ncomplete quotes and budget limits as REST. No existing artist or GitHub workspace\nis required. Use returned schemas and identifiers; preparation does not authorize\npaid generation. See [Release Packs](/release-packs) for first use and upload limits.\n","headings":[{"title":"Context results","id":"context-results"},{"title":"Plan a catalog lookup","id":"plan-a-catalog-lookup"},{"title":"Continue a catalog case","id":"continue-a-catalog-case"},{"title":"Check an application proposal","id":"check-an-application-proposal"},{"title":"Release Packs","id":"release-packs"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Connect your host to \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"OAuth setup guide\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"tools/list\"\n }), \" after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" and call it with its returned schema to verify access. An empty roster is a valid result.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sandbox command tools previously shown on this page are absent from the current registry. Do not call \", _jsx(_components.code, {\n children: \"prompt_sandbox\"\n }), \", \", _jsx(_components.code, {\n children: \"run_sandbox_command\"\n }), \", or infer that every REST endpoint is exposed as MCP. Use documented \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/create\",\n children: \"REST sandbox operations\"\n }), \" with a separate authorized credential when required.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For an API-key MCP connection, configure \", _jsx(_components.code, {\n children: \"Authorization: Bearer YOUR_RECOUP_API_KEY\"\n }), \" in the client's secret settings. The \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header is for \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"REST requests\"\n }), \". Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"context-results\",\n children: \"Context results\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \" pairs each supported action\\nwith its success status, response model and synthetic request/result examples.\\nUse the status declared for that action: \", _jsx(_components.code, {\n children: \"ingest\"\n }), \" returns 202, while the specific\\ncatalog, artist, release and text ingestion actions return 200. A 202 verification\\nreceipt means queued after existing readiness checks, not completed work.\\nHTTP/standard MCP \", _jsx(_components.code, {\n children: \"read\"\n }), \" may include a metadata-only \", _jsx(_components.code, {\n children: \"material_evidence\"\n }), \" receipt;\\ndelegated OAuth omits it. The examples do not verify hosted access or enable collection.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"plan-a-catalog-lookup\",\n children: \"Plan a catalog lookup\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A catalog manager with an existing catalog Context request can plan a lookup for\\nits current expanded recording members. Standard MCP uses \", _jsx(_components.code, {\n children: \"context\"\n }), \" with\\n\", _jsx(_components.code, {\n children: \"action: plan_catalog_members\"\n }), \"; delegated OAuth uses \", _jsx(_components.code, {\n children: \"plan_music_catalog_research\"\n }), \"\\nwith the same input fields and no \", _jsx(_components.code, {\n children: \"action\"\n }), \". Discover the tool in the connected\\nclient before use; this source mapping does not prove hosted availability.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Choose \", _jsx(_components.code, {\n children: \"recording_candidates\"\n }), \", \", _jsx(_components.code, {\n children: \"recording_work_candidates\"\n }), \" or \", _jsx(_components.code, {\n children: \"platform_metadata\"\n }), \".\\nThese plan possible recording matches, linked works or platform track information.\\nThe response preserves the existing module values and node IDs, returns each node\\nblocked and has \", _jsx(_components.code, {\n children: \"collectionPermitted: false\"\n }), \". It does not fetch data, verify rights,\\nstart collection or grant spending permission. The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \"\\nlists all accepted compatibility values, required IDs, page cursors and the complete response.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"continue-a-catalog-case\",\n children: \"Continue a catalog case\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The source contract adds \", _jsx(_components.code, {\n children: \"save_catalog_case\"\n }), \", \", _jsx(_components.code, {\n children: \"read_catalog_case\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"list_catalog_cases\"\n }), \" to standard MCP; delegated OAuth excludes them. Discover the\\ntools in the connected host before using them. They also use the \", _jsx(_components.code, {\n children: \"context\"\n }), \" tool\\nwith the corresponding \", _jsx(_components.code, {\n children: \"action\"\n }), \". The catalog-case database and API release must\\nbe deployed before this source contract is available.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A case keeps versioned sources, assessments, findings, proposed actions, attempts\\nand outcomes for the authorized workspace. No artist or ingestion request is\\nrequired. The stored snapshot is \", _jsx(_components.code, {\n children: \"customer_assertion\"\n }), \" evidence and always returns\\n\", _jsx(_components.code, {\n children: \"external_actions: unsupported\"\n }), \": saving a record does not submit a registration,\\nsend a claim, confirm a provider decision or verify a bank receipt.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a new case, save with \", _jsx(_components.code, {\n children: \"expected_revision: 0\"\n }), \" and \", _jsx(_components.code, {\n children: \"snapshot.revision: 0\"\n }), \".\\nFor subsequent saves, use the current revision. Supply a unique idempotency key\\nfor each new save. After an uncertain response, retry the unchanged payload with\\nthe same key and expected revision.\\nReads can withhold withdrawn evidence and its dependent records; explicitly\\nreassemble a partial snapshot before another save. The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \"\\ndefines the complete bounded schema, historical-source rules, revision conflicts,\\nresponse fields and list pagination.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"check-an-application-proposal\",\n children: \"Check an application proposal\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The pending standard MCP tool \", _jsx(_components.code, {\n children: \"validate_application_registration\"\n }), \" checks an\\nauthorized workspace's proposed name, environment, exact origins and return URLs.\\nIt returns \", _jsx(_components.code, {\n children: \"persisted: false\"\n }), \" and \", _jsx(_components.code, {\n children: \"origins_verified: false\"\n }), \"; it does not register\\nan application, prove domain ownership or issue application credentials.\\nDelegated OAuth excludes this tool, including grants with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \". Discover\\nit in a standard connection before use. See the \", _jsx(_components.a, {\n href: \"/api-reference/applications/validate-registration\",\n children: \"proposal preflight reference\"\n }), \"\\nfor inputs, normal authentication effects and the limits of a successful result.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"release-packs\",\n children: \"Release Packs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"When deployed and exposed by the current grant, the pack catalog includes\\n\", _jsx(_components.code, {\n children: \"prepare_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"get_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"estimate_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"generate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"retry_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"upload_release_pack_asset\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"export_release_pack\"\n }), \". These use the same account ownership, brief revisions,\\ncomplete quotes and budget limits as REST. No existing artist or GitHub workspace\\nis required. Use returned schemas and identifiers; preparation does not authorize\\npaid generation. See \", _jsx(_components.a, {\n href: \"/release-packs\",\n children: \"Release Packs\"\n }), \" for first use and upload limits.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"MCP Connect an agent to Recoup through OAuth and discover its authorized tools. Quickstart Getting started Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](/mcp-oauth). Use `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result. `mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access. Sandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](/api-reference/sandboxes/create) with a separate authorized credential when required. For an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST. ## Context results The [Context reference](/api-reference/context/operate) pairs each supported action with its success status, response model and synthetic request/result examples. Use the status declared for that action: `ingest` returns 202, while the specific catalog, artist, release and text ingestion actions return 200. A 202 verification receipt means queued after existing readiness checks, not completed work. HTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt; delegated OAuth omits it. The examples do not verify hosted access or enable collection. ## Plan a catalog lookup A catalog manager with an existing catalog Context request can plan a lookup for its current expanded recording members. Standard MCP uses `context` with `action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research` with the same input fields and no `action`. Discover the tool in the connected client before use; this source mapping does not prove hosted availability. Choose `recording_candidates`, `recording_work_candidates` or `platform_metadata`. These plan possible recording matches, linked works or platform track information. The response preserves the existing module values and node IDs, returns each node blocked and has `collectionPermitted: false`. It does not fetch data, verify rights, start collection or grant spending permission. The [Context reference](/api-reference/context/operate) lists all accepted compatibility values, required IDs, page cursors and the complete response. ## Continue a catalog case The source contract adds `save_catalog_case`, `read_catalog_case` and `list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the tools in the connected host before using them. They also use the `context` tool with the corresponding `action`. The catalog-case database and API release must be deployed before this source contract is available. A case keeps versioned sources, assessments, findings, proposed actions, attempts and outcomes for the authorized workspace. No artist or ingestion request is required. The stored snapshot is `customer_assertion` evidence and always returns `external_actions: unsupported`: saving a record does not submit a registration, send a claim, confirm a provider decision or verify a bank receipt. For a new case, save with `expected_revision: 0` and `snapshot.revision: 0`. For subsequent saves, use the current revision. Supply a unique idempotency key for each new save. After an uncertain response, retry the unchanged payload with the same key and expected revision. Reads can withhold withdrawn evidence and its dependent records; explicitly reassemble a partial snapshot before another save. The [Context reference](/api-reference/context/operate) defines the complete bounded schema, historical-source rules, revision conflicts, response fields and list pagination. ## Check an application proposal The pending standard MCP tool `validate_application_registration` checks an authorized workspace's proposed name, environment, exact origins and return URLs. It returns `persisted: false` and `origins_verified: false`; it does not register an application, prove domain ownership or issue application credentials. Delegated OAuth excludes this tool, including grants with `mcp:tools`. Discover it in a standard connection before use. See the [proposal preflight reference](/api-reference/applications/validate-registration) for inputs, normal authentication effects and the limits of a successful result. ## Release Packs When deployed and exposed by the current grant, the pack catalog includes `prepare_release_pack`, `get_release_pack`, `estimate_release_pack`, `generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and `export_release_pack`. These use the same account ownership, brief revisions, complete quotes and budget limits as REST. No existing artist or GitHub workspace is required. Use returned schemas and identifiers; preparation does not authorize paid generation. See [Release Packs](/release-packs) for first use and upload limits. "},{"slug":"mcp-oauth","title":"Connect an agent","description":"Connect an MCP client to Recoup with OAuth and account-authorized tools.","category":"Quickstart","group":"Getting started","source":"mcp-oauth.mdx","body":"Use this URL in your agent's remote MCP settings:\n\n```text\nhttps://api.recoupable.dev/mcp\n```\n\nSelect **OAuth**. Recoup supports [published client metadata (CIMD)](/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.\n\n## What your agent can do\n\nRequest **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.\n\nThe consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.\n\n| Permission | Access |\n| --- | --- |\n| `mcp:tools` | Full business-tool catalog across accessible workspaces |\n| `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` |\n| `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` |\n\nExisting limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience.\n\nOAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.\n\nEmail uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.\n\nThe platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.\n\nNew connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately.\n\nConnections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.\n\n## Claude\n\n1. Open **Customize → Connectors → Add custom connector**.\n2. Name it **Recoup** and enter the MCP URL above.\n3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR.\n4. Connect, sign in to Recoup, and select **Allow access**.\n5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.\n\nClaude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.\n\nClaude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).\n\n## ChatGPT\n\nIn the interface tested on October 7, 2026:\n\n1. Open **Plugins → Add → Add custom MCP server**.\n2. Enter **Recoup**, the MCP URL, and **OAuth**.\n3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access.\n4. Create the plugin, connect it, and complete Recoup consent.\n5. Start a chat with Recoup enabled and request an artist list.\n\nChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).\n\n## Codex\n\n```bash\ncodex mcp add recoup --url https://api.recoupable.dev/mcp\ncodex mcp login recoup --scopes mcp:tools\n```\n\nComplete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp).\n\n## Cursor\n\nAdd a remote server to your project's `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"recoup\": {\n \"url\": \"https://api.recoupable.dev/mcp\"\n }\n }\n}\n```\n\nOpen Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions.\n\n## Other agents and callbacks\n\nUse a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:\n\n- Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp`\n- Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth`\n- Resource: `https://api.recoupable.dev/mcp`\n\nRegister the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration.\n\nA generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.\n\n### Additional client setup paths\n\nThe following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.\n\n| Client | Setup and callback guidance |\n| --- | --- |\n| [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. |\n| [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. |\n| [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. |\n| [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost:/oauth/callback` unless configured otherwise. |\n| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. |\n| [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. |\n| [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. |\n| [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. |\n\nDocumented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.\n\n## Disconnect\n\nOpen [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.\n\n## Troubleshooting\n\n| Symptom | What to do |\n| --- | --- |\n| Custom connector option missing | Check your client's plan and workspace-admin permissions. |\n| Published identity / CIMD unavailable or fails | Check the [metadata requirements](/mcp-cimd), or choose automatic registration / DCR if your client offers it. |\n| Connection request expired | Restart Connect from the client; do not reuse an old consent URL. |\n| Wrong Recoup account | Use Switch before approving. |\n| Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. |\n| Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. |\n| Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. |\n| `401` after disconnect | Expected: reconnect and approve a new grant. |\n| `429` | Respect `Retry-After`; avoid repeated registration attempts. |\n| `503` | Retry later; do not weaken authentication or callback checks. |\n| Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. |\n\nFor clients without OAuth, [API-key authentication](/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.\n\nFor help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys.\n\nFull OAuth MCP calls currently share account-level limits of 120 calls per minute\nand 30 calls per tool per minute across connected clients. See the\n[pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts).\nThe `compact_chats` MCP tool accepts up to 50 chats per call under the\n[pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts);\nthis is an MCP limit, not a claimed REST request limit.\n","headings":[{"title":"What your agent can do","id":"what-your-agent-can-do"},{"title":"Claude","id":"claude"},{"title":"ChatGPT","id":"chatgpt"},{"title":"Codex","id":"codex"},{"title":"Cursor","id":"cursor"},{"title":"Other agents and callbacks","id":"other-agents-and-callbacks"},{"title":"Disconnect","id":"disconnect"},{"title":"Troubleshooting","id":"troubleshooting"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Use this URL in your agent's remote MCP settings:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-text\",\n children: \"https://api.recoupable.dev/mcp\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Select \", _jsx(_components.strong, {\n children: \"OAuth\"\n }), \". Recoup supports \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"published client metadata (CIMD)\"\n }), \" and \", _jsx(_components.strong, {\n children: \"automatic registration\"\n }), \" (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-your-agent-can-do\",\n children: \"What your agent can do\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Request \", _jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"mcp:tools\"\n })\n }), \" for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Permission\"\n }), _jsx(_components.th, {\n children: \"Access\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:tools\"\n })\n }), _jsx(_components.td, {\n children: \"Full business-tool catalog across accessible workspaces\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:read\"\n })\n }), _jsxs(_components.td, {\n children: [\"Original personal-only \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \", \", _jsx(_components.code, {\n children: \"get_artist_socials\"\n }), \", \", _jsx(_components.code, {\n children: \"get_chats\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:write\"\n })\n }), _jsxs(_components.td, {\n children: [\"Original personal-only \", _jsx(_components.code, {\n children: \"create_new_artist\"\n }), \", \", _jsx(_components.code, {\n children: \"update_account_info\"\n })]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Existing limited grants do \", _jsx(_components.strong, {\n children: \"not\"\n }), \" expand automatically. Reconnect with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \", review the broader permission, and refresh your client's tool catalog. Clients requesting the \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" + \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" pair keep the five-tool experience.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"OAuth never exposes \", _jsx(_components.code, {\n children: \"get_api_key\"\n }), \": it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. \", _jsx(_components.code, {\n children: \"create_knowledge_base\"\n }), \" and \", _jsx(_components.code, {\n children: \"generate_txt_file\"\n }), \" publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound \", _jsx(_components.code, {\n children: \"id\"\n }), \"; pass that entire value as \", _jsx(_components.code, {\n children: \"video_id\"\n }), \" to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/oauth/connections\",\n children: \"Connected agents\"\n }), \" to revoke its access and refresh tokens immediately.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"claude\",\n children: \"Claude\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Open \", _jsx(_components.strong, {\n children: \"Customize → Connectors → Add custom connector\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Name it \", _jsx(_components.strong, {\n children: \"Recoup\"\n }), \" and enter the MCP URL above.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Choose \", _jsx(_components.strong, {\n children: \"Sign in now\"\n }), \". \", _jsx(_components.strong, {\n children: \"Register automatically\"\n }), \" uses DCR; \", _jsx(_components.strong, {\n children: \"published identity\"\n }), \" uses CIMD. The production client tests below used DCR.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Connect, sign in to Recoup, and select \", _jsx(_components.strong, {\n children: \"Allow access\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See \", _jsx(_components.a, {\n href: \"https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp\",\n children: \"Claude's remote connector guide\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"chatgpt\",\n children: \"ChatGPT\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"In the interface tested on October 7, 2026:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Open \", _jsx(_components.strong, {\n children: \"Plugins → Add → Add custom MCP server\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Enter \", _jsx(_components.strong, {\n children: \"Recoup\"\n }), \", the MCP URL, and \", _jsx(_components.strong, {\n children: \"OAuth\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Under advanced OAuth settings, confirm \", _jsx(_components.strong, {\n children: \"Dynamic Client Registration (DCR)\"\n }), \" and request \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for full access.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Create the plugin, connect it, and complete Recoup consent.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Start a chat with Recoup enabled and request an artist list.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see \", _jsx(_components.a, {\n href: \"https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt\",\n children: \"OpenAI's MCP setup documentation\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"codex\",\n children: \"Codex\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"codex mcp add recoup --url https://api.recoupable.dev/mcp\\ncodex mcp login recoup --scopes mcp:tools\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See \", _jsx(_components.a, {\n href: \"https://developers.openai.com/codex/mcp\",\n children: \"Codex MCP configuration\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"cursor\",\n children: \"Cursor\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Add a remote server to your project's \", _jsx(_components.code, {\n children: \".cursor/mcp.json\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"mcpServers\\\": {\\n \\\"recoup\\\": {\\n \\\"url\\\": \\\"https://api.recoupable.dev/mcp\\\"\\n }\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See \", _jsx(_components.a, {\n href: \"https://cursor.com/docs/mcp\",\n children: \"Cursor's MCP guide\"\n }), \" for the current setup and workspace restrictions.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"other-agents-and-callbacks\",\n children: \"Other agents and callbacks\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Resource metadata: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Authorization-server metadata: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Resource: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute \", _jsx(_components.code, {\n children: \"localhost\"\n }), \" for \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \" or edit a callback after registration.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"CIMD requirements and verification status\"\n }), \". Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"additional-client-setup-paths\",\n children: \"Additional client setup paths\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The following paths were reviewed in official client documentation on October 7, 2026. \", _jsx(_components.strong, {\n children: \"They have not been tested end to end against Recoup.\"\n }), \" Use automatic registration and request \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for full access, or \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" / \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Client\"\n }), _jsx(_components.th, {\n children: \"Setup and callback guidance\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors\",\n children: \"Perplexity\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are \", _jsx(_components.code, {\n children: \"https://www.perplexity.ai/rest/connections/oauth_callback\"\n }), \" and, for enterprise, \", _jsx(_components.code, {\n children: \"https://enterprise.perplexity.ai/rest/connections/oauth_callback\"\n }), \".\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://code.claude.com/docs/en/mcp\",\n children: \"Claude Code\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add Recoup as an HTTP server and authenticate through \", _jsx(_components.code, {\n children: \"/mcp\"\n }), \" inside Claude Code. Automatic registration uses a localhost callback; \", _jsx(_components.code, {\n children: \"--callback-port\"\n }), \" can fix its port when required.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization\",\n children: \"VS Code\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add an HTTP server in \", _jsx(_components.code, {\n children: \".vscode/mcp.json\"\n }), \". OAuth supports DCR; documented callbacks include \", _jsx(_components.code, {\n children: \"http://127.0.0.1:33418\"\n }), \" and \", _jsx(_components.code, {\n children: \"https://vscode.dev/redirect\"\n }), \". Preserve the callback supplied by your VS Code surface.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://geminicli.com/docs/tools/mcp-server/\",\n children: \"Gemini CLI\"\n })\n }), _jsxs(_components.td, {\n children: [\"Configure the MCP URL as \", _jsx(_components.code, {\n children: \"httpUrl\"\n }), \" and authenticate with \", _jsx(_components.code, {\n children: \"/mcp auth recoup\"\n }), \" inside the Gemini CLI chat. DCR uses \", _jsx(_components.code, {\n children: \"http://localhost:/oauth/callback\"\n }), \" unless configured otherwise.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://opencode.ai/docs/mcp-servers/\",\n children: \"OpenCode\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add a remote MCP server and run \", _jsx(_components.code, {\n children: \"opencode mcp auth recoup\"\n }), \". OAuth supports automatic registration. Let the client supply its callback.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://kiro.dev/docs/mcp/configuration/\",\n children: \"Kiro\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add the remote MCP URL and use DCR. Set \", _jsx(_components.code, {\n children: \"oauth.oauthScopes\"\n }), \" to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://docs.n8n.io/integrations/builtin/credentials/mcp/\",\n children: \"n8n\"\n })\n }), _jsxs(_components.td, {\n children: [\"Create an MCP OAuth credential with \", _jsx(_components.strong, {\n children: \"Use Dynamic Client Registration\"\n }), \" enabled. Use the exact callback shown by your n8n instance.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent\",\n children: \"Copilot Studio\"\n })\n }), _jsx(_components.td, {\n children: \"Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio.\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"disconnect\",\n children: \"Disconnect\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Open \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/oauth/connections\",\n children: \"Connected agents\"\n }), \" and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"troubleshooting\",\n children: \"Troubleshooting\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Symptom\"\n }), _jsx(_components.th, {\n children: \"What to do\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Custom connector option missing\"\n }), _jsx(_components.td, {\n children: \"Check your client's plan and workspace-admin permissions.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Published identity / CIMD unavailable or fails\"\n }), _jsxs(_components.td, {\n children: [\"Check the \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"metadata requirements\"\n }), \", or choose automatic registration / DCR if your client offers it.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Connection request expired\"\n }), _jsx(_components.td, {\n children: \"Restart Connect from the client; do not reuse an old consent URL.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Wrong Recoup account\"\n }), _jsx(_components.td, {\n children: \"Use Switch before approving.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Still seeing only five tools\"\n }), _jsxs(_components.td, {\n children: [\"Reconnect requesting \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \", approve full access, then refresh the client tool catalog.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Connected but no tool access\"\n }), _jsx(_components.td, {\n children: \"Check selected scopes, individual tool approvals, and whether the grant expired or was revoked.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Organization artist missing\"\n }), _jsxs(_components.td, {\n children: [\"Reconnect with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" and verify your organization membership.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"401\"\n }), \" after disconnect\"]\n }), _jsx(_components.td, {\n children: \"Expected: reconnect and approve a new grant.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"429\"\n })\n }), _jsxs(_components.td, {\n children: [\"Respect \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \"; avoid repeated registration attempts.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"503\"\n })\n }), _jsx(_components.td, {\n children: \"Retry later; do not weaken authentication or callback checks.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Write timed out\"\n }), _jsx(_components.td, {\n children: \"Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate.\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For clients without OAuth, \", _jsx(_components.a, {\n href: \"/mcp\",\n children: \"API-key authentication\"\n }), \" remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For help, contact \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \". Include the client name, time, and error text; never include tokens, passwords, or API keys.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Full OAuth MCP calls currently share account-level limits of 120 calls per minute\\nand 30 calls per tool per minute across connected clients. See the\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts\",\n children: \"pinned rate-limit implementation\"\n }), \".\\nThe \", _jsx(_components.code, {\n children: \"compact_chats\"\n }), \" MCP tool accepts up to 50 chats per call under the\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts\",\n children: \"pinned MCP guard\"\n }), \";\\nthis is an MCP limit, not a claimed REST request limit.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Connect an agent Connect an MCP client to Recoup with OAuth and account-authorized tools. Quickstart Getting started Use this URL in your agent's remote MCP settings: Select **OAuth**. Recoup supports [published client metadata (CIMD)](/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied. ## What your agent can do Request **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support. The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound. | Permission | Access | | --- | --- | | `mcp:tools` | Full business-tool catalog across accessible workspaces | | `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` | | `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` | Existing limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience. OAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog. Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs. The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification. New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately. Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected. ## Claude 1. Open **Customize → Connectors → Add custom connector**. 2. Name it **Recoup** and enter the MCP URL above. 3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR. 4. Connect, sign in to Recoup, and select **Allow access**. 5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted. Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward. Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). ## ChatGPT In the interface tested on October 7, 2026: 1. Open **Plugins → Add → Add custom MCP server**. 2. Enter **Recoup**, the MCP URL, and **OAuth**. 3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access. 4. Create the plugin, connect it, and complete Recoup consent. 5. Start a chat with Recoup enabled and request an artist list. ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt). ## Codex Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp). ## Cursor Add a remote server to your project's `.cursor/mcp.json`: Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions. ## Other agents and callbacks Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes: - Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp` - Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth` - Resource: `https://api.recoupable.dev/mcp` Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration. A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only. ### Additional client setup paths The following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist. | Client | Setup and callback guidance | | --- | --- | | [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. | | [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. | | [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. | | [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost: /oauth/callback` unless configured otherwise. | | [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. | | [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. | | [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. | | [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. | Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access. ## Disconnect Open [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again. ## Troubleshooting | Symptom | What to do | | --- | --- | | Custom connector option missing | Check your client's plan and workspace-admin permissions. | | Published identity / CIMD unavailable or fails | Check the [metadata requirements](/mcp-cimd), or choose automatic registration / DCR if your client offers it. | | Connection request expired | Restart Connect from the client; do not reuse an old consent URL. | | Wrong Recoup account | Use Switch before approving. | | Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. | | Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. | | Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. | | `401` after disconnect | Expected: reconnect and approve a new grant. | | `429` | Respect `Retry-After`; avoid repeated registration attempts. | | `503` | Retry later; do not weaken authentication or callback checks. | | Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. | For clients without OAuth, [API-key authentication](/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command. For help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys. Full OAuth MCP calls currently share account-level limits of 120 calls per minute and 30 calls per tool per minute across connected clients. See the [pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts). The `compact_chats` MCP tool accepts up to 50 chats per call under the [pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts); this is an MCP limit, not a claimed REST request limit. "},{"slug":"mcp-cimd","title":"Published client metadata (CIMD)","description":"Connect using an HTTPS client identity without dynamic registration.","category":"Quickstart","group":"Getting started","source":"mcp-cimd.mdx","body":"Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth `client_id`. Recoup retrieves that document and validates the client's callbacks before asking you to approve access.\n\nUse the same MCP server URL: `https://api.recoupable.dev/mcp`. A compatible client can discover CIMD through `client_id_metadata_document_supported: true` in Recoup's [authorization-server metadata](https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth). No vendor-specific registration or callback allowlist is needed.\n\n## Access and trust\n\nCIMD uses the same [permissions and consent](/mcp-oauth) as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work.\n\nA client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account.\n\n## Client requirements\n\n- Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected.\n- Set `client_id` to the exact document URL and include `client_name` and `redirect_uris`.\n- Use a document URL with an explicit path and without credentials, fragments, or dot path segments.\n- Use authorization code flow with PKCE S256 and `mcp:tools` for the full Recoup catalog, or `mcp:read` / `mcp:write` for the original limited personal tools.\n- Public clients should set `token_endpoint_auth_method` to `none`. Never publish client secrets or private keys.\n- Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. `localhost` and `127.0.0.1` remain different hosts.\n\nRecoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy.\n\nMetadata caching respects freshness headers up to five minutes. `no-store`, `no-cache`, absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata.\n\n## Verification status\n\nThe implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits.\n\nA local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on [Connect an agent](/mcp-oauth) were obtained using DCR.\n\nProduction verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified.\n\nIf a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored.\n\nSee the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and [CIMD draft 02](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html). CIMD remains a draft specification; Recoup's provider currently implements draft 02.\n","headings":[{"title":"Access and trust","id":"access-and-trust"},{"title":"Client requirements","id":"client-requirements"},{"title":"Verification status","id":"verification-status"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth \", _jsx(_components.code, {\n children: \"client_id\"\n }), \". Recoup retrieves that document and validates the client's callbacks before asking you to approve access.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the same MCP server URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \". A compatible client can discover CIMD through \", _jsx(_components.code, {\n children: \"client_id_metadata_document_supported: true\"\n }), \" in Recoup's \", _jsx(_components.a, {\n href: \"https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth\",\n children: \"authorization-server metadata\"\n }), \". No vendor-specific registration or callback allowlist is needed.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"access-and-trust\",\n children: \"Access and trust\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"CIMD uses the same \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"permissions and consent\"\n }), \" as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"client-requirements\",\n children: \"Client requirements\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Set \", _jsx(_components.code, {\n children: \"client_id\"\n }), \" to the exact document URL and include \", _jsx(_components.code, {\n children: \"client_name\"\n }), \" and \", _jsx(_components.code, {\n children: \"redirect_uris\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Use a document URL with an explicit path and without credentials, fragments, or dot path segments.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use authorization code flow with PKCE S256 and \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for the full Recoup catalog, or \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" / \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" for the original limited personal tools.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Public clients should set \", _jsx(_components.code, {\n children: \"token_endpoint_auth_method\"\n }), \" to \", _jsx(_components.code, {\n children: \"none\"\n }), \". Never publish client secrets or private keys.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. \", _jsx(_components.code, {\n children: \"localhost\"\n }), \" and \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \" remain different hosts.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Recoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Metadata caching respects freshness headers up to five minutes. \", _jsx(_components.code, {\n children: \"no-store\"\n }), \", \", _jsx(_components.code, {\n children: \"no-cache\"\n }), \", absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"verification-status\",\n children: \"Verification status\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"Connect an agent\"\n }), \" were obtained using DCR.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Production verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See the \", _jsx(_components.a, {\n href: \"https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization\",\n children: \"MCP authorization specification\"\n }), \" and \", _jsx(_components.a, {\n href: \"https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html\",\n children: \"CIMD draft 02\"\n }), \". CIMD remains a draft specification; Recoup's provider currently implements draft 02.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Published client metadata (CIMD) Connect using an HTTPS client identity without dynamic registration. Quickstart Getting started Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth `client_id`. Recoup retrieves that document and validates the client's callbacks before asking you to approve access. Use the same MCP server URL: `https://api.recoupable.dev/mcp`. A compatible client can discover CIMD through `client_id_metadata_document_supported: true` in Recoup's [authorization-server metadata](https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth). No vendor-specific registration or callback allowlist is needed. ## Access and trust CIMD uses the same [permissions and consent](/mcp-oauth) as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work. A client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account. ## Client requirements - Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected. - Set `client_id` to the exact document URL and include `client_name` and `redirect_uris`. - Use a document URL with an explicit path and without credentials, fragments, or dot path segments. - Use authorization code flow with PKCE S256 and `mcp:tools` for the full Recoup catalog, or `mcp:read` / `mcp:write` for the original limited personal tools. - Public clients should set `token_endpoint_auth_method` to `none`. Never publish client secrets or private keys. - Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. `localhost` and `127.0.0.1` remain different hosts. Recoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy. Metadata caching respects freshness headers up to five minutes. `no-store`, `no-cache`, absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata. ## Verification status The implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits. A local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on [Connect an agent](/mcp-oauth) were obtained using DCR. Production verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified. If a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored. See the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and [CIMD draft 02](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html). CIMD remains a draft specification; Recoup's provider currently implements draft 02. "},{"slug":"authentication","title":"Authentication","description":"How authentication works in the Recoup API — API keys, access tokens, and organization access control.","category":"Quickstart","group":"Getting started","source":"authentication.mdx","body":"## Overview\n\nEvery request to the Recoup API must be authenticated using exactly one of two mechanisms:\n\n| Method | Header | Use case |\n|--------|--------|----------|\n| API Key | `x-api-key` | Server-to-server integrations |\n| Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy |\n\nProviding both headers in the same request will result in a `401` error.\n\n\nAgent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details.\n\n\n---\n\n## API Keys\n\nAPI 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.\n\n### Creating an API Key\n\n1. Navigate to [chat.recoupable.dev/keys](https://chat.recoupable.dev/keys)\n2. Enter a descriptive name (e.g. `\"Production Server\"`)\n3. Click **Create API Key**\n\n\nCopy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation.\n\n\n### Using an API Key\n\nPass your key in the `x-api-key` header:\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n### Access to Organizations\n\nIf 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.\n\n- **No org membership** — the key can only access its own account's data\n- **Org member** — the key can pass `account_id` to filter to any account within that organization\n\n\nOrg 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.\n\n\n---\n\n## Access Tokens (Privy)\n\nIf 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.\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"Authorization: Bearer YOUR_PRIVY_JWT\"\n```\n\nThe 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.\n\n---\n\n## How We Verify Access on API Calls\n\nEvery authenticated request goes through `validateAuthContext`, which enforces the following access rules:\n\n### API Key or Bearer Token\n\nBy default, requests access the key owner's own account. When `account_id` is provided:\n\n```\nRequest includes account_id override?\n ├── Same as key owner → Allowed (self-access)\n ├── Key owner is a member of an org that contains account_id → Allowed\n └── No matching org membership → 403 Forbidden\n```\n\nMembership 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.\n\n\nThe Recoup internal admin organization has universal access to all accounts.\n\n\n### Organization Access via `organization_id`\n\nSome endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either:\n\n- A **member** of the organization, or\n- The **organization account itself**\n\n---\n\n## Error Responses\n\n| Status | Cause |\n|--------|-------|\n| `401` | Missing or invalid credentials, or both `x-api-key` and `Authorization` headers provided |\n| `403` | Valid credentials but insufficient access to the requested `account_id` or `organization_id` |\n\n---\n\n## Security Notes\n\n- API keys are **never stored in plaintext** — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database\n- **Never include `account_id` in your API key creation request** — the account is always derived from your authenticated credentials\n- Rotate keys immediately if compromised via the [API Keys Management Page](https://chat.recoupable.dev/keys)\n\n## MCP OAuth and REST credentials\n\nRemote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See [MCP OAuth](/mcp-oauth).\n","headings":[{"title":"Overview","id":"overview"},{"title":"API Keys","id":"api-keys"},{"title":"Access Tokens (Privy)","id":"access-tokens-privy"},{"title":"How We Verify Access on API Calls","id":"how-we-verify-access-on-api-calls"},{"title":"Error Responses","id":"error-responses"},{"title":"Security Notes","id":"security-notes"},{"title":"MCP OAuth and REST credentials","id":"mcp-oauth-and-rest-credentials"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n }, {Info, Note, Warning} = _components;\n if (!Info) _missingMdxReference(\"Info\", true);\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"overview\",\n children: \"Overview\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Every request to the Recoup API must be authenticated using exactly one of two mechanisms:\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Method\"\n }), _jsx(_components.th, {\n children: \"Header\"\n }), _jsx(_components.th, {\n children: \"Use case\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"API Key\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"x-api-key\"\n })\n }), _jsx(_components.td, {\n children: \"Server-to-server integrations\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Access Token\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"Authorization: Bearer \"\n })\n }), _jsx(_components.td, {\n children: \"Frontend apps authenticated via Privy\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Providing both headers in the same request will result in a \", _jsx(_components.code, {\n children: \"401\"\n }), \" error.\"]\n }), \"\\n\", _jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"Agent onboarding endpoints (\", _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" and \", _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \") are \", _jsx(_components.strong, {\n children: \"unauthenticated\"\n }), \" — they exist so agents can obtain their first API key. See the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents guide\"\n }), \" for details.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"api-keys\",\n children: \"API Keys\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are \", _jsx(_components.strong, {\n children: \"personal keys\"\n }), \" — they are always tied to the account that created them.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"creating-an-api-key\",\n children: \"Creating an API Key\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"chat.recoupable.dev/keys\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Enter a descriptive name (e.g. \", _jsx(_components.code, {\n children: \"\\\"Production Server\\\"\"\n }), \")\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Click \", _jsx(_components.strong, {\n children: \"Create API Key\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"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.\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"using-an-api-key\",\n children: \"Using an API Key\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass your key in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"access-to-organizations\",\n children: \"Access to Organizations\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If your account belongs to one or more organizations, your API key can access data across those organizations by passing an \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" parameter on supported endpoints. This lets you filter to any account within an organization your key has access to.\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"No org membership\"\n }), \" — the key can only access its own account's data\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Org member\"\n }), \" — the key can pass \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" to filter to any account within that organization\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Info, {\n children: _jsxs(_components.p, {\n children: [\"Org membership is determined by the account's \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: \"organizations\"\n }), \". An account gains access to an org when it is added as a member.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"access-tokens-privy\",\n children: \"Access Tokens (Privy)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you're building a frontend application that authenticates users via \", _jsx(_components.a, {\n href: \"https://privy.io\",\n children: \"Privy\"\n }), \", you can pass the user's Privy JWT as a Bearer token instead of an API key.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"Authorization: Bearer YOUR_PRIVY_JWT\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"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.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"how-we-verify-access-on-api-calls\",\n children: \"How We Verify Access on API Calls\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Every authenticated request goes through \", _jsx(_components.code, {\n children: \"validateAuthContext\"\n }), \", which enforces the following access rules:\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"api-key-or-bearer-token\",\n children: \"API Key or Bearer Token\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"By default, requests access the key owner's own account. When \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" is provided:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"Request includes account_id override?\\n ├── Same as key owner → Allowed (self-access)\\n ├── Key owner is a member of an org that contains account_id → Allowed\\n └── No matching org membership → 403 Forbidden\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Membership is verified by checking the key owner's \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: \"organizations\"\n }), \" for a record linking the account to the target account's organization.\"]\n }), \"\\n\", _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"The Recoup internal admin organization has universal access to all accounts.\"\n })\n }), \"\\n\", _jsxs(_components.h3, {\n id: \"organization-access-via-organizationid\",\n children: [\"Organization Access via \", _jsx(_components.code, {\n children: \"organization_id\"\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Some endpoints accept an \", _jsx(_components.code, {\n children: \"organization_id\"\n }), \" parameter. When provided, the API additionally validates that the authenticated account is either:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"A \", _jsx(_components.strong, {\n children: \"member\"\n }), \" of the organization, or\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The \", _jsx(_components.strong, {\n children: \"organization account itself\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"error-responses\",\n children: \"Error Responses\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Status\"\n }), _jsx(_components.th, {\n children: \"Cause\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"401\"\n })\n }), _jsxs(_components.td, {\n children: [\"Missing or invalid credentials, or both \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" and \", _jsx(_components.code, {\n children: \"Authorization\"\n }), \" headers provided\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"403\"\n })\n }), _jsxs(_components.td, {\n children: [\"Valid credentials but insufficient access to the requested \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" or \", _jsx(_components.code, {\n children: \"organization_id\"\n })]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"security-notes\",\n children: \"Security Notes\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"API keys are \", _jsx(_components.strong, {\n children: \"never stored in plaintext\"\n }), \" — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsxs(_components.strong, {\n children: [\"Never include \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" in your API key creation request\"]\n }), \" — the account is always derived from your authenticated credentials\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Rotate keys immediately if compromised via the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys Management Page\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"mcp-oauth-and-rest-credentials\",\n children: \"MCP OAuth and REST credentials\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Remote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Authentication How authentication works in the Recoup API — API keys, access tokens, and organization access control. Quickstart Getting started ## Overview Every request to the Recoup API must be authenticated using exactly one of two mechanisms: | Method | Header | Use case | |--------|--------|----------| | API Key | `x-api-key` | Server-to-server integrations | | Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy | Providing both headers in the same request will result in a `401` error. Agent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details. --- ## 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.dev/keys](https://chat.recoupable.dev/keys) 2. Enter a descriptive name (e.g. `\"Production Server\"`) 3. Click **Create API Key** Copy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation. ### Using an API Key Pass your key in the `x-api-key` header: ### 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 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. --- ## Access Tokens (Privy) If you're building a frontend application that authenticates users via [Privy](https://privy.io), you can pass the user's Privy JWT as a Bearer token instead of an API key. 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. --- ## How We Verify Access on API Calls Every authenticated request goes through `validateAuthContext`, which enforces the following access rules: ### API Key or Bearer Token By default, requests access the key owner's own account. When `account_id` is provided: Membership is verified by checking the key owner's [organizations](/api-reference/organizations/list) for a record linking the account to the target account's organization. The Recoup internal admin organization has universal access to all accounts. ### Organization Access via `organization_id` Some endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either: - A **member** of the organization, or - The **organization account itself** --- ## Error Responses | 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.dev/keys) ## MCP OAuth and REST credentials Remote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See [MCP OAuth](/mcp-oauth). "},{"slug":"credits","title":"Credits","description":"How Recoup credits work — what's billed, how to check your balance, and how to upgrade.","category":"Quickstart","group":"Getting started","source":"credits.mdx","body":"Some Recoup endpoints are billed in **credits** — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates.\n\n---\n\n## What's billed\n\n| Family | Billed? | Notes |\n|--------|---------|-------|\n| **Research** ([`/api/research/*`](/api-reference/research/web)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). |\n| **Content generation** ([`/api/content/image`](/api-reference/content/generate-image), [`video`](/api-reference/content/generate-video), upscale, transcribe and analyze) | Yes | Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory. |\n| **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. |\n| **Music analysis** ([`POST /api/songs/analyze`](/api-reference/songs/analyze)) | Yes | \\$0.05 per model call plus \\$0.001166 per second of inference time; `full_report` is the sum of its 13 calls. |\n| **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | \\$0.05, plus \\$0.01 per post requested via `posts` — per social profile scraped. |\n| **Other operations** | Consult the endpoint contract | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. |\n\nUpstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient.\n\n---\n\n## What a credit is worth\n\n**Balances and prices are US dollars.** The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: `1,000,000 = $1.00`, so it can carry sub-cent charges (a \\$0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get).\n\n---\n\n## Check your balance\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/credits \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nResponse shape:\n\n```json\n{\n \"account_id\": \"11111111-1111-4111-8111-111111111111\",\n \"remaining_credits\": 292450000,\n \"total_credits\": 300000000,\n \"used_credits\": 7550000,\n \"is_pro\": true,\n \"plan\": \"pro\",\n \"task_limit\": null,\n \"min_cadence_minutes\": 60,\n \"timestamp\": \"2026-10-01T12:00:00Z\"\n}\n```\n\n`plan`, `task_limit`, and `min_cadence_minutes` describe the [plan](#subscription) the balance belongs to. `total_credits` is your plan-derived monthly allotment. `remaining_credits` can exceed `total_credits` after a top-up or an admin grant, and `used_credits` clamps to 0 in that case. Full schema at [Get Account Credits](/api-reference/accounts/credits-get).\n\n### Plan response examples\n\n`is_pro` on credits and `isPro` on subscriptions mean effective Pro, so both are\nfalse for paid Starter. Use `plan` to distinguish Starter from Free. The credits\nresponse reports the effective allowance; the [subscription response](/api-reference/accounts/subscription-get)\nseparately identifies whether it comes from the account or an organization.\n\n| Situation | Credits `plan` / `is_pro` | Subscription `source` | Task limit / minimum cadence |\n| --- | --- | --- | --- |\n| Free | `free` / `false` | `null` | 1 / weekly |\n| Paid Starter | `starter` / `false` | `account` | 3 / daily |\n| Direct Pro | `pro` / `true` | `account` | `null` (unlimited) / hourly |\n| Starter account with organization Pro | `pro` / `true` | `organization` | `null` (unlimited) / hourly |\n| Inactive subscription without another paid entitlement | `free` / `false` | `null` | 1 / weekly |\n\nFor example, a Pro balance of 325,000,000 against an allowance of 300,000,000\nreturns `used_credits: 0`. The API preserves a signed balance: a negative balance\ncan make this display exceed the allowance. This is not a ledger of charges.\nA null timestamp means the timestamp is unavailable, not proof of no prior activity.\nAn inactive subscription resolves to `status: \"none\"` and null subscription/billing\nfields; this endpoint does not return the canceled subscription's history. Billing\ndetails may also be unavailable on an active response. Named reference examples\nillustrate these states without quoting an available offer or a live payment.\n\nTo see what consumed the balance, list the charges line by line with [`GET /api/accounts/{id}/usage`](/api-reference/accounts/usage-get): one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in `model_id` (for example `POST /api/artist/socials/scrape`), so a list of charges reads as a list of calls.\n\n---\n\n## Subscription\n\nFor Platform, Advisory, Build + Partner, and Enterprise options, see [Recoup pricing](https://recoupable.dev/pricing). API and MCP usage is billed separately through credits.\n\nYour account's current credit allowance and scheduled-task limits are returned by [Get Account Credits](/api-reference/accounts/credits-get). Use `total_credits`, `task_limit`, and `min_cadence_minutes` from that response rather than inferring limits from a public plan name.\n\nThe API may return account identifiers such as `free`, `starter`, or `pro`. These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint.\n\n### Task limits\n\n[`POST /api/tasks`](/api-reference/tasks/create) and [`PATCH /api/tasks`](/api-reference/tasks/update) [check the plan](/api-reference/accounts/credits-get) before writing. Creating a task past `task_limit`, re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than `min_cadence_minutes` returns **HTTP 402** with `error: \"plan_limit\"`:\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"plan_limit\",\n \"limit\": \"task_count\",\n \"message\": \"Free includes 1 task. Starter includes 3, Pro is unlimited.\",\n \"plan\": \"free\",\n \"task_limit\": 1,\n \"min_cadence_minutes\": 10080,\n \"current_task_count\": 1,\n \"billingUrl\": \"https://app.recoupable.dev/plan\"\n}\n```\n\n`limit` is `task_count` or `min_cadence`; `current_task_count` excludes the task being created or updated. Edits that only touch `title`, `prompt`, or `model` never hit the gate.\n\n### Monthly refill\n\nThe refill is a **floor, not an assignment.** It raises `remaining_credits` up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a [top-up](#one-time-top-ups) or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar.\n\nThe refill is lazy rather than scheduled: it applies on the next read of [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get) once your credits row is more than a month old. The balance you read is always the refilled one.\n\n### Manage your subscription\n\nSign in to your [account billing page](https://app.recoupable.dev/plan) to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in [Create Subscription Session](/api-reference/subscriptions/sessions-create) and open its returned checkout URL. Review the price and billing terms before completing checkout.\n\nAdvisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment.\n\n### Check your tier\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/subscription \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nGet `$ACCOUNT_ID` from [`GET /api/accounts/id`](/api-reference/accounts/id) if you don't already have it. Response includes `isPro` (boolean), `status`, `plan`, and `source` (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at [Get Subscription](/api-reference/accounts/subscription-get).\n\n### One-time top-ups\n\nYou can purchase credits any time via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create). The endpoint adapts to what's on the account:\n\n- **Card on file → silent auto-charge.** Recoup charges your saved Stripe card off-session and returns `paymentIntentId`, `creditsPurchased`, and `totalCents`. Credits land within seconds.\n- **No card, or Stripe declines the saved card → Stripe Checkout fallback.** The response contains a Checkout `url` you open in the browser. When Stripe specifically declined a saved card, the response also includes a `declineReason` (e.g. `insufficient_funds`, `expired_card`) so you can explain *why* before sending the customer to update billing.\n\n```bash\ncurl -sS -X POST https://api.recoupable.dev/api/credits/sessions \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"credits\": 1000000, \"successUrl\": \"https://chat.recoupable.dev/credits/success\"}'\n```\n\nFull request/response schema at [Create Credits Top-Up Session](/api-reference/credits/sessions-create).\n\n### Check which card will be charged\n\nBefore triggering a silent off-session charge, inspect the default payment method on file:\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/payment-method \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nResponse shape:\n\n```json\n{\n \"account_id\": \"11111111-1111-4111-8111-111111111111\",\n \"card\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"exp_month\": 12,\n \"exp_year\": 2026,\n \"funding\": \"credit\"\n }\n}\n```\n\n`card` is `null` when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original `exp_month` / `exp_year`); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at [Get Default Payment Method](/api-reference/accounts/payment-method-get).\n\n---\n\n## Running out of credits\n\nEvery billed API request runs a credit gate before it executes. If `remaining_credits` doesn't cover the request's cost, the request stops there and returns **HTTP 402**. Nothing is charged and no Stripe object is created.\n\nThe decision tree:\n\n1. **Enough credits?** → Request proceeds, credits deducted on success.\n2. **Short?** → Request returns **HTTP 402** with the balance, the cost, and a link to billing.\n\nA card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through [`POST /api/credits/sessions`](/api-reference/credits/sessions-create), or when the account has turned on auto top-up. Saving a card ahead of time via [`POST /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-create) makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on [`/api/accounts/{id}/subscription`](/api-reference/accounts/subscription-get), [`/api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-get), and [`/api/accounts/{id}/payments`](/api-reference/accounts/payments-get); pass an organization id as `{id}` to read the organization's billing.\n\n### Auto top-up (opt-in)\n\nAuto top-up is off for every account until it is turned on with [`PUT /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-update), which needs three things chosen by the account: `enabled`, the `amountCents` to buy each time (5.00 to 1,000.00 USD), and the `thresholdCents` balance that triggers it. Both are USD cents; the `remaining_credits` balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file.\n\nOnce on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as `lastError` (returned by [`GET /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-get)), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself.\n\n### Remove a saved card\n\n[`DELETE /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-delete) turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again.\n\nSuccess returns **204** with no body. If no customer or selected card exists, **404** leaves settings and cards unchanged. A **500** can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card.\n\nThis operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently.\n\n---\n\n## 402 Payment Required\n\nWhen the gate comes up short, billed endpoints return **HTTP 402** with a unified body:\n\n```json\n{\n \"error\": \"insufficient_credits\",\n \"remaining_credits\": 120000,\n \"required_credits\": 1000000,\n \"billingUrl\": \"https://app.recoupable.dev\"\n}\n```\n\n| Field | When it appears | Meaning |\n|-------|-----------------|---------|\n| `error` | Always | Literally `\"insufficient_credits\"` |\n| `remaining_credits` | Always | Account balance at the moment of the failed request |\n| `required_credits` | Always | What this endpoint needed |\n| `billingUrl` | Always | Static link to the Recoup app, where a human can save a card and buy credits |\n\n`billingUrl` is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running.\n\n**How to react:**\n\n- **Browser-driven UI** (e.g., the Recoup chat app): send the customer to `billingUrl`, or call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create) inline and open the `url` it returns.\n- **Programmatic / LLM-driven client**: report `remaining_credits` and `required_credits`, and surface `billingUrl` as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands.\n\n---\n\n## Cost per endpoint\n\nCurrent as of this revision of the page. The authoritative source is the per-endpoint reference docs and the `required_credits` field on any 402 response.\n\n| Endpoint | Cost |\n|----------|------|\n| [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | Variable, priced from the model's token usage; see `required_credits` on a 402 |\n| [Recoup artist and track research](/api-reference/research/search) | \\$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups |\n| [`POST /api/research/people`](/api-reference/research/people) | \\$0.05 per call |\n| [`POST /api/research/web`](/api-reference/research/web) | \\$0.01 per call |\n| [`POST /api/research/extract`](/api-reference/research/extract) | \\$0.05 × number of URLs |\n| [`POST /api/research/enrich`](/api-reference/research/enrich) | \\$0.05 / \\$0.10 / \\$0.25 (base / core / ultra processor) |\n| [`POST /api/research/deep`](/api-reference/research/deep) | \\$0.25 per call |\n| [`POST /api/image/generate`](/api-reference/image/generation) | Per-call price; see endpoint reference |\n| [`POST /api/songs/analyze`](/api-reference/songs/analyze) | `$0.05 + $0.001166 × elapsed_seconds` per model call; `full_report` = 13 calls |\n\n## Billing recovery and units\n\n`insufficient_credits` returns `billingUrl`, a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns `checkoutUrl`; subscription Checkout returns `url`. Inspect the endpoint-specific error type.\n\nTop-ups require `successUrl` on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; `totalCents` is 289 for that example. It is not a credit count. `isPro` means effective Pro only, and is false for paid Starter; use `plan` for paid-plan decisions.\n\nScheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names.\n","headings":[{"title":"What's billed","id":"whats-billed"},{"title":"What a credit is worth","id":"what-a-credit-is-worth"},{"title":"Check your balance","id":"check-your-balance"},{"title":"Subscription","id":"subscription"},{"title":"Running out of credits","id":"running-out-of-credits"},{"title":"402 Payment Required","id":"402-payment-required"},{"title":"Cost per endpoint","id":"cost-per-endpoint"},{"title":"Billing recovery and units","id":"billing-recovery-and-units"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Some Recoup endpoints are billed in \", _jsx(_components.strong, {\n children: \"credits\"\n }), \" — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"whats-billed\",\n children: \"What's billed\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Family\"\n }), _jsx(_components.th, {\n children: \"Billed?\"\n }), _jsx(_components.th, {\n children: \"Notes\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Research\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: _jsx(_components.code, {\n children: \"/api/research/*\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. \", _jsx(_components.a, {\n href: \"/api-reference/research/enrich\",\n children: _jsx(_components.code, {\n children: \"enrich\"\n })\n }), \" charges by processor tier; \", _jsx(_components.a, {\n href: \"/api-reference/research/extract\",\n children: _jsx(_components.code, {\n children: \"extract\"\n })\n }), \" charges by URL count).\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Content generation\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/content/generate-image\",\n children: _jsx(_components.code, {\n children: \"/api/content/image\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/content/generate-video\",\n children: _jsx(_components.code, {\n children: \"video\"\n })\n }), \", upscale, transcribe and analyze)\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"AI Chat — streaming\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/chat/workflow\",\n children: _jsx(_components.code, {\n children: \"POST /api/chat\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Variable cost based on model token usage, with a per-request minimum.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Music analysis\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"$0.05 per model call plus $0.001166 per second of inference time; \", _jsx(_components.code, {\n children: \"full_report\"\n }), \" is the sum of its 13 calls.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Social scrape\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/social/scrape\",\n children: _jsx(_components.code, {\n children: \"/api/socials/{id}/scrape\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/artist/socials-scrape\",\n children: _jsx(_components.code, {\n children: \"/api/artist/socials/scrape\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"$0.05, plus $0.01 per post requested via \", _jsx(_components.code, {\n children: \"posts\"\n }), \" — per social profile scraped.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.strong, {\n children: \"Other operations\"\n })\n }), _jsx(_components.td, {\n children: \"Consult the endpoint contract\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/artists/list\",\n children: \"Artist CRUD\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: \"sandboxes\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/sessions/get\",\n children: \"sessions\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/tasks/get\",\n children: \"scheduled tasks\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: \"account/org management\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/agents/signup\",\n children: \"agent signup\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/spotify/search\",\n children: \"Spotify proxies\"\n }), \", etc. Subscription gating may still apply.\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Upstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"what-a-credit-is-worth\",\n children: \"What a credit is worth\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Balances and prices are US dollars.\"\n }), \" The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: \", _jsx(_components.code, {\n children: \"1,000,000 = $1.00\"\n }), \", so it can carry sub-cent charges (a $0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/credits\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"check-your-balance\",\n children: \"Check your balance\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/credits \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response shape:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"11111111-1111-4111-8111-111111111111\\\",\\n \\\"remaining_credits\\\": 292450000,\\n \\\"total_credits\\\": 300000000,\\n \\\"used_credits\\\": 7550000,\\n \\\"is_pro\\\": true,\\n \\\"plan\\\": \\\"pro\\\",\\n \\\"task_limit\\\": null,\\n \\\"min_cadence_minutes\\\": 60,\\n \\\"timestamp\\\": \\\"2026-10-01T12:00:00Z\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"plan\"\n }), \", \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", and \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" describe the \", _jsx(_components.a, {\n href: \"#subscription\",\n children: \"plan\"\n }), \" the balance belongs to. \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \" is your plan-derived monthly allotment. \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" can exceed \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \" after a top-up or an admin grant, and \", _jsx(_components.code, {\n children: \"used_credits\"\n }), \" clamps to 0 in that case. Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"Get Account Credits\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"plan-response-examples\",\n children: \"Plan response examples\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"is_pro\"\n }), \" on credits and \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" on subscriptions mean effective Pro, so both are\\nfalse for paid Starter. Use \", _jsx(_components.code, {\n children: \"plan\"\n }), \" to distinguish Starter from Free. The credits\\nresponse reports the effective allowance; the \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: \"subscription response\"\n }), \"\\nseparately identifies whether it comes from the account or an organization.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Situation\"\n }), _jsxs(_components.th, {\n children: [\"Credits \", _jsx(_components.code, {\n children: \"plan\"\n }), \" / \", _jsx(_components.code, {\n children: \"is_pro\"\n })]\n }), _jsxs(_components.th, {\n children: [\"Subscription \", _jsx(_components.code, {\n children: \"source\"\n })]\n }), _jsx(_components.th, {\n children: \"Task limit / minimum cadence\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Free\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"free\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"null\"\n })\n }), _jsx(_components.td, {\n children: \"1 / weekly\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Paid Starter\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"starter\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"account\"\n })\n }), _jsx(_components.td, {\n children: \"3 / daily\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Direct Pro\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"pro\"\n }), \" / \", _jsx(_components.code, {\n children: \"true\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"account\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"null\"\n }), \" (unlimited) / hourly\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Starter account with organization Pro\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"pro\"\n }), \" / \", _jsx(_components.code, {\n children: \"true\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"organization\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"null\"\n }), \" (unlimited) / hourly\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Inactive subscription without another paid entitlement\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"free\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"null\"\n })\n }), _jsx(_components.td, {\n children: \"1 / weekly\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For example, a Pro balance of 325,000,000 against an allowance of 300,000,000\\nreturns \", _jsx(_components.code, {\n children: \"used_credits: 0\"\n }), \". The API preserves a signed balance: a negative balance\\ncan make this display exceed the allowance. This is not a ledger of charges.\\nA null timestamp means the timestamp is unavailable, not proof of no prior activity.\\nAn inactive subscription resolves to \", _jsx(_components.code, {\n children: \"status: \\\"none\\\"\"\n }), \" and null subscription/billing\\nfields; this endpoint does not return the canceled subscription's history. Billing\\ndetails may also be unavailable on an active response. Named reference examples\\nillustrate these states without quoting an available offer or a live payment.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To see what consumed the balance, list the charges line by line with \", _jsx(_components.a, {\n href: \"/api-reference/accounts/usage-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/usage\"\n })\n }), \": one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in \", _jsx(_components.code, {\n children: \"model_id\"\n }), \" (for example \", _jsx(_components.code, {\n children: \"POST /api/artist/socials/scrape\"\n }), \"), so a list of charges reads as a list of calls.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"subscription\",\n children: \"Subscription\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For Platform, Advisory, Build + Partner, and Enterprise options, see \", _jsx(_components.a, {\n href: \"https://recoupable.dev/pricing\",\n children: \"Recoup pricing\"\n }), \". API and MCP usage is billed separately through credits.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Your account's current credit allowance and scheduled-task limits are returned by \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"Get Account Credits\"\n }), \". Use \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \", \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", and \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" from that response rather than inferring limits from a public plan name.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The API may return account identifiers such as \", _jsx(_components.code, {\n children: \"free\"\n }), \", \", _jsx(_components.code, {\n children: \"starter\"\n }), \", or \", _jsx(_components.code, {\n children: \"pro\"\n }), \". These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"task-limits\",\n children: \"Task limits\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/tasks/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/tasks\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/tasks/update\",\n children: _jsx(_components.code, {\n children: \"PATCH /api/tasks\"\n })\n }), \" \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"check the plan\"\n }), \" before writing. Creating a task past \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with \", _jsx(_components.code, {\n children: \"error: \\\"plan_limit\\\"\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"status\\\": \\\"error\\\",\\n \\\"error\\\": \\\"plan_limit\\\",\\n \\\"limit\\\": \\\"task_count\\\",\\n \\\"message\\\": \\\"Free includes 1 task. Starter includes 3, Pro is unlimited.\\\",\\n \\\"plan\\\": \\\"free\\\",\\n \\\"task_limit\\\": 1,\\n \\\"min_cadence_minutes\\\": 10080,\\n \\\"current_task_count\\\": 1,\\n \\\"billingUrl\\\": \\\"https://app.recoupable.dev/plan\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"limit\"\n }), \" is \", _jsx(_components.code, {\n children: \"task_count\"\n }), \" or \", _jsx(_components.code, {\n children: \"min_cadence\"\n }), \"; \", _jsx(_components.code, {\n children: \"current_task_count\"\n }), \" excludes the task being created or updated. Edits that only touch \", _jsx(_components.code, {\n children: \"title\"\n }), \", \", _jsx(_components.code, {\n children: \"prompt\"\n }), \", or \", _jsx(_components.code, {\n children: \"model\"\n }), \" never hit the gate.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"monthly-refill\",\n children: \"Monthly refill\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The refill is a \", _jsx(_components.strong, {\n children: \"floor, not an assignment.\"\n }), \" It raises \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a \", _jsx(_components.a, {\n href: \"#one-time-top-ups\",\n children: \"top-up\"\n }), \" or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The refill is lazy rather than scheduled: it applies on the next read of \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/credits\"\n })\n }), \" once your credits row is more than a month old. The balance you read is always the refilled one.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"manage-your-subscription\",\n children: \"Manage your subscription\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sign in to your \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/plan\",\n children: \"account billing page\"\n }), \" to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in \", _jsx(_components.a, {\n href: \"/api-reference/subscriptions/sessions-create\",\n children: \"Create Subscription Session\"\n }), \" and open its returned checkout URL. Review the price and billing terms before completing checkout.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Advisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"check-your-tier\",\n children: \"Check your tier\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/subscription \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Get \", _jsx(_components.code, {\n children: \"$ACCOUNT_ID\"\n }), \" from \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n })\n }), \" if you don't already have it. Response includes \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" (boolean), \", _jsx(_components.code, {\n children: \"status\"\n }), \", \", _jsx(_components.code, {\n children: \"plan\"\n }), \", and \", _jsx(_components.code, {\n children: \"source\"\n }), \" (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: \"Get Subscription\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"one-time-top-ups\",\n children: \"One-time top-ups\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"You can purchase credits any time via \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \". The endpoint adapts to what's on the account:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Card on file → silent auto-charge.\"\n }), \" Recoup charges your saved Stripe card off-session and returns \", _jsx(_components.code, {\n children: \"paymentIntentId\"\n }), \", \", _jsx(_components.code, {\n children: \"creditsPurchased\"\n }), \", and \", _jsx(_components.code, {\n children: \"totalCents\"\n }), \". Credits land within seconds.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"No card, or Stripe declines the saved card → Stripe Checkout fallback.\"\n }), \" The response contains a Checkout \", _jsx(_components.code, {\n children: \"url\"\n }), \" you open in the browser. When Stripe specifically declined a saved card, the response also includes a \", _jsx(_components.code, {\n children: \"declineReason\"\n }), \" (e.g. \", _jsx(_components.code, {\n children: \"insufficient_funds\"\n }), \", \", _jsx(_components.code, {\n children: \"expired_card\"\n }), \") so you can explain \", _jsx(_components.em, {\n children: \"why\"\n }), \" before sending the customer to update billing.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS -X POST https://api.recoupable.dev/api/credits/sessions \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"credits\\\": 1000000, \\\"successUrl\\\": \\\"https://chat.recoupable.dev/credits/success\\\"}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Full request/response schema at \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: \"Create Credits Top-Up Session\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"check-which-card-will-be-charged\",\n children: \"Check which card will be charged\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before triggering a silent off-session charge, inspect the default payment method on file:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/payment-method \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response shape:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"11111111-1111-4111-8111-111111111111\\\",\\n \\\"card\\\": {\\n \\\"brand\\\": \\\"visa\\\",\\n \\\"last4\\\": \\\"4242\\\",\\n \\\"exp_month\\\": 12,\\n \\\"exp_year\\\": 2026,\\n \\\"funding\\\": \\\"credit\\\"\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"card\"\n }), \" is \", _jsx(_components.code, {\n children: \"null\"\n }), \" when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original \", _jsx(_components.code, {\n children: \"exp_month\"\n }), \" / \", _jsx(_components.code, {\n children: \"exp_year\"\n }), \"); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-get\",\n children: \"Get Default Payment Method\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"running-out-of-credits\",\n children: \"Running out of credits\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Every billed API request runs a credit gate before it executes. If \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" doesn't cover the request's cost, the request stops there and returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \". Nothing is charged and no Stripe object is created.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The decision tree:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Enough credits?\"\n }), \" → Request proceeds, credits deducted on success.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Short?\"\n }), \" → Request returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with the balance, the cost, and a link to billing.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \", or when the account has turned on auto top-up. Saving a card ahead of time via \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/accounts/{id}/payment-method\"\n })\n }), \" makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/subscription\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/payment-method\"\n })\n }), \", and \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payments-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/payments\"\n })\n }), \"; pass an organization id as \", _jsx(_components.code, {\n children: \"{id}\"\n }), \" to read the organization's billing.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"auto-top-up-opt-in\",\n children: \"Auto top-up (opt-in)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Auto top-up is off for every account until it is turned on with \", _jsx(_components.a, {\n href: \"/api-reference/accounts/auto-top-up-update\",\n children: _jsx(_components.code, {\n children: \"PUT /api/accounts/{id}/auto-top-up\"\n })\n }), \", which needs three things chosen by the account: \", _jsx(_components.code, {\n children: \"enabled\"\n }), \", the \", _jsx(_components.code, {\n children: \"amountCents\"\n }), \" to buy each time (5.00 to 1,000.00 USD), and the \", _jsx(_components.code, {\n children: \"thresholdCents\"\n }), \" balance that triggers it. Both are USD cents; the \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as \", _jsx(_components.code, {\n children: \"lastError\"\n }), \" (returned by \", _jsx(_components.a, {\n href: \"/api-reference/accounts/auto-top-up-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/auto-top-up\"\n })\n }), \"), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"remove-a-saved-card\",\n children: \"Remove a saved card\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-delete\",\n children: _jsx(_components.code, {\n children: \"DELETE /api/accounts/{id}/payment-method\"\n })\n }), \" turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Success returns \", _jsx(_components.strong, {\n children: \"204\"\n }), \" with no body. If no customer or selected card exists, \", _jsx(_components.strong, {\n children: \"404\"\n }), \" leaves settings and cards unchanged. A \", _jsx(_components.strong, {\n children: \"500\"\n }), \" can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"402-payment-required\",\n children: \"402 Payment Required\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"When the gate comes up short, billed endpoints return \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with a unified body:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"error\\\": \\\"insufficient_credits\\\",\\n \\\"remaining_credits\\\": 120000,\\n \\\"required_credits\\\": 1000000,\\n \\\"billingUrl\\\": \\\"https://app.recoupable.dev\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Field\"\n }), _jsx(_components.th, {\n children: \"When it appears\"\n }), _jsx(_components.th, {\n children: \"Meaning\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"error\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsxs(_components.td, {\n children: [\"Literally \", _jsx(_components.code, {\n children: \"\\\"insufficient_credits\\\"\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"remaining_credits\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"Account balance at the moment of the failed request\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"required_credits\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"What this endpoint needed\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"billingUrl\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"Static link to the Recoup app, where a human can save a card and buy credits\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"billingUrl\"\n }), \" is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"How to react:\"\n })\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Browser-driven UI\"\n }), \" (e.g., the Recoup chat app): send the customer to \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \", or call \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \" inline and open the \", _jsx(_components.code, {\n children: \"url\"\n }), \" it returns.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Programmatic / LLM-driven client\"\n }), \": report \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" and \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \", and surface \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \" as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"cost-per-endpoint\",\n children: \"Cost per endpoint\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Current as of this revision of the page. The authoritative source is the per-endpoint reference docs and the \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \" field on any 402 response.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Endpoint\"\n }), _jsx(_components.th, {\n children: \"Cost\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/chat/workflow\",\n children: _jsx(_components.code, {\n children: \"POST /api/chat\"\n })\n }), \" (streaming)\"]\n }), _jsxs(_components.td, {\n children: [\"Variable, priced from the model's token usage; see \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \" on a 402\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/search\",\n children: \"Recoup artist and track research\"\n })\n }), _jsx(_components.td, {\n children: \"$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/people\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/people\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/web\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.01 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/extract\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/extract\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 × number of URLs\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/enrich\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/enrich\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 / $0.10 / $0.25 (base / core / ultra processor)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/deep\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/deep\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.25 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/image/generation\",\n children: _jsx(_components.code, {\n children: \"POST /api/image/generate\"\n })\n })\n }), _jsx(_components.td, {\n children: \"Per-call price; see endpoint reference\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"$0.05 + $0.001166 × elapsed_seconds\"\n }), \" per model call; \", _jsx(_components.code, {\n children: \"full_report\"\n }), \" = 13 calls\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"billing-recovery-and-units\",\n children: \"Billing recovery and units\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"insufficient_credits\"\n }), \" returns \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \", a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns \", _jsx(_components.code, {\n children: \"checkoutUrl\"\n }), \"; subscription Checkout returns \", _jsx(_components.code, {\n children: \"url\"\n }), \". Inspect the endpoint-specific error type.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Top-ups require \", _jsx(_components.code, {\n children: \"successUrl\"\n }), \" on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; \", _jsx(_components.code, {\n children: \"totalCents\"\n }), \" is 289 for that example. It is not a credit count. \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" means effective Pro only, and is false for paid Starter; use \", _jsx(_components.code, {\n children: \"plan\"\n }), \" for paid-plan decisions.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Scheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Credits How Recoup credits work — what's billed, how to check your balance, and how to upgrade. Quickstart Getting started Some Recoup endpoints are billed in **credits** — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates. --- ## What's billed | Family | Billed? | Notes | |--------|---------|-------| | **Research** ([`/api/research/*`](/api-reference/research/web)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). | | **Content generation** ([`/api/content/image`](/api-reference/content/generate-image), [`video`](/api-reference/content/generate-video), upscale, transcribe and analyze) | Yes | Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory. | | **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. | | **Music analysis** ([`POST /api/songs/analyze`](/api-reference/songs/analyze)) | Yes | \\$0.05 per model call plus \\$0.001166 per second of inference time; `full_report` is the sum of its 13 calls. | | **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | \\$0.05, plus \\$0.01 per post requested via `posts` — per social profile scraped. | | **Other operations** | Consult the endpoint contract | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. | Upstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient. --- ## What a credit is worth **Balances and prices are US dollars.** The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: `1,000,000 = $1.00`, so it can carry sub-cent charges (a \\$0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get). --- ## Check your balance Response shape: `plan`, `task_limit`, and `min_cadence_minutes` describe the [plan](#subscription) the balance belongs to. `total_credits` is your plan-derived monthly allotment. `remaining_credits` can exceed `total_credits` after a top-up or an admin grant, and `used_credits` clamps to 0 in that case. Full schema at [Get Account Credits](/api-reference/accounts/credits-get). ### Plan response examples `is_pro` on credits and `isPro` on subscriptions mean effective Pro, so both are false for paid Starter. Use `plan` to distinguish Starter from Free. The credits response reports the effective allowance; the [subscription response](/api-reference/accounts/subscription-get) separately identifies whether it comes from the account or an organization. | Situation | Credits `plan` / `is_pro` | Subscription `source` | Task limit / minimum cadence | | --- | --- | --- | --- | | Free | `free` / `false` | `null` | 1 / weekly | | Paid Starter | `starter` / `false` | `account` | 3 / daily | | Direct Pro | `pro` / `true` | `account` | `null` (unlimited) / hourly | | Starter account with organization Pro | `pro` / `true` | `organization` | `null` (unlimited) / hourly | | Inactive subscription without another paid entitlement | `free` / `false` | `null` | 1 / weekly | For example, a Pro balance of 325,000,000 against an allowance of 300,000,000 returns `used_credits: 0`. The API preserves a signed balance: a negative balance can make this display exceed the allowance. This is not a ledger of charges. A null timestamp means the timestamp is unavailable, not proof of no prior activity. An inactive subscription resolves to `status: \"none\"` and null subscription/billing fields; this endpoint does not return the canceled subscription's history. Billing details may also be unavailable on an active response. Named reference examples illustrate these states without quoting an available offer or a live payment. To see what consumed the balance, list the charges line by line with [`GET /api/accounts/{id}/usage`](/api-reference/accounts/usage-get): one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in `model_id` (for example `POST /api/artist/socials/scrape`), so a list of charges reads as a list of calls. --- ## Subscription For Platform, Advisory, Build + Partner, and Enterprise options, see [Recoup pricing](https://recoupable.dev/pricing). API and MCP usage is billed separately through credits. Your account's current credit allowance and scheduled-task limits are returned by [Get Account Credits](/api-reference/accounts/credits-get). Use `total_credits`, `task_limit`, and `min_cadence_minutes` from that response rather than inferring limits from a public plan name. The API may return account identifiers such as `free`, `starter`, or `pro`. These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint. ### Task limits [`POST /api/tasks`](/api-reference/tasks/create) and [`PATCH /api/tasks`](/api-reference/tasks/update) [check the plan](/api-reference/accounts/credits-get) before writing. Creating a task past `task_limit`, re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than `min_cadence_minutes` returns **HTTP 402** with `error: \"plan_limit\"`: `limit` is `task_count` or `min_cadence`; `current_task_count` excludes the task being created or updated. Edits that only touch `title`, `prompt`, or `model` never hit the gate. ### Monthly refill The refill is a **floor, not an assignment.** It raises `remaining_credits` up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a [top-up](#one-time-top-ups) or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar. The refill is lazy rather than scheduled: it applies on the next read of [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get) once your credits row is more than a month old. The balance you read is always the refilled one. ### Manage your subscription Sign in to your [account billing page](https://app.recoupable.dev/plan) to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in [Create Subscription Session](/api-reference/subscriptions/sessions-create) and open its returned checkout URL. Review the price and billing terms before completing checkout. Advisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment. ### Check your tier Get `$ACCOUNT_ID` from [`GET /api/accounts/id`](/api-reference/accounts/id) if you don't already have it. Response includes `isPro` (boolean), `status`, `plan`, and `source` (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at [Get Subscription](/api-reference/accounts/subscription-get). ### One-time top-ups You can purchase credits any time via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create). The endpoint adapts to what's on the account: - **Card on file → silent auto-charge.** Recoup charges your saved Stripe card off-session and returns `paymentIntentId`, `creditsPurchased`, and `totalCents`. Credits land within seconds. - **No card, or Stripe declines the saved card → Stripe Checkout fallback.** The response contains a Checkout `url` you open in the browser. When Stripe specifically declined a saved card, the response also includes a `declineReason` (e.g. `insufficient_funds`, `expired_card`) so you can explain *why* before sending the customer to update billing. Full request/response schema at [Create Credits Top-Up Session](/api-reference/credits/sessions-create). ### Check which card will be charged Before triggering a silent off-session charge, inspect the default payment method on file: Response shape: `card` is `null` when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original `exp_month` / `exp_year`); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at [Get Default Payment Method](/api-reference/accounts/payment-method-get). --- ## Running out of credits Every billed API request runs a credit gate before it executes. If `remaining_credits` doesn't cover the request's cost, the request stops there and returns **HTTP 402**. Nothing is charged and no Stripe object is created. The decision tree: 1. **Enough credits?** → Request proceeds, credits deducted on success. 2. **Short?** → Request returns **HTTP 402** with the balance, the cost, and a link to billing. A card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through [`POST /api/credits/sessions`](/api-reference/credits/sessions-create), or when the account has turned on auto top-up. Saving a card ahead of time via [`POST /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-create) makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on [`/api/accounts/{id}/subscription`](/api-reference/accounts/subscription-get), [`/api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-get), and [`/api/accounts/{id}/payments`](/api-reference/accounts/payments-get); pass an organization id as `{id}` to read the organization's billing. ### Auto top-up (opt-in) Auto top-up is off for every account until it is turned on with [`PUT /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-update), which needs three things chosen by the account: `enabled`, the `amountCents` to buy each time (5.00 to 1,000.00 USD), and the `thresholdCents` balance that triggers it. Both are USD cents; the `remaining_credits` balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file. Once on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as `lastError` (returned by [`GET /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-get)), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself. ### Remove a saved card [`DELETE /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-delete) turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again. Success returns **204** with no body. If no customer or selected card exists, **404** leaves settings and cards unchanged. A **500** can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card. This operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently. --- ## 402 Payment Required When the gate comes up short, billed endpoints return **HTTP 402** with a unified body: | Field | When it appears | Meaning | |-------|-----------------|---------| | `error` | Always | Literally `\"insufficient_credits\"` | | `remaining_credits` | Always | Account balance at the moment of the failed request | | `required_credits` | Always | What this endpoint needed | | `billingUrl` | Always | Static link to the Recoup app, where a human can save a card and buy credits | `billingUrl` is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running. **How to react:** - **Browser-driven UI** (e.g., the Recoup chat app): send the customer to `billingUrl`, or call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create) inline and open the `url` it returns. - **Programmatic / LLM-driven client**: report `remaining_credits` and `required_credits`, and surface `billingUrl` as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands. --- ## Cost per endpoint Current as of this revision of the page. The authoritative source is the per-endpoint reference docs and the `required_credits` field on any 402 response. | Endpoint | Cost | |----------|------| | [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | Variable, priced from the model's token usage; see `required_credits` on a 402 | | [Recoup artist and track research](/api-reference/research/search) | \\$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups | | [`POST /api/research/people`](/api-reference/research/people) | \\$0.05 per call | | [`POST /api/research/web`](/api-reference/research/web) | \\$0.01 per call | | [`POST /api/research/extract`](/api-reference/research/extract) | \\$0.05 × number of URLs | | [`POST /api/research/enrich`](/api-reference/research/enrich) | \\$0.05 / \\$0.10 / \\$0.25 (base / core / ultra processor) | | [`POST /api/research/deep`](/api-reference/research/deep) | \\$0.25 per call | | [`POST /api/image/generate`](/api-reference/image/generation) | Per-call price; see endpoint reference | | [`POST /api/songs/analyze`](/api-reference/songs/analyze) | `$0.05 + $0.001166 × elapsed_seconds` per model call; `full_report` = 13 calls | ## Billing recovery and units `insufficient_credits` returns `billingUrl`, a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns `checkoutUrl`; subscription Checkout returns `url`. Inspect the endpoint-specific error type. Top-ups require `successUrl` on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; `totalCents` is 289 for that example. It is not a credit count. `isPro` means effective Pro only, and is false for paid Starter; use `plan` for paid-plan decisions. Scheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names. "},{"slug":"research-availability","title":"Research availability","description":"Explore Recoup research, choose the right identifiers, and handle incomplete data.","category":"Quickstart","group":"Getting started","source":"research-availability.mdx","body":"Recoup Research lets you discover artists and tracks, read current metrics,\nexplore audience and playlist activity, and capture recording measurements.\nAuthenticate with your Recoup API key or supported bearer credential. Recoup\nmanages the data connections; you do not need a separate data-service key.\n\nCoverage varies by artist, recording, platform and metric. An empty result means\nno matching data was returned; it does not prove an artist has no activity or audience.\n\n## Choose an identifier\n\nSearch by name, inspect the matches, and pass the selected result's `id` to the\ndetail endpoints. Treat research IDs as opaque strings: do not parse them or\nsubstitute a Recoup account UUID. Artist-name shortcuts use the first match;\nselect an explicit ID when names are ambiguous.\n\nFor portable recording references, store the ISRC and available Spotify or\nApple Music identifiers. Additional response fields and provenance labels may\nvary as Recoup's data connections change. Preserve returned provenance for\ntraceability without using it to choose a data vendor.\n\n## Current track statistics\n\nSupply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus\nthe required `source` (the platform, such as `spotify`). Recoup uses stored\nSpotify measurements when available for an ISRC, and otherwise requests current\nresearch data. Preserve `data_source` and capture timestamps when returned;\nmissing provenance remains unknown. A displayed play count is not a verified\nroyalty-bearing stream count.\n\n## Research endpoints\n\n| Method | Path | Reference |\n| --- | --- | --- |\n| GET | `/api/research` | [Search](/api-reference/research/search) |\n| GET | `/api/research/albums` | [Albums](/api-reference/research/albums) |\n| GET | `/api/research/audience` | [Audience](/api-reference/research/audience) |\n| GET | `/api/research/career` | [Career activities](/api-reference/research/career) |\n| GET | `/api/research/insights` | [Insights activities](/api-reference/research/insights) |\n| GET | `/api/research/lookup` | [Spotify artist lookup](/api-reference/research/lookup) |\n| GET | `/api/research/metrics` | [Current artist metrics](/api-reference/research/metrics) |\n| GET | `/api/research/milestones` | [Milestones](/api-reference/research/milestones) |\n| GET | `/api/research/playlists` | [Artist playlists](/api-reference/research/playlists) |\n| GET | `/api/research/profile` | [Artist profile](/api-reference/research/profile) |\n| GET | `/api/research/similar` | [Related artists](/api-reference/research/similar) |\n| GET | `/api/research/track` | [Track details](/api-reference/research/track) |\n| GET | `/api/research/track/playlists` | [Track playlists](/api-reference/research/track-playlists) |\n| GET | `/api/research/tracks` | [Artist tracks](/api-reference/research/tracks) |\n| GET | `/api/research/urls` | [Platform URLs](/api-reference/research/urls) |\n\n## Understand the results\n\n- Artist metrics are current snapshots. Save dated results to compare them over time.\n- Related artists are unweighted; the accepted similarity axes do not change the ranking.\n- Artist playlist `status=past` uses all-time scope and can include current placements.\n- Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.\n- Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.\n- Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.\n\n## Historical measurement jobs\n\n`POST /api/research/measurement-jobs` supports `source: \"historical\"`\nfor Spotify backfill. It requires a card on file and returns queue counts with\n`id: null`; enqueueing does not confirm capture completion. Recordings with an\nexisting historical research measurement can be skipped even when their history\nis partial. Inspect the available dates before claiming complete coverage.\nCurrent capture jobs return a snapshot ID.\n\n## Costs and unavailable data\n\nSuccessful research calls cost $0.05 (50,000 micro-dollar credits). Track-name\nresolution can add separately charged lookup calls; reuse a selected research\nID when available. Historical enqueue itself does not deduct research credits;\ncapture work has its own balance and budget checks.\n\nFor `402 insufficient_credits`, show the returned `billingUrl`. Surface `429`\nand unavailable-data errors; use bounded retries for transient failures and stop\nwhen the request cannot be served. Recoup does not promise a `Retry-After` header\non these routes. Never fill a missing metric with an invented number or zero.\n","headings":[{"title":"Choose an identifier","id":"choose-an-identifier"},{"title":"Current track statistics","id":"current-track-statistics"},{"title":"Research endpoints","id":"research-endpoints"},{"title":"Understand the results","id":"understand-the-results"},{"title":"Historical measurement jobs","id":"historical-measurement-jobs"},{"title":"Costs and unavailable data","id":"costs-and-unavailable-data"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Recoup Research lets you discover artists and tracks, read current metrics,\\nexplore audience and playlist activity, and capture recording measurements.\\nAuthenticate with your Recoup API key or supported bearer credential. Recoup\\nmanages the data connections; you do not need a separate data-service key.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Coverage varies by artist, recording, platform and metric. An empty result means\\nno matching data was returned; it does not prove an artist has no activity or audience.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"choose-an-identifier\",\n children: \"Choose an identifier\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Search by name, inspect the matches, and pass the selected result's \", _jsx(_components.code, {\n children: \"id\"\n }), \" to the\\ndetail endpoints. Treat research IDs as opaque strings: do not parse them or\\nsubstitute a Recoup account UUID. Artist-name shortcuts use the first match;\\nselect an explicit ID when names are ambiguous.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For portable recording references, store the ISRC and available Spotify or\\nApple Music identifiers. Additional response fields and provenance labels may\\nvary as Recoup's data connections change. Preserve returned provenance for\\ntraceability without using it to choose a data vendor.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"current-track-statistics\",\n children: \"Current track statistics\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Supply exactly one of \", _jsx(_components.code, {\n children: \"isrc\"\n }), \", \", _jsx(_components.code, {\n children: \"spotify_track_id\"\n }), \", or \", _jsx(_components.code, {\n children: \"apple_music_track_id\"\n }), \", plus\\nthe required \", _jsx(_components.code, {\n children: \"source\"\n }), \" (the platform, such as \", _jsx(_components.code, {\n children: \"spotify\"\n }), \"). Recoup uses stored\\nSpotify measurements when available for an ISRC, and otherwise requests current\\nresearch data. Preserve \", _jsx(_components.code, {\n children: \"data_source\"\n }), \" and capture timestamps when returned;\\nmissing provenance remains unknown. A displayed play count is not a verified\\nroyalty-bearing stream count.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"research-endpoints\",\n children: \"Research endpoints\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Method\"\n }), _jsx(_components.th, {\n children: \"Path\"\n }), _jsx(_components.th, {\n children: \"Reference\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/search\",\n children: \"Search\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/albums\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/albums\",\n children: \"Albums\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/audience\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/audience\",\n children: \"Audience\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/career\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/career\",\n children: \"Career activities\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/insights\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/insights\",\n children: \"Insights activities\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/lookup\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/lookup\",\n children: \"Spotify artist lookup\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/metrics\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/metrics\",\n children: \"Current artist metrics\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/milestones\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/milestones\",\n children: \"Milestones\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/playlists\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/playlists\",\n children: \"Artist playlists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/profile\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/profile\",\n children: \"Artist profile\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/similar\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/similar\",\n children: \"Related artists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/track\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/track\",\n children: \"Track details\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/track/playlists\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/track-playlists\",\n children: \"Track playlists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/tracks\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/tracks\",\n children: \"Artist tracks\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/urls\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/urls\",\n children: \"Platform URLs\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"understand-the-results\",\n children: \"Understand the results\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Artist metrics are current snapshots. Save dated results to compare them over time.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Related artists are unweighted; the accepted similarity axes do not change the ranking.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Artist playlist \", _jsx(_components.code, {\n children: \"status=past\"\n }), \" uses all-time scope and can include current placements.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"historical-measurement-jobs\",\n children: \"Historical measurement jobs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/research/measurement-jobs\"\n }), \" supports \", _jsx(_components.code, {\n children: \"source: \\\"historical\\\"\"\n }), \"\\nfor Spotify backfill. It requires a card on file and returns queue counts with\\n\", _jsx(_components.code, {\n children: \"id: null\"\n }), \"; enqueueing does not confirm capture completion. Recordings with an\\nexisting historical research measurement can be skipped even when their history\\nis partial. Inspect the available dates before claiming complete coverage.\\nCurrent capture jobs return a snapshot ID.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"costs-and-unavailable-data\",\n children: \"Costs and unavailable data\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name\\nresolution can add separately charged lookup calls; reuse a selected research\\nID when available. Historical enqueue itself does not deduct research credits;\\ncapture work has its own balance and budget checks.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For \", _jsx(_components.code, {\n children: \"402 insufficient_credits\"\n }), \", show the returned \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \". Surface \", _jsx(_components.code, {\n children: \"429\"\n }), \"\\nand unavailable-data errors; use bounded retries for transient failures and stop\\nwhen the request cannot be served. Recoup does not promise a \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" header\\non these routes. Never fill a missing metric with an invented number or zero.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Research availability Explore Recoup research, choose the right identifiers, and handle incomplete data. Quickstart Getting started Recoup Research lets you discover artists and tracks, read current metrics, explore audience and playlist activity, and capture recording measurements. Authenticate with your Recoup API key or supported bearer credential. Recoup manages the data connections; you do not need a separate data-service key. Coverage varies by artist, recording, platform and metric. An empty result means no matching data was returned; it does not prove an artist has no activity or audience. ## Choose an identifier Search by name, inspect the matches, and pass the selected result's `id` to the detail endpoints. Treat research IDs as opaque strings: do not parse them or substitute a Recoup account UUID. Artist-name shortcuts use the first match; select an explicit ID when names are ambiguous. For portable recording references, store the ISRC and available Spotify or Apple Music identifiers. Additional response fields and provenance labels may vary as Recoup's data connections change. Preserve returned provenance for traceability without using it to choose a data vendor. ## Current track statistics Supply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus the required `source` (the platform, such as `spotify`). Recoup uses stored Spotify measurements when available for an ISRC, and otherwise requests current research data. Preserve `data_source` and capture timestamps when returned; missing provenance remains unknown. A displayed play count is not a verified royalty-bearing stream count. ## Research endpoints | Method | Path | Reference | | --- | --- | --- | | GET | `/api/research` | [Search](/api-reference/research/search) | | GET | `/api/research/albums` | [Albums](/api-reference/research/albums) | | GET | `/api/research/audience` | [Audience](/api-reference/research/audience) | | GET | `/api/research/career` | [Career activities](/api-reference/research/career) | | GET | `/api/research/insights` | [Insights activities](/api-reference/research/insights) | | GET | `/api/research/lookup` | [Spotify artist lookup](/api-reference/research/lookup) | | GET | `/api/research/metrics` | [Current artist metrics](/api-reference/research/metrics) | | GET | `/api/research/milestones` | [Milestones](/api-reference/research/milestones) | | GET | `/api/research/playlists` | [Artist playlists](/api-reference/research/playlists) | | GET | `/api/research/profile` | [Artist profile](/api-reference/research/profile) | | GET | `/api/research/similar` | [Related artists](/api-reference/research/similar) | | GET | `/api/research/track` | [Track details](/api-reference/research/track) | | GET | `/api/research/track/playlists` | [Track playlists](/api-reference/research/track-playlists) | | GET | `/api/research/tracks` | [Artist tracks](/api-reference/research/tracks) | | GET | `/api/research/urls` | [Platform URLs](/api-reference/research/urls) | ## Understand the results - Artist metrics are current snapshots. Save dated results to compare them over time. - Related artists are unweighted; the accepted similarity axes do not change the ranking. - Artist playlist `status=past` uses all-time scope and can include current placements. - Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline. - Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album. - Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied. ## Historical measurement jobs `POST /api/research/measurement-jobs` supports `source: \"historical\"` for Spotify backfill. It requires a card on file and returns queue counts with `id: null`; enqueueing does not confirm capture completion. Recordings with an existing historical research measurement can be skipped even when their history is partial. Inspect the available dates before claiming complete coverage. Current capture jobs return a snapshot ID. ## Costs and unavailable data Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name resolution can add separately charged lookup calls; reuse a selected research ID when available. Historical enqueue itself does not deduct research credits; capture work has its own balance and budget checks. For `402 insufficient_credits`, show the returned `billingUrl`. Surface `429` and unavailable-data errors; use bounded retries for transient failures and stop when the request cannot be served. Recoup does not promise a `Retry-After` header on these routes. Never fill a missing metric with an invented number or zero. "},{"slug":"workflows/create-artist","title":"Create a New Artist","description":"End-to-end workflow to create, research and enrich a new artist account in a single session.","category":"Artists","group":"Workflows","source":"workflows/create-artist.mdx","body":"This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \"researched + enriched\" parity from a sandbox or any external agent.\n\nThe chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.\n\n## Prerequisites\n\n- `$RECOUP_API_KEY` (`x-api-key`) or `$RECOUP_ACCESS_TOKEN` (Privy Bearer JWT) for `api.recoupable.dev`\n- `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes)\n- An artist name to create (e.g. `ARTIST_NAME=\"The Weeknd\"`)\n\nSelect one credential obtained through the approved real-account REST setup:\n\n```bash\nif [ -n \"$RECOUP_API_KEY\" ]; then\n AUTH=(-H \"x-api-key: $RECOUP_API_KEY\")\nelif [ -n \"$RECOUP_ACCESS_TOKEN\" ]; then\n AUTH=(-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\")\nelse\n echo \"Authenticate REST through the approved real-account setup flow.\" >&2\n exit 1\nfi\n```\n\nUse your real account and selected organization. Do not create a disposable\n`agent+` identity or paste credentials into the workspace file.\n\nThe flow has three phases, run from a single checklist file:\n\n1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match\n2. **Enrich** — `PATCH` the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials\n3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array\n\n## Step 0: Scaffold the workspace BEFORE any API call\n\nPick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:\n\n```bash\nARTIST_SLUG=$(echo \"$ARTIST_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\\+/-/g; s/^-//; s/-$//')\nARTIST_DIR=\"artists/$ARTIST_SLUG\"\nmkdir -p \"$ARTIST_DIR\"\n\ncat > \"$ARTIST_DIR/RECOUP.md\" <&2\n return 1 ;;\n 429)\n retry_after=$(awk 'tolower($1)==\"retry-after:\" {sub(/^[^:]*:[[:space:]]*/, \"\"); sub(/\\r$/, \"\"); print}' \"$headers\")\n rm -f \"$headers\"\n printf 'Research step stopped. Retry-After: %s. Resume manually when allowed.\\n' \"${retry_after:-not provided}\" >&2\n return 1 ;;\n 5??) ;;\n *) rm -f \"$headers\"; printf 'Research HTTP %s; resolve before resuming.\\n' \"$status\" >&2; return 1 ;;\n esac\n fi\n if [ \"$attempt\" -lt 3 ]; then sleep \"$((attempt * 2))\"; fi\n done\n rm -f \"$headers\"\n echo 'Research unavailable after three attempts.' >&2\n return 1\n}\n```\n\n### 4a: Resolve the research artist ID\n\n```bash\nLOOKUP=$(research_request lookup --get \\\n --data-urlencode \"spotifyId=$SPOTIFY_ARTIST_ID\") || exit 1\n\nRESEARCH_ARTIST_ID=$(printf '%s' \"$LOOKUP\" | jq -r \\\n '[.id, .artist_info.id] | map(select(type == \"string\") | select(test(\"\\\\S\"))) | first // empty')\n```\n\nSave this value as `researchArtistId`. It is separate from the Recoup artist\naccount UUID and Spotify ID. Do not coerce it to a number or copy an older\nsaved research ID into it; re-resolve and verify older workspaces. If a successful\nlookup has no usable `id`, record that gap and skip 4b–4d, then run 4e.\n\nSee [Artist Lookup](/api-reference/research/lookup) for the response contract.\n\n### 4b–4d: Read available structured signals\n\n```bash\nif [ -n \"$RESEARCH_ARTIST_ID\" ]; then\n PROFILE=$(research_request profile --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\n CAREER=$(research_request career --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\n PLAYLISTS=$(research_request playlists --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\nfi\n```\n\nInspect the fields actually returned. Profile data may be partial; `career` is\nan available activity feed, not a guaranteed complete career timeline.\n`playlists` returns `placements`, which may be empty. Do not turn missing data\ninto zero or infer a label, achievement or placement that is absent.\n\nSee [Artist Profile](/api-reference/research/profile),\n[Artist Activity](/api-reference/research/career) and\n[Playlist Placements](/api-reference/research/playlists).\n\n### 4e: Search for narrative, press and collaborations\n\n```bash\nRESEARCH_WEB=$(research_request web -X POST \\\n -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg name \"$ARTIST_NAME\" \\\n '{query: ($name + \" biography press recent collaborations\")}')\") || exit 1\n```\n\nVerify source links before asserting a fact. See [Web Search](/api-reference/research/web).\n\n**After this step:** persist `researchArtistId` when available. Save the returned\npayloads, source links and coverage gaps under `## Research` in `RECOUP.md`, with\none subsection per request. Tick step 4 only after the successful reads and any\nintentional structured-data skip have been recorded.\n\n## Step 5: Pull the Spotify catalog\n\n```bash\nTOP_TRACKS=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/artist/topTracks\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$SPOTIFY_ARTIST_ID\")\n\nALBUMS=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/artist/albums\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$SPOTIFY_ARTIST_ID\")\n\n# For each notable album, drill in (ALBUM_ID from $ALBUMS):\nALBUM_DETAIL=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/album\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$ALBUM_ID\")\n```\n\n`$SPOTIFY_ARTIST_ID` is the value you exported in step 2.\n\nSee [Spotify Top Tracks](/api-reference/spotify/artist-top-tracks), [Spotify Artist Albums](/api-reference/spotify/artist-albums), and [Spotify Album](/api-reference/spotify/album) for full schemas.\n\n**After this step:** populate the artist's `releases/` folder — write one `releases/{release-slug}/RELEASE.md` per album (album slugs are bare, `-ep` / `-single` / `-compilation` suffixes for other types) using the per-album `GET /api/spotify/album?id=$ALBUM_ID` response, and write the top tracks snapshot to `releases/top-tracks.md`. `RELEASE.md` is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as `⚠️ TBD`. The full template + the field-by-field Spotify mapping live in the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill at `references/release-template.md`. Tick `- [ ] 5.` → `- [x] 5.`.\n\n## Step 6: Search the web for additional socials\n\n```bash\nSOCIALS_SEARCH=$(curl -sS -X POST \"https://api.recoupable.dev/api/research/web\" \\\n \"${AUTH[@]}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg name \"$ARTIST_NAME\" \\\n '{query: ($name + \" official instagram tiktok twitter youtube\")}')\")\n```\n\nParse the results to extract any new social URLs whose host matches the platform reference table below.\n\nSee [Web Search](/api-reference/research/web) for the request/response schema.\n\n**After this step:** save the discovered URLs (one per platform) into the `## Notes` section so step 7 can read them without re-querying. Tick `- [ ] 6.` → `- [x] 6.`.\n\n## Step 7: PATCH the artist with the discovered socials\n\n```bash\ncurl -sS -X PATCH \"https://api.recoupable.dev/api/artists/$ARTIST_ID\" \\\n \"${AUTH[@]}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"profileUrls\": {\n \"INSTAGRAM\": \"https://instagram.com/...\",\n \"TIKTOK\": \"https://tiktok.com/@...\",\n \"TWITTER\": \"https://x.com/...\",\n \"YOUTUBE\": \"https://youtube.com/@...\"\n }\n }'\n```\n\nOnly include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally.\n\nSee [Update Artist](/api-reference/artists/update) for the full body schema.\n\n**After this step:** tick `- [ ] 7.` → `- [x] 7.`.\n\n## Step 8: Synthesize the knowledge base\n\nCombine the available structured and web research (`## Research` section), the Spotify catalog (`releases/`), and the discovered socials into a comprehensive markdown report. Recommended sections:\n\n- Artist biography and origin\n- Discography highlights (top tracks + key albums)\n- Spotify presence (genres, listener count, notable playlists)\n- Social media footprint\n- Recent activity / press\n- Notable collaborations and achievements\n\nAppend the report to the same `RECOUP.md` you scaffolded in Step 0 — add it as a `## Knowledge base` section below the checklist. The path is:\n\n```\nartists/$ARTIST_SLUG/RECOUP.md\n```\n\nThis dovetails with the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL.\n\n**After this step:** tick `- [ ] 8.` → `- [x] 8.`. With every box ticked, the artist is fully set up.\n\n## Platform key reference\n\n`profileUrls` keys are **uppercase** platform identifiers, inferred from the URL host. Recognized platforms:\n\n| URL contains | `profileUrls` key |\n| ---------------------------- | ----------------- |\n| `spotify.com` | `SPOTIFY` |\n| `instagram.com` | `INSTAGRAM` |\n| `tiktok.com` | `TIKTOK` |\n| `x.com`, `twitter.com` | `TWITTER` |\n| `youtube.` | `YOUTUBE` |\n| `apple.com` | `APPLE` |\n| `facebook.com` | `FACEBOOK` |\n| `threads.net`, `threads.com` | `THREADS` |\n\nURLs that don't match any of these are silently skipped — they won't be saved.\n\n## What this workflow doesn't enforce\n\nThere's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The `RECOUP.md` checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't.\n\nA few constraints to honor:\n\n- **Run steps in order.** The frontmatter values written at one step are the inputs for later steps.\n- **Don't continue past a 4xx/5xx without recovery.** Leave the box unchecked, write the error to `## Notes`, and resolve before resuming.\n- **Treat the file as the source of truth.** If something isn't on disk, don't assume it ran.\n","headings":[{"title":"Prerequisites","id":"prerequisites"},{"title":"Step 0: Scaffold the workspace BEFORE any API call","id":"step-0-scaffold-the-workspace-before-any-api-call"},{"title":"Resuming a partial setup","id":"resuming-a-partial-setup"},{"title":"Step 1: Create the artist","id":"step-1-create-the-artist"},{"title":"Step 2: Find the canonical Spotify match","id":"step-2-find-the-canonical-spotify-match"},{"title":"Step 3: Set basic profile + Spotify URL","id":"step-3-set-basic-profile-spotify-url"},{"title":"Step 4: Run Recoup research","id":"step-4-run-recoup-research"},{"title":"Step 5: Pull the Spotify catalog","id":"step-5-pull-the-spotify-catalog"},{"title":"Step 6: Search the web for additional socials","id":"step-6-search-the-web-for-additional-socials"},{"title":"Step 7: PATCH the artist with the discovered socials","id":"step-7-patch-the-artist-with-the-discovered-socials"},{"title":"Step 8: Synthesize the knowledge base","id":"step-8-synthesize-the-knowledge-base"},{"title":"Platform key reference","id":"platform-key-reference"},{"title":"What this workflow doesn't enforce","id":"what-this-workflow-doesnt-enforce"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \\\"researched + enriched\\\" parity from a sandbox or any external agent.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, \", _jsx(_components.strong, {\n children: \"drive the work from a checklist file\"\n }), \": scaffold the artist's \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"prerequisites\",\n children: \"Prerequisites\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$RECOUP_API_KEY\"\n }), \" (\", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \") or \", _jsx(_components.code, {\n children: \"$RECOUP_ACCESS_TOKEN\"\n }), \" (Privy Bearer JWT) for \", _jsx(_components.code, {\n children: \"api.recoupable.dev\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$RECOUP_ORG_ID\"\n }), \" — the org the artist should belong to (recommended in sandboxes)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"An artist name to create (e.g. \", _jsx(_components.code, {\n children: \"ARTIST_NAME=\\\"The Weeknd\\\"\"\n }), \")\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Select one credential obtained through the approved real-account REST setup:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"if [ -n \\\"$RECOUP_API_KEY\\\" ]; then\\n AUTH=(-H \\\"x-api-key: $RECOUP_API_KEY\\\")\\nelif [ -n \\\"$RECOUP_ACCESS_TOKEN\\\" ]; then\\n AUTH=(-H \\\"Authorization: Bearer $RECOUP_ACCESS_TOKEN\\\")\\nelse\\n echo \\\"Authenticate REST through the approved real-account setup flow.\\\" >&2\\n exit 1\\nfi\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use your real account and selected organization. Do not create a disposable\\n\", _jsx(_components.code, {\n children: \"agent+\"\n }), \" identity or paste credentials into the workspace file.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The flow has three phases, run from a single checklist file:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Create + identify\"\n }), \" — \", _jsx(_components.code, {\n children: \"POST /api/artists\"\n }), \", then find the canonical Spotify match\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Enrich\"\n }), \" — \", _jsx(_components.code, {\n children: \"PATCH\"\n }), \" the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Synthesize + persist\"\n }), \" — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally \", _jsx(_components.code, {\n children: \"PATCH\"\n }), \" the \", _jsx(_components.code, {\n children: \"knowledges\"\n }), \" array\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-0-scaffold-the-workspace-before-any-api-call\",\n children: \"Step 0: Scaffold the workspace BEFORE any API call\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pick a slug, make the directory, and write the initial \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"ARTIST_SLUG=$(echo \\\"$ARTIST_NAME\\\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\\\\+/-/g; s/^-//; s/-$//')\\nARTIST_DIR=\\\"artists/$ARTIST_SLUG\\\"\\nmkdir -p \\\"$ARTIST_DIR\\\"\\n\\ncat > \\\"$ARTIST_DIR/RECOUP.md\\\" <&2\\n return 1 ;;\\n 429)\\n retry_after=$(awk 'tolower($1)==\\\"retry-after:\\\" {sub(/^[^:]*:[[:space:]]*/, \\\"\\\"); sub(/\\\\r$/, \\\"\\\"); print}' \\\"$headers\\\")\\n rm -f \\\"$headers\\\"\\n printf 'Research step stopped. Retry-After: %s. Resume manually when allowed.\\\\n' \\\"${retry_after:-not provided}\\\" >&2\\n return 1 ;;\\n 5??) ;;\\n *) rm -f \\\"$headers\\\"; printf 'Research HTTP %s; resolve before resuming.\\\\n' \\\"$status\\\" >&2; return 1 ;;\\n esac\\n fi\\n if [ \\\"$attempt\\\" -lt 3 ]; then sleep \\\"$((attempt * 2))\\\"; fi\\n done\\n rm -f \\\"$headers\\\"\\n echo 'Research unavailable after three attempts.' >&2\\n return 1\\n}\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4a-resolve-the-research-artist-id\",\n children: \"4a: Resolve the research artist ID\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"LOOKUP=$(research_request lookup --get \\\\\\n --data-urlencode \\\"spotifyId=$SPOTIFY_ARTIST_ID\\\") || exit 1\\n\\nRESEARCH_ARTIST_ID=$(printf '%s' \\\"$LOOKUP\\\" | jq -r \\\\\\n '[.id, .artist_info.id] | map(select(type == \\\"string\\\") | select(test(\\\"\\\\\\\\S\\\"))) | first // empty')\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save this value as \", _jsx(_components.code, {\n children: \"researchArtistId\"\n }), \". It is separate from the Recoup artist\\naccount UUID and Spotify ID. Do not coerce it to a number or copy an older\\nsaved research ID into it; re-resolve and verify older workspaces. If a successful\\nlookup has no usable \", _jsx(_components.code, {\n children: \"id\"\n }), \", record that gap and skip 4b–4d, then run 4e.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/lookup\",\n children: \"Artist Lookup\"\n }), \" for the response contract.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4b4d-read-available-structured-signals\",\n children: \"4b–4d: Read available structured signals\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"if [ -n \\\"$RESEARCH_ARTIST_ID\\\" ]; then\\n PROFILE=$(research_request profile --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\n CAREER=$(research_request career --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\n PLAYLISTS=$(research_request playlists --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\nfi\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Inspect the fields actually returned. Profile data may be partial; \", _jsx(_components.code, {\n children: \"career\"\n }), \" is\\nan available activity feed, not a guaranteed complete career timeline.\\n\", _jsx(_components.code, {\n children: \"playlists\"\n }), \" returns \", _jsx(_components.code, {\n children: \"placements\"\n }), \", which may be empty. Do not turn missing data\\ninto zero or infer a label, achievement or placement that is absent.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/profile\",\n children: \"Artist Profile\"\n }), \",\\n\", _jsx(_components.a, {\n href: \"/api-reference/research/career\",\n children: \"Artist Activity\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"/api-reference/research/playlists\",\n children: \"Playlist Placements\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4e-search-for-narrative-press-and-collaborations\",\n children: \"4e: Search for narrative, press and collaborations\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"RESEARCH_WEB=$(research_request web -X POST \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg name \\\"$ARTIST_NAME\\\" \\\\\\n '{query: ($name + \\\" biography press recent collaborations\\\")}')\\\") || exit 1\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Verify source links before asserting a fact. See \", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: \"Web Search\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" persist \", _jsx(_components.code, {\n children: \"researchArtistId\"\n }), \" when available. Save the returned\\npayloads, source links and coverage gaps under \", _jsx(_components.code, {\n children: \"## Research\"\n }), \" in \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \", with\\none subsection per request. Tick step 4 only after the successful reads and any\\nintentional structured-data skip have been recorded.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-5-pull-the-spotify-catalog\",\n children: \"Step 5: Pull the Spotify catalog\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"TOP_TRACKS=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/artist/topTracks\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$SPOTIFY_ARTIST_ID\\\")\\n\\nALBUMS=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/artist/albums\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$SPOTIFY_ARTIST_ID\\\")\\n\\n# For each notable album, drill in (ALBUM_ID from $ALBUMS):\\nALBUM_DETAIL=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/album\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$ALBUM_ID\\\")\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"$SPOTIFY_ARTIST_ID\"\n }), \" is the value you exported in step 2.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/spotify/artist-top-tracks\",\n children: \"Spotify Top Tracks\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/spotify/artist-albums\",\n children: \"Spotify Artist Albums\"\n }), \", and \", _jsx(_components.a, {\n href: \"/api-reference/spotify/album\",\n children: \"Spotify Album\"\n }), \" for full schemas.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" populate the artist's \", _jsx(_components.code, {\n children: \"releases/\"\n }), \" folder — write one \", _jsx(_components.code, {\n children: \"releases/{release-slug}/RELEASE.md\"\n }), \" per album (album slugs are bare, \", _jsx(_components.code, {\n children: \"-ep\"\n }), \" / \", _jsx(_components.code, {\n children: \"-single\"\n }), \" / \", _jsx(_components.code, {\n children: \"-compilation\"\n }), \" suffixes for other types) using the per-album \", _jsx(_components.code, {\n children: \"GET /api/spotify/album?id=$ALBUM_ID\"\n }), \" response, and write the top tracks snapshot to \", _jsx(_components.code, {\n children: \"releases/top-tracks.md\"\n }), \". \", _jsx(_components.code, {\n children: \"RELEASE.md\"\n }), \" is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as \", _jsx(_components.code, {\n children: \"⚠️ TBD\"\n }), \". The full template + the field-by-field Spotify mapping live in the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace\",\n children: _jsx(_components.code, {\n children: \"artist-workspace\"\n })\n }), \" skill at \", _jsx(_components.code, {\n children: \"references/release-template.md\"\n }), \". Tick \", _jsx(_components.code, {\n children: \"- [ ] 5.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 5.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-6-search-the-web-for-additional-socials\",\n children: \"Step 6: Search the web for additional socials\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"SOCIALS_SEARCH=$(curl -sS -X POST \\\"https://api.recoupable.dev/api/research/web\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg name \\\"$ARTIST_NAME\\\" \\\\\\n '{query: ($name + \\\" official instagram tiktok twitter youtube\\\")}')\\\")\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Parse the results to extract any new social URLs whose host matches the platform reference table below.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: \"Web Search\"\n }), \" for the request/response schema.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" save the discovered URLs (one per platform) into the \", _jsx(_components.code, {\n children: \"## Notes\"\n }), \" section so step 7 can read them without re-querying. Tick \", _jsx(_components.code, {\n children: \"- [ ] 6.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 6.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-7-patch-the-artist-with-the-discovered-socials\",\n children: \"Step 7: PATCH the artist with the discovered socials\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS -X PATCH \\\"https://api.recoupable.dev/api/artists/$ARTIST_ID\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\n \\\"profileUrls\\\": {\\n \\\"INSTAGRAM\\\": \\\"https://instagram.com/...\\\",\\n \\\"TIKTOK\\\": \\\"https://tiktok.com/@...\\\",\\n \\\"TWITTER\\\": \\\"https://x.com/...\\\",\\n \\\"YOUTUBE\\\": \\\"https://youtube.com/@...\\\"\\n }\\n }'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Only include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/artists/update\",\n children: \"Update Artist\"\n }), \" for the full body schema.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" tick \", _jsx(_components.code, {\n children: \"- [ ] 7.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 7.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-8-synthesize-the-knowledge-base\",\n children: \"Step 8: Synthesize the knowledge base\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Combine the available structured and web research (\", _jsx(_components.code, {\n children: \"## Research\"\n }), \" section), the Spotify catalog (\", _jsx(_components.code, {\n children: \"releases/\"\n }), \"), and the discovered socials into a comprehensive markdown report. Recommended sections:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Artist biography and origin\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Discography highlights (top tracks + key albums)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Spotify presence (genres, listener count, notable playlists)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Social media footprint\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Recent activity / press\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Notable collaborations and achievements\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Append the report to the same \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" you scaffolded in Step 0 — add it as a \", _jsx(_components.code, {\n children: \"## Knowledge base\"\n }), \" section below the checklist. The path is:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"artists/$ARTIST_SLUG/RECOUP.md\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This dovetails with the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace\",\n children: _jsx(_components.code, {\n children: \"artist-workspace\"\n })\n }), \" skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" tick \", _jsx(_components.code, {\n children: \"- [ ] 8.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 8.\"\n }), \". With every box ticked, the artist is fully set up.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"platform-key-reference\",\n children: \"Platform key reference\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"profileUrls\"\n }), \" keys are \", _jsx(_components.strong, {\n children: \"uppercase\"\n }), \" platform identifiers, inferred from the URL host. Recognized platforms:\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"URL contains\"\n }), _jsxs(_components.th, {\n children: [_jsx(_components.code, {\n children: \"profileUrls\"\n }), \" key\"]\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"spotify.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"SPOTIFY\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"instagram.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"INSTAGRAM\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"tiktok.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"TIKTOK\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"x.com\"\n }), \", \", _jsx(_components.code, {\n children: \"twitter.com\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"TWITTER\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"youtube.\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"YOUTUBE\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"apple.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"APPLE\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"facebook.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"FACEBOOK\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"threads.net\"\n }), \", \", _jsx(_components.code, {\n children: \"threads.com\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"THREADS\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"URLs that don't match any of these are silently skipped — they won't be saved.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-this-workflow-doesnt-enforce\",\n children: \"What this workflow doesn't enforce\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"There's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A few constraints to honor:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Run steps in order.\"\n }), \" The frontmatter values written at one step are the inputs for later steps.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Don't continue past a 4xx/5xx without recovery.\"\n }), \" Leave the box unchecked, write the error to \", _jsx(_components.code, {\n children: \"## Notes\"\n }), \", and resolve before resuming.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Treat the file as the source of truth.\"\n }), \" If something isn't on disk, don't assume it ran.\"]\n }), \"\\n\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Create a New Artist End-to-end workflow to create, research and enrich a new artist account in a single session. Artists Workflows This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \"researched + enriched\" parity from a sandbox or any external agent. The chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it. ## Prerequisites - `$RECOUP_API_KEY` (`x-api-key`) or `$RECOUP_ACCESS_TOKEN` (Privy Bearer JWT) for `api.recoupable.dev` - `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes) - An artist name to create (e.g. `ARTIST_NAME=\"The Weeknd\"`) Select one credential obtained through the approved real-account REST setup: Use your real account and selected organization. Do not create a disposable `agent+` identity or paste credentials into the workspace file. The flow has three phases, run from a single checklist file: 1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match 2. **Enrich** — `PATCH` the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials 3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array ## Step 0: Scaffold the workspace BEFORE any API call Pick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps: The sandbox is already scoped to a single Recoupable organization (its repo _is_ the org), so artists live at the top level — there is no `orgs/` directory. Don't proceed to step 1 until the file exists on disk. **After every step that follows, do two writes back to `RECOUP.md`:** tick the checkbox for the step you just ran (`- [ ]` → `- [x]`) and persist any captured value into the frontmatter. Later steps read those values from the frontmatter — never re-derive what's already saved. ## Resuming a partial setup If `$ARTIST_DIR/RECOUP.md` already exists, do not re-scaffold and do not re-run completed steps. Read the file, find the first unchecked item, and resume from there using the values already saved in the frontmatter: If every item is checked, the artist is fully set up — confirm with the user before doing anything else. ## Step 1: Create the artist Capture `account_id` as `$ARTIST_ID` — every subsequent step needs it. `organization_id` is optional but should be included when running inside a sandbox so the artist is scoped to the right org. See [Create Artist](/api-reference/artists/create) for the full request/response schema. **After this step:** write `artistId: $ARTIST_ID` into the frontmatter and tick `- [ ] 1.` → `- [x] 1.` in `RECOUP.md`. ## Step 2: Find the canonical Spotify match Inspect the returned candidates' names, profile links, images and catalog. Set `SELECTED_SPOTIFY_ARTIST_ID` to the verified match; popularity alone does not establish identity. If candidates remain ambiguous, resolve that before saving the artist's profile. If the verified artist is absent from the first ten results, repeat the search with a more specific name or known catalog context and inspect the new results. Do not substitute another artist. After verifying the candidate, export its fields: Also keep `genres`, `followers.total`, and `popularity` from `$MATCH` for the KB report later. See [Spotify Search](/api-reference/spotify/search) for the full query parameters and response schema. **After this step:** write `spotifyArtistId`, `spotifyProfileUrl`, and `imageUrl` into the frontmatter, save `genres` / `followers.total` / `popularity` to the `## Notes` section, and tick `- [ ] 2.` → `- [x] 2.`. ## Step 3: Set basic profile + Spotify URL One `PATCH` covers the image and the Spotify social URL. Use **uppercase** platform keys in `profileUrls` (the API matches platforms case-sensitively — see the reference table below). 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 only after verifying it in the research (step 4). See [Update Artist](/api-reference/artists/update) for the full body schema. **After this step:** tick `- [ ] 3.` → `- [x] 3.`. ## Step 4: Run Recoup research Resolve the verified Spotify artist to an opaque Recoup research ID, then read available profile fields, activity and playlist placements. Coverage varies by artist and platform: an empty successful response is a data gap, not a request to warm a cache. Use a web search for biography, press and collaborations. The four structured reads below cost $0.05 each when successful, or $0.20 total (200,000 micro-dollar credits). Web research is billed separately; check the current credit reference before running it. Check HTTP status before extracting IDs or making dependent calls. This helper allows at most three attempts for network failures or `5xx`, each with a 90-second timeout. A `402` surfaces `billingUrl`; a `429` stops the step and prints `Retry-After` for a later manual retry; it does not wait or retry automatically. Leave the step unchecked on errors. ### 4a: Resolve the research artist ID Save this value as `researchArtistId`. It is separate from the Recoup artist account UUID and Spotify ID. Do not coerce it to a number or copy an older saved research ID into it; re-resolve and verify older workspaces. If a successful lookup has no usable `id`, record that gap and skip 4b–4d, then run 4e. See [Artist Lookup](/api-reference/research/lookup) for the response contract. ### 4b–4d: Read available structured signals Inspect the fields actually returned. Profile data may be partial; `career` is an available activity feed, not a guaranteed complete career timeline. `playlists` returns `placements`, which may be empty. Do not turn missing data into zero or infer a label, achievement or placement that is absent. See [Artist Profile](/api-reference/research/profile), [Artist Activity](/api-reference/research/career) and [Playlist Placements](/api-reference/research/playlists). ### 4e: Search for narrative, press and collaborations Verify source links before asserting a fact. See [Web Search](/api-reference/research/web). **After this step:** persist `researchArtistId` when available. Save the returned payloads, source links and coverage gaps under `## Research` in `RECOUP.md`, with one subsection per request. Tick step 4 only after the successful reads and any intentional structured-data skip have been recorded. ## Step 5: Pull the Spotify catalog `$SPOTIFY_ARTIST_ID` is the value you exported in step 2. See [Spotify Top Tracks](/api-reference/spotify/artist-top-tracks), [Spotify Artist Albums](/api-reference/spotify/artist-albums), and [Spotify Album](/api-reference/spotify/album) for full schemas. **After this step:** populate the artist's `releases/` folder — write one `releases/{release-slug}/RELEASE.md` per album (album slugs are bare, `-ep` / `-single` / `-compilation` suffixes for other types) using the per-album `GET /api/spotify/album?id=$ALBUM_ID` response, and write the top tracks snapshot to `releases/top-tracks.md`. `RELEASE.md` is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as `⚠️ TBD`. The full template + the field-by-field Spotify mapping live in the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill at `references/release-template.md`. Tick `- [ ] 5.` → `- [x] 5.`. ## Step 6: Search the web for additional socials Parse the results to extract any new social URLs whose host matches the platform reference table below. See [Web Search](/api-reference/research/web) for the request/response schema. **After this step:** save the discovered URLs (one per platform) into the `## Notes` section so step 7 can read them without re-querying. Tick `- [ ] 6.` → `- [x] 6.`. ## Step 7: PATCH the artist with the discovered socials Only include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally. See [Update Artist](/api-reference/artists/update) for the full body schema. **After this step:** tick `- [ ] 7.` → `- [x] 7.`. ## Step 8: Synthesize the knowledge base Combine the available structured and web research (`## Research` section), the Spotify catalog (`releases/`), and the discovered socials into a comprehensive markdown report. Recommended sections: - Artist biography and origin - Discography highlights (top tracks + key albums) - Spotify presence (genres, listener count, notable playlists) - Social media footprint - Recent activity / press - Notable collaborations and achievements Append the report to the same `RECOUP.md` you scaffolded in Step 0 — add it as a `## Knowledge base` section below the checklist. The path is: This dovetails with the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL. **After this step:** tick `- [ ] 8.` → `- [x] 8.`. With every box ticked, the artist is fully set up. ## Platform key reference `profileUrls` keys are **uppercase** platform identifiers, inferred from the URL host. Recognized platforms: | URL contains | `profileUrls` key | | ---------------------------- | ----------------- | | `spotify.com` | `SPOTIFY` | | `instagram.com` | `INSTAGRAM` | | `tiktok.com` | `TIKTOK` | | `x.com`, `twitter.com` | `TWITTER` | | `youtube.` | `YOUTUBE` | | `apple.com` | `APPLE` | | `facebook.com` | `FACEBOOK` | | `threads.net`, `threads.com` | `THREADS` | URLs that don't match any of these are silently skipped — they won't be saved. ## What this workflow doesn't enforce There's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The `RECOUP.md` checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't. A few constraints to honor: - **Run steps in order.** The frontmatter values written at one step are the inputs for later steps. - **Don't continue past a 4xx/5xx without recovery.** Leave the box unchecked, write the error to `## Notes`, and resolve before resuming. - **Treat the file as the source of truth.** If something isn't on disk, don't assume it ran. "},{"slug":"api-reference/artists/list","title":"Get Artists","description":"Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to.","category":"Artists","group":"Artists","source":"api-reference/artists/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists","spec":"releases.json"},"searchText":"Get Artists Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to. Artists Artists GET /api/artists "},{"slug":"api-reference/artists/profile","title":"Get Artist Profile","description":"Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call.","category":"Artists","group":"Artists","source":"api-reference/artists/profile.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/profile","spec":"releases.json"},"searchText":"Get Artist Profile Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call. Artists Artists GET /api/artists/{id}/profile "},{"slug":"api-reference/artists/create","title":"Create Artist","description":"Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization.","category":"Artists","group":"Artists","source":"api-reference/artists/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/artists","spec":"releases.json"},"searchText":"Create Artist Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization. Artists Artists POST /api/artists "},{"slug":"api-reference/artists/update","title":"Update Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Update Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/pin","title":"Pin Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/pin.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Pin Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/unpin","title":"Unpin Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/unpin.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Unpin Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/delete","title":"Delete Artist","description":"Delete an artist accessible to the authenticated account.","category":"Artists","group":"Artists","source":"api-reference/artists/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Delete Artist Delete an artist accessible to the authenticated account. Artists Artists DELETE /api/artists/{id} "},{"slug":"api-reference/artists/socials","title":"Get Artist Socials","description":"Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember.","category":"Artists","group":"Artists","source":"api-reference/artists/socials.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/socials","spec":"releases.json"},"searchText":"Get Artist Socials Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember. Artists Artists GET /api/artists/{id}/socials "},{"slug":"api-reference/artists/socials-delete","title":"Delete Artist Social","description":"Remove a social profile link from an artist to correct a wrongly auto-matched social.","category":"Artists","group":"Artists","source":"api-reference/artists/socials-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/artists/{id}/socials/{socialId}","spec":"releases.json"},"searchText":"Delete Artist Social Remove a social profile link from an artist to correct a wrongly auto-matched social. Artists Artists DELETE /api/artists/{id}/socials/{socialId} "},{"slug":"api-reference/fans/get","title":"Get Artist Fans","description":"Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists.","category":"Artists","group":"Fans","source":"api-reference/fans/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/fans","spec":"releases.json"},"searchText":"Get Artist Fans Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists. Artists Fans GET /api/artists/{id}/fans "},{"slug":"api-reference/chat/workflow","title":"Stream Chat","description":"Stream sandbox-driven chat (Vercel Workflow)","category":"Chats","group":"Streaming","source":"api-reference/chat/workflow.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat","spec":"research.json"},"searchText":"Stream Chat Stream sandbox-driven chat (Vercel Workflow) Chats Streaming POST /api/chat "},{"slug":"api-reference/chat/workflow-stream","title":"Resume Chat Stream","description":"Resume a chat response stream","category":"Chats","group":"Streaming","source":"api-reference/chat/workflow-stream.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chat/{chatId}/stream","spec":"research.json"},"searchText":"Resume Chat Stream Resume a chat response stream Chats Streaming GET /api/chat/{chatId}/stream "},{"slug":"api-reference/chat/runs","title":"Start Chat Run","description":"Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow).","category":"Chats","group":"Streaming","source":"api-reference/chat/runs.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat/runs","spec":"research.json"},"searchText":"Start Chat Run Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow). Chats Streaming POST /api/chat/runs "},{"slug":"api-reference/chat/runs-status","title":"Get Chat Run Status","description":"Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.","category":"Chats","group":"Streaming","source":"api-reference/chat/runs-status.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chat/runs/{runId}","spec":"research.json"},"searchText":"Get Chat Run Status Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content. Chats Streaming GET /api/chat/runs/{runId} "},{"slug":"api-reference/chat/stop","title":"Stop Chat","description":"Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account.","category":"Chats","group":"Streaming","source":"api-reference/chat/stop.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat/{chatId}/stop","spec":"research.json"},"searchText":"Stop Chat Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account. Chats Streaming POST /api/chat/{chatId}/stop "},{"slug":"api-reference/chat/create","title":"Create Chat","description":"Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to.","category":"Chats","group":"Chats","source":"api-reference/chat/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats","spec":"research.json"},"searchText":"Create Chat Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to. Chats Chats POST /api/chats "},{"slug":"api-reference/chat/chats","title":"Get Chats","description":"Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL.","category":"Chats","group":"Chats","source":"api-reference/chat/chats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats","spec":"research.json"},"searchText":"Get Chats Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL. Chats Chats GET /api/chats "},{"slug":"api-reference/chat/artist","title":"Get Chat Artist","description":"Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller.","category":"Chats","group":"Chats","source":"api-reference/chat/artist.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats/{id}/artist","spec":"research.json"},"searchText":"Get Chat Artist Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller. Chats Chats GET /api/chats/{id}/artist "},{"slug":"api-reference/chat/update","title":"Update Chat","description":"Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters.","category":"Chats","group":"Chats","source":"api-reference/chat/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/chats","spec":"research.json"},"searchText":"Update Chat Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters. Chats Chats PATCH /api/chats "},{"slug":"api-reference/chat/delete","title":"Delete Chat","description":"Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself.","category":"Chats","group":"Chats","source":"api-reference/chat/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/chats","spec":"research.json"},"searchText":"Delete Chat Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself. Chats Chats DELETE /api/chats "},{"slug":"api-reference/chat/compact","title":"Compact Chats","description":"Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary.","category":"Chats","group":"Chats","source":"api-reference/chat/compact.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats/compact","spec":"research.json"},"searchText":"Compact Chats Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary. Chats Chats POST /api/chats/compact "},{"slug":"api-reference/ai/models","title":"List Models","description":"Returns the catalog of language models available through the Vercel AI Gateway. Embedding models are filtered out. The full schema mirrors the Vercel AI Gateway response (`GatewayLanguageModelEntry` from `@ai-sdk/gateway`); the documented properties below are the load-bearing fields used by clients. No authentication required.","category":"Chats","group":"Chats","source":"api-reference/ai/models.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/ai/models","spec":"ai.json"},"searchText":"List Models Returns the catalog of language models available through the Vercel AI Gateway. Embedding models are filtered out. The full schema mirrors the Vercel AI Gateway response (`GatewayLanguageModelEntry` from `@ai-sdk/gateway`); the documented properties below are the load-bearing fields used by clients. No authentication required. Chats Chats GET /api/ai/models "},{"slug":"api-reference/chat/messages","title":"Get Chat Messages","description":"Retrieve all messages (memories) for a specific chat room in chronological order.","category":"Chats","group":"Messages","source":"api-reference/chat/messages.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats/{id}/messages","spec":"research.json"},"searchText":"Get Chat Messages Retrieve all messages (memories) for a specific chat room in chronological order. Chats Messages GET /api/chats/{id}/messages "},{"slug":"api-reference/chat/messages-copy","title":"Copy Chat Messages","description":"Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy.","category":"Chats","group":"Messages","source":"api-reference/chat/messages-copy.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats/{id}/messages/copy","spec":"research.json"},"searchText":"Copy Chat Messages Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy. Chats Messages POST /api/chats/{id}/messages/copy "},{"slug":"api-reference/chat/messages-trailing-delete","title":"Delete Trailing Chat Messages","description":"Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override.","category":"Chats","group":"Messages","source":"api-reference/chat/messages-trailing-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/chats/{id}/messages/trailing","spec":"research.json"},"searchText":"Delete Trailing Chat Messages Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override. Chats Messages DELETE /api/chats/{id}/messages/trailing "},{"slug":"api-reference/research/search","title":"Research Search","description":"Search Recoup Research for artists, tracks or labels by name. Artist and track matches include an `id` when an identifier is available. Select a match and reuse that ID for detail requests. `type` accepts artists, tracks or labels, plus their singular aliases, case-insensitively. Playlist search is unavailable. Recoup defaults `limit` to 10; pagination strings are passed to the data connection and its limits apply.","category":"Research","group":"Artist discovery","source":"api-reference/research/search.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research","spec":"research.json"},"searchText":"Research Search Search Recoup Research for artists, tracks or labels by name. Artist and track matches include an `id` when an identifier is available. Select a match and reuse that ID for detail requests. `type` accepts artists, tracks or labels, plus their singular aliases, case-insensitively. Playlist search is unavailable. Recoup defaults `limit` to 10; pagination strings are passed to the data connection and its limits apply. Research Artist discovery GET /api/research "},{"slug":"api-reference/research/lookup","title":"Lookup by URL","description":"Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved.","category":"Research","group":"Artist discovery","source":"api-reference/research/lookup.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/lookup","spec":"research.json"},"searchText":"Lookup by URL Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved. Research Artist discovery GET /api/research/lookup "},{"slug":"api-reference/research/profile","title":"Artist Profile","description":"Read artist identity and available biography, links, genres and related-artist metadata. Fields depend on available research data. For current platform counts, use [Metrics](/api-reference/research/metrics).","category":"Research","group":"Artist discovery","source":"api-reference/research/profile.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/profile","spec":"research.json"},"searchText":"Artist Profile Read artist identity and available biography, links, genres and related-artist metadata. Fields depend on available research data. For current platform counts, use [Metrics](/api-reference/research/metrics). Research Artist discovery GET /api/research/profile "},{"slug":"api-reference/research/metrics","title":"Platform Metrics","description":"Read current artist statistics for the required platform `source`. This is a synchronous snapshot, without a historical series or refresh-pending job. A valid source does not guarantee data is available. Save dated responses to compare results over time.","category":"Research","group":"Metrics & insights","source":"api-reference/research/metrics.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/metrics","spec":"research.json"},"searchText":"Platform Metrics Read current artist statistics for the required platform `source`. This is a synchronous snapshot, without a historical series or refresh-pending job. A valid source does not guarantee data is available. Save dated responses to compare results over time. Research Metrics & insights GET /api/research/metrics "},{"slug":"api-reference/research/audience","title":"Audience Demographics","description":"Read available audience data for an artist and platform. The default is `instagram`; other supported data connections can include Spotify, TikTok and YouTube. Geographic and demographic coverage varies. Age and gender breakdowns are not guaranteed.","category":"Research","group":"Metrics & insights","source":"api-reference/research/audience.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/audience","spec":"research.json"},"searchText":"Audience Demographics Read available audience data for an artist and platform. The default is `instagram`; other supported data connections can include Spotify, TikTok and YouTube. Geographic and demographic coverage varies. Age and gender breakdowns are not guaranteed. Research Metrics & insights GET /api/research/audience "},{"slug":"api-reference/research/insights","title":"Insights Activities","description":"Read available artist activities under `insights`. This endpoint returns activity data; it does not generate an AI analysis or a separate insight report.","category":"Research","group":"Metrics & insights","source":"api-reference/research/insights.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/insights","spec":"research.json"},"searchText":"Insights Activities Read available artist activities under `insights`. This endpoint returns activity data; it does not generate an AI analysis or a separate insight report. Research Metrics & insights GET /api/research/insights "},{"slug":"api-reference/research/career","title":"Career Timeline","description":"Read available dated artist activities under `career`. Career, insights and milestones use the same activity feed. This endpoint does not calculate a career stage or score, and does not guarantee a complete career history.","category":"Research","group":"Metrics & insights","source":"api-reference/research/career.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/career","spec":"research.json"},"searchText":"Career Timeline Read available dated artist activities under `career`. Career, insights and milestones use the same activity feed. This endpoint does not calculate a career stage or score, and does not guarantee a complete career history. Research Metrics & insights GET /api/research/career "},{"slug":"api-reference/research/milestones","title":"Milestones","description":"Read available artist activities under `milestones`. Coverage varies; an empty result does not prove the artist has no milestones. This endpoint does not guarantee a complete history or scored career timeline.","category":"Research","group":"Metrics & insights","source":"api-reference/research/milestones.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/milestones","spec":"research.json"},"searchText":"Milestones Read available artist activities under `milestones`. Coverage varies; an empty result does not prove the artist has no milestones. This endpoint does not guarantee a complete history or scored career timeline. Research Metrics & insights GET /api/research/milestones "},{"slug":"api-reference/research/events","title":"Artist Events","description":"List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup.","category":"Research","group":"Metrics & insights","source":"api-reference/research/events.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/events","spec":"research.json"},"searchText":"Artist Events List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup. Research Metrics & insights POST /api/research/events "},{"slug":"api-reference/research/similar","title":"Similar Artists","description":"Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored.","category":"Research","group":"Metrics & insights","source":"api-reference/research/similar.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/similar","spec":"research.json"},"searchText":"Similar Artists Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored. Research Metrics & insights GET /api/research/similar "},{"slug":"api-reference/research/urls","title":"Social URLs","description":"Read available platform URLs as `{domain, url}` entries. A missing link means no matching URL was returned; it does not prove the artist lacks an account on that platform.","category":"Research","group":"Metrics & insights","source":"api-reference/research/urls.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/urls","spec":"research.json"},"searchText":"Social URLs Read available platform URLs as `{domain, url}` entries. A missing link means no matching URL was returned; it does not prove the artist lacks an account on that platform. Research Metrics & insights GET /api/research/urls "},{"slug":"api-reference/research/albums","title":"Albums","description":"Read the artist catalog through the `albums` view using the `artist_id` selected from [Search](/api-reference/research/search). Results can include track-shaped catalog entries rather than distinct album objects. `is_primary` accepts true/false; filtering depends on the data connection. `limit` must be a positive integer string and `offset` a non-negative integer string.","category":"Research","group":"Catalog","source":"api-reference/research/albums.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/albums","spec":"research.json"},"searchText":"Albums Read the artist catalog through the `albums` view using the `artist_id` selected from [Search](/api-reference/research/search). Results can include track-shaped catalog entries rather than distinct album objects. `is_primary` accepts true/false; filtering depends on the data connection. `limit` must be a positive integer string and `offset` a non-negative integer string. Research Catalog GET /api/research/albums "},{"slug":"api-reference/research/tracks","title":"Tracks","description":"Read available artist catalog entries under `tracks`. Entries can include remixes and features; completeness and fields vary. This endpoint accepts an artist identifier without catalog pagination or filtering controls.","category":"Research","group":"Catalog","source":"api-reference/research/tracks.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/tracks","spec":"research.json"},"searchText":"Tracks Read available artist catalog entries under `tracks`. Entries can include remixes and features; completeness and fields vary. This endpoint accepts an artist identifier without catalog pagination or filtering controls. Research Catalog GET /api/research/tracks "},{"slug":"api-reference/research/track","title":"Track","description":"Read track details using the `id` selected from [Search](/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording.","category":"Research","group":"Catalog","source":"api-reference/research/track.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track","spec":"research.json"},"searchText":"Track Read track details using the `id` selected from [Search](/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording. Research Catalog GET /api/research/track "},{"slug":"api-reference/research/track-stats","title":"Track Stats","description":"Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown.","category":"Research","group":"Catalog","source":"api-reference/research/track-stats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track/stats","spec":"research.json"},"searchText":"Track Stats Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown. Research Catalog GET /api/research/track/stats "},{"slug":"api-reference/research/measurements","title":"Track measurements","description":"Track measurements","category":"Research","group":"Catalog","source":"api-reference/research/measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/tracks/{id}/measurements","spec":"research.json"},"searchText":"Track measurements Track measurements Research Catalog GET /api/research/tracks/{id}/measurements "},{"slug":"api-reference/research/album-measurements","title":"Album measurements","description":"Album measurements","category":"Research","group":"Catalog","source":"api-reference/research/album-measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/albums/{id}/measurements","spec":"research.json"},"searchText":"Album measurements Album measurements Research Catalog GET /api/research/albums/{id}/measurements "},{"slug":"api-reference/research/measurement-jobs","title":"Create measurement job","description":"Create a measurement job","category":"Research","group":"Catalog","source":"api-reference/research/measurement-jobs.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/measurement-jobs","spec":"research.json"},"searchText":"Create measurement job Create a measurement job Research Catalog POST /api/research/measurement-jobs "},{"slug":"api-reference/research/playlists","title":"Playlist Placements","description":"Read available playlist placements for an artist. `status=current` selects current scope; `status=past` selects all-time scope, which can include current placements. `limit` is an optional raw string with no Recoup default; supported limits and coverage depend on the data connection.","category":"Research","group":"Playlists","source":"api-reference/research/playlists.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/playlists","spec":"research.json"},"searchText":"Playlist Placements Read available playlist placements for an artist. `status=current` selects current scope; `status=past` selects all-time scope, which can include current placements. `limit` is an optional raw string with no Recoup default; supported limits and coverage depend on the data connection. Research Playlists GET /api/research/playlists "},{"slug":"api-reference/research/track-playlists","title":"Track Playlists","description":"Read available track playlist and activity entries. Supply a selected track `id`, or a track name `q` with optional `artist`. Name resolution selects the first Spotify match and resolves its research ID; `id` takes precedence. Filtering and pagination support depend on the data connection. With no filter flags, editorial, indie, majorCurator and popularIndie default to true. Track-name resolution can add separately charged lookup calls; reuse a selected ID to avoid them.","category":"Research","group":"Playlists","source":"api-reference/research/track-playlists.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track/playlists","spec":"research.json"},"searchText":"Track Playlists Read available track playlist and activity entries. Supply a selected track `id`, or a track name `q` with optional `artist`. Name resolution selects the first Spotify match and resolves its research ID; `id` takes precedence. Filtering and pagination support depend on the data connection. With no filter flags, editorial, indie, majorCurator and popularIndie default to true. Track-name resolution can add separately charged lookup calls; reuse a selected ID to avoid them. Research Playlists GET /api/research/track/playlists "},{"slug":"api-reference/research/web","title":"Web Search","description":"Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover.","category":"Research","group":"Web & social","source":"api-reference/research/web.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/web","spec":"research.json"},"searchText":"Web Search Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover. Research Web & social POST /api/research/web "},{"slug":"api-reference/research/deep","title":"Deep Research","description":"Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources.","category":"Research","group":"Web & social","source":"api-reference/research/deep.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/deep","spec":"research.json"},"searchText":"Deep Research Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources. Research Web & social POST /api/research/deep "},{"slug":"api-reference/research/people","title":"People Search","description":"Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data.","category":"Research","group":"Web & social","source":"api-reference/research/people.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/people","spec":"research.json"},"searchText":"People Search Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data. Research Web & social POST /api/research/people "},{"slug":"api-reference/research/extract","title":"Extract URL","description":"Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content.","category":"Research","group":"Web & social","source":"api-reference/research/extract.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/extract","spec":"research.json"},"searchText":"Extract URL Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content. Research Web & social POST /api/research/extract "},{"slug":"api-reference/research/enrich","title":"Enrich","description":"Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected.","category":"Research","group":"Web & social","source":"api-reference/research/enrich.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/enrich","spec":"research.json"},"searchText":"Enrich Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected. Research Web & social POST /api/research/enrich "},{"slug":"api-reference/songs/songs","title":"Get Songs","description":"Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information.","category":"Catalog","group":"Songs","source":"api-reference/songs/songs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/songs","spec":"releases.json"},"searchText":"Get Songs Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information. Catalog Songs GET /api/songs "},{"slug":"api-reference/songs/create","title":"Song creation availability","description":"Import songs into an owned catalog; standalone song creation is not available.","category":"Catalog","group":"Songs","source":"api-reference/songs/create.mdx","body":"Standalone `POST /api/songs` is not available. The API currently supports\n[`GET /api/songs`](/api-reference/songs/songs) for reading songs.\n\n## Add songs to a catalog\n\nIf you have an existing catalog you can access, use\n[`POST /api/catalogs/songs`](/api-reference/songs/catalog-songs-add).\nEach song needs its `catalog_id` and `isrc`; optional name, album, notes and\nartist names supply fallback metadata. The API checks access to every named\ncatalog before processing songs. This writes song records and catalog links;\nit is not a standalone create-only replacement.\n\n## Unfinished product decision\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) owns the\ndecision whether a separate song-creation API is needed and what ownership,\nmetadata-update and duplicate behavior it should allow. The old standalone\nrequest and response are removed from the callable specification until that\ndecision and its implementation exist. Do not omit `catalog_id` or substitute\nan unrelated catalog to make a write succeed.\n","headings":[{"title":"Add songs to a catalog","id":"add-songs-to-a-catalog"},{"title":"Unfinished product decision","id":"unfinished-product-decision"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Standalone \", _jsx(_components.code, {\n children: \"POST /api/songs\"\n }), \" is not available. The API currently supports\\n\", _jsx(_components.a, {\n href: \"/api-reference/songs/songs\",\n children: _jsx(_components.code, {\n children: \"GET /api/songs\"\n })\n }), \" for reading songs.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"add-songs-to-a-catalog\",\n children: \"Add songs to a catalog\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you have an existing catalog you can access, use\\n\", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-add\",\n children: _jsx(_components.code, {\n children: \"POST /api/catalogs/songs\"\n })\n }), \".\\nEach song needs its \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" and \", _jsx(_components.code, {\n children: \"isrc\"\n }), \"; optional name, album, notes and\\nartist names supply fallback metadata. The API checks access to every named\\ncatalog before processing songs. This writes song records and catalog links;\\nit is not a standalone create-only replacement.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"unfinished-product-decision\",\n children: \"Unfinished product decision\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" owns the\\ndecision whether a separate song-creation API is needed and what ownership,\\nmetadata-update and duplicate behavior it should allow. The old standalone\\nrequest and response are removed from the callable specification until that\\ndecision and its implementation exist. Do not omit \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" or substitute\\nan unrelated catalog to make a write succeed.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Song creation availability Import songs into an owned catalog; standalone song creation is not available. Catalog Songs Standalone `POST /api/songs` is not available. The API currently supports [`GET /api/songs`](/api-reference/songs/songs) for reading songs. ## Add songs to a catalog If you have an existing catalog you can access, use [`POST /api/catalogs/songs`](/api-reference/songs/catalog-songs-add). Each song needs its `catalog_id` and `isrc`; optional name, album, notes and artist names supply fallback metadata. The API checks access to every named catalog before processing songs. This writes song records and catalog links; it is not a standalone create-only replacement. ## Unfinished product decision [Reconciliation #327](https://github.com/recoupable/mono/issues/327) owns the decision whether a separate song-creation API is needed and what ownership, metadata-update and duplicate behavior it should allow. The old standalone request and response are removed from the callable specification until that decision and its implementation exist. Do not omit `catalog_id` or substitute an unrelated catalog to make a write succeed. "},{"slug":"api-reference/songs/analyze","title":"Analyze Songs","description":"Analyze music using a state-of-the-art Audio Language Model ([Music Flamingo](https://www.universalmusic.com/universal-music-group-to-transform-music-experience-for-billions-of-fans-with-nvidia-ai/)) that listens directly to the audio waveform.","category":"Catalog","group":"Songs","source":"api-reference/songs/analyze.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/songs/analyze","spec":"releases.json"},"searchText":"Analyze Songs Analyze music using a state-of-the-art Audio Language Model ([Music Flamingo](https://www.universalmusic.com/universal-music-group-to-transform-music-experience-for-billions-of-fans-with-nvidia-ai/)) that listens directly to the audio waveform. Catalog Songs POST /api/songs/analyze "},{"slug":"api-reference/songs/analyze-presets","title":"List Analyze Presets","description":"Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token.","category":"Catalog","group":"Songs","source":"api-reference/songs/analyze-presets.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/songs/analyze/presets","spec":"releases.json"},"searchText":"List Analyze Presets Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token. Catalog Songs GET /api/songs/analyze/presets "},{"slug":"api-reference/songs/catalogs","title":"Get Catalogs","description":"Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalogs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/catalogs","spec":"releases.json"},"searchText":"Get Catalogs Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run). Catalog Catalogs GET /api/accounts/{id}/catalogs "},{"slug":"api-reference/songs/catalogs-create","title":"Create Catalog","description":"Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalogs-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/catalogs","spec":"releases.json"},"searchText":"Create Catalog Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization. Catalog Catalogs POST /api/catalogs "},{"slug":"api-reference/songs/catalog-rename","title":"Rename Catalog","description":"Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-rename.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/catalogs/{catalogId}","spec":"releases.json"},"searchText":"Rename Catalog Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete). Catalog Catalogs PATCH /api/catalogs/{catalogId} "},{"slug":"api-reference/songs/catalog-delete","title":"Delete Catalog","description":"Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/catalogs/{catalogId}","spec":"releases.json"},"searchText":"Delete Catalog Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations). Catalog Catalogs DELETE /api/catalogs/{catalogId} "},{"slug":"api-reference/songs/valuation-run","title":"Run Valuation","description":"Run valuation","category":"Catalog","group":"Catalogs","source":"api-reference/songs/valuation-run.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/valuation","spec":"releases.json"},"searchText":"Run Valuation Run valuation Catalog Catalogs POST /api/valuation "},{"slug":"api-reference/songs/runs","title":"Get Runs","description":"Get runs","category":"Catalog","group":"Catalogs","source":"api-reference/songs/runs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/runs","spec":"releases.json"},"searchText":"Get Runs Get runs Catalog Catalogs GET /api/runs "},{"slug":"api-reference/songs/catalog-measurements","title":"Get Catalog Measurements","description":"Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/measurements","spec":"releases.json"},"searchText":"Get Catalog Measurements Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song. Catalog Catalogs GET /api/catalogs/{catalogId}/measurements "},{"slug":"api-reference/songs/catalog-playcount-history","title":"Catalog Playcount History","description":"Read catalog playcount history and period comparisons","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-playcount-history.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/playcount-history","spec":"releases.json"},"searchText":"Catalog Playcount History Read catalog playcount history and period comparisons Catalog Catalogs GET /api/catalogs/{catalogId}/playcount-history "},{"slug":"api-reference/songs/catalog-valuations","title":"Valuation history availability","description":"Saved valuation history is unfinished; current estimates do not establish a history.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-valuations.mdx","body":"Saved catalog valuation history is not available through\n`GET /api/catalogs/{catalogId}/valuations`. Current valuation calculations and\ncatalog measurements do not establish that estimates were saved or can be read\nback as a dated series.\n\n## Existing implementation work\n\n[Reconciliation #326](https://github.com/recoupable/mono/issues/326) owns this\noutcome through [App #1911](https://github.com/recoupable/app/issues/1911) and\n[API #795](https://github.com/recoupable/api/pull/795).\n[API #1059](https://github.com/recoupable/api/pull/1059) continues that work as a\nheld draft of internal adapters. It does not register a REST route, MCP tool or\nproduction caller and does not connect successful valuation runs to persistence.\n\nThe existing owner must finish the access prerequisite, run-to-save integration,\npublic read contract and authorized deployed save/readback before this feature\ncan be advertised. Removing the unfinished operation from the callable\nspecification does not complete or cancel valuation history. Do not rerun a paid\nvaluation solely to try to recover an unconfirmed save.\n","headings":[{"title":"Existing implementation work","id":"existing-implementation-work"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Saved catalog valuation history is not available through\\n\", _jsx(_components.code, {\n children: \"GET /api/catalogs/{catalogId}/valuations\"\n }), \". Current valuation calculations and\\ncatalog measurements do not establish that estimates were saved or can be read\\nback as a dated series.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"existing-implementation-work\",\n children: \"Existing implementation work\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/326\",\n children: \"Reconciliation #326\"\n }), \" owns this\\noutcome through \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/app/issues/1911\",\n children: \"App #1911\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/795\",\n children: \"API #795\"\n }), \".\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/1059\",\n children: \"API #1059\"\n }), \" continues that work as a\\nheld draft of internal adapters. It does not register a REST route, MCP tool or\\nproduction caller and does not connect successful valuation runs to persistence.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The existing owner must finish the access prerequisite, run-to-save integration,\\npublic read contract and authorized deployed save/readback before this feature\\ncan be advertised. Removing the unfinished operation from the callable\\nspecification does not complete or cancel valuation history. Do not rerun a paid\\nvaluation solely to try to recover an unconfirmed save.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Valuation history availability Saved valuation history is unfinished; current estimates do not establish a history. Catalog Catalogs Saved catalog valuation history is not available through `GET /api/catalogs/{catalogId}/valuations`. Current valuation calculations and catalog measurements do not establish that estimates were saved or can be read back as a dated series. ## Existing implementation work [Reconciliation #326](https://github.com/recoupable/mono/issues/326) owns this outcome through [App #1911](https://github.com/recoupable/app/issues/1911) and [API #795](https://github.com/recoupable/api/pull/795). [API #1059](https://github.com/recoupable/api/pull/1059) continues that work as a held draft of internal adapters. It does not register a REST route, MCP tool or production caller and does not connect successful valuation runs to persistence. The existing owner must finish the access prerequisite, run-to-save integration, public read contract and authorized deployed save/readback before this feature can be advertised. Removing the unfinished operation from the callable specification does not complete or cancel valuation history. Do not rerun a paid valuation solely to try to recover an unconfirmed save. "},{"slug":"api-reference/songs/catalog-songs","title":"Get Catalog Songs","description":"Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs.mdx","body":"\n This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints.\n\n\nA successful query with no matching songs returns HTTP `200`, an empty `songs`\narray, and `pagination.total_count: 0`. This also applies to an accessible catalog\nwith no songs. An empty result is not a `404` response.\n\nUse a nonempty `artistName` to request songs with a matching artist name. Omit the filter to\ninclude songs without a linked artist. Filtering applies before pagination and\nthe total count; a client can use a zero count to decide whether to retry without\nthe artist filter.\n\nMissing or inaccessible catalogs return `403`. A server or database failure\nreturns `500` with `status: \"error\"` and `error: \"Internal server error\"`.\n","headings":[],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the \", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-add\",\n children: \"Add Catalog Songs\"\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-delete\",\n children: \"Remove Catalog Songs\"\n }), \" endpoints.\"]\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A successful query with no matching songs returns HTTP \", _jsx(_components.code, {\n children: \"200\"\n }), \", an empty \", _jsx(_components.code, {\n children: \"songs\"\n }), \"\\narray, and \", _jsx(_components.code, {\n children: \"pagination.total_count: 0\"\n }), \". This also applies to an accessible catalog\\nwith no songs. An empty result is not a \", _jsx(_components.code, {\n children: \"404\"\n }), \" response.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use a nonempty \", _jsx(_components.code, {\n children: \"artistName\"\n }), \" to request songs with a matching artist name. Omit the filter to\\ninclude songs without a linked artist. Filtering applies before pagination and\\nthe total count; a client can use a zero count to decide whether to retry without\\nthe artist filter.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Missing or inaccessible catalogs return \", _jsx(_components.code, {\n children: \"403\"\n }), \". A server or database failure\\nreturns \", _jsx(_components.code, {\n children: \"500\"\n }), \" with \", _jsx(_components.code, {\n children: \"status: \\\"error\\\"\"\n }), \" and \", _jsx(_components.code, {\n children: \"error: \\\"Internal server error\\\"\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"GET","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Get Catalog Songs Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0. Catalog Catalogs GET /api/catalogs/songs This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints. A successful query with no matching songs returns HTTP `200`, an empty `songs` array, and `pagination.total_count: 0`. This also applies to an accessible catalog with no songs. An empty result is not a `404` response. Use a nonempty `artistName` to request songs with a matching artist name. Omit the filter to include songs without a linked artist. Filtering applies before pagination and the total count; a client can use a zero count to decide whether to retry without the artist filter. Missing or inaccessible catalogs return `403`. A server or database failure returns `500` with `status: \"error\"` and `error: \"Internal server error\"`. "},{"slug":"api-reference/songs/catalog-songs-add","title":"Add Catalog Songs","description":"Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs-add.mdx","body":"\n For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.\n\n","headings":[],"compiled":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.\"\n })\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"POST","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Add Catalog Songs Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used. Catalog Catalogs POST /api/catalogs/songs For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used. "},{"slug":"api-reference/songs/catalog-songs-delete","title":"Remove Catalog Songs","description":"Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs-delete.mdx","body":"\n This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted.\n\n","headings":[],"compiled":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"This endpoint removes the relationship in \", _jsx(_components.code, {\n children: \"catalog_songs\"\n }), \" for each \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" and ISRC pair. The song data itself is not deleted.\"]\n })\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"DELETE","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Remove Catalog Songs Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair. Catalog Catalogs DELETE /api/catalogs/songs This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted. "},{"slug":"api-reference/songs/catalog-streams","title":"Daily Catalog Streams","description":"Read daily catalog streams","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-streams.mdx","body":"## Date range and coverage\n\nSet `days` to an integer from 1 to 366 days. For example, use `days=90` for a 90-day comparison period. `since` is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive.\n\nA supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while `pagination.has_more` is true. Missing measurements suppress growth; they do not establish zero streams.\n\nThe catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection.\n","headings":[{"title":"Date range and coverage","id":"date-range-and-coverage"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"date-range-and-coverage\",\n children: \"Date range and coverage\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Set \", _jsx(_components.code, {\n children: \"days\"\n }), \" to an integer from 1 to 366 days. For example, use \", _jsx(_components.code, {\n children: \"days=90\"\n }), \" for a 90-day comparison period. \", _jsx(_components.code, {\n children: \"since\"\n }), \" is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while \", _jsx(_components.code, {\n children: \"pagination.has_more\"\n }), \" is true. Missing measurements suppress growth; they do not establish zero streams.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","api":{"method":"GET","path":"/api/catalogs/{catalogId}/streams","spec":"releases.json"},"searchText":"Daily Catalog Streams Read daily catalog streams Catalog Catalogs GET /api/catalogs/{catalogId}/streams ## Date range and coverage Set `days` to an integer from 1 to 366 days. For example, use `days=90` for a 90-day comparison period. `since` is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive. A supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while `pagination.has_more` is true. Missing measurements suppress growth; they do not establish zero streams. The catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection. "},{"slug":"api-reference/songs/catalog-stream-tracking","title":"Catalog Stream Tracking","description":"Inspect daily catalog tracking","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-stream-tracking.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/stream-tracking","spec":"releases.json"},"searchText":"Catalog Stream Tracking Inspect daily catalog tracking Catalog Catalogs GET /api/catalogs/{catalogId}/stream-tracking "},{"slug":"api-reference/songs/update-catalog-stream-tracking","title":"Update Catalog Stream Tracking","description":"Control daily catalog tracking","category":"Catalog","group":"Catalogs","source":"api-reference/songs/update-catalog-stream-tracking.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/catalogs/{catalogId}/stream-tracking","spec":"releases.json"},"searchText":"Update Catalog Stream Tracking Control daily catalog tracking Catalog Catalogs POST /api/catalogs/{catalogId}/stream-tracking "},{"slug":"api-reference/context/operate","title":"Context Engine","description":"Ingest, read, or compile context briefs","category":"Catalog","group":"Context","source":"api-reference/context/operate.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context","spec":"context.json"},"searchText":"Context Engine Ingest, read, or compile context briefs Catalog Context POST /api/context "},{"slug":"api-reference/context/guest-start","title":"Start guest context","description":"Start guest context extraction","category":"Catalog","group":"Context","source":"api-reference/context/guest-start.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context/guest","spec":"context.json"},"searchText":"Start guest context Start guest context extraction Catalog Context POST /api/context/guest "},{"slug":"api-reference/context/guest-read","title":"Read guest context","description":"Read guest context","category":"Catalog","group":"Context","source":"api-reference/context/guest-read.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/context/guest","spec":"context.json"},"searchText":"Read guest context Read guest context Catalog Context GET /api/context/guest "},{"slug":"api-reference/context/guest-claim","title":"Claim guest context","description":"Claim guest context after sign-in","category":"Catalog","group":"Context","source":"api-reference/context/guest-claim.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context/guest/claim","spec":"context.json"},"searchText":"Claim guest context Claim guest context after sign-in Catalog Context POST /api/context/guest/claim "},{"slug":"workflows/generate-music-video","title":"Generate a Music Video","description":"End-to-end workflow to produce a vertical, social-ready music video — image, motion, caption — from an artist and a song.","category":"Content","group":"Workflows","source":"workflows/generate-music-video.mdx","body":"This is the canonical recipe used internally by Recoup's `create-content` background task. Two paths are documented below: the **async pipeline** that an LLM agent should use, and the **manual recipe** for humans (or for cases where you want to swap a single step).\n\n## Hand it to your LLM\n\nThe fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a `.md` suffix, so models can fetch and follow it without parsing HTML:\n\n```\nGenerate a music video for The Weeknd – \"Blinding Lights\" using\nhttps://docs.recoupable.dev/workflows/generate-music-video.md\n```\n\nSwap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL.\n\n## Running as an agent? Use the async pipeline\n\n`POST /api/content/video` is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments.\n\nUse the async path instead — same five steps, run server-side:\n\n```bash\n# Trigger\nRUN_IDS=$(curl -sS -X POST \"https://api.recoupable.dev/api/content/create\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg artist \"$ARTIST_ACCOUNT_ID\" --arg template \"$TEMPLATE\" \\\n '{artist_account_id: $artist, template: $template}')\" \\\n | jq -r '.runIds[]')\n\n# Poll (every ~10s) until COMPLETED / FAILED / CANCELED / CRASHED\nRUN_ID=$(echo \"$RUN_IDS\" | head -1)\nuntil STATUS=$(curl -sS \"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq -r '.runs[0].status') && \\\n [[ \"$STATUS\" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do\n sleep 10\ndone\n\n# Read the output\ncurl -sS \"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq '.runs[0].output'\n# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }\n```\n\nPolling fits inside short shell timeouts and survives session restarts. See [Tasks Runs](/api-reference/tasks/runs) for the full status enum (`QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, etc.) and the `CreateContentRunOutput` schema.\n\n### Resolving `$ARTIST_ACCOUNT_ID`\n\n`POST /api/content/create` needs the artist's `account_id`. Three calls:\n\n```bash\nORG_ID=$(curl -sS \"https://api.recoupable.dev/api/organizations\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" | jq -r '.organizations[0].id')\n\nARTIST_ACCOUNT_ID=$(curl -sS \"https://api.recoupable.dev/api/artists?org_id=$ORG_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq -r --arg name \"$ARTIST_NAME\" '.artists[] | select(.name == $name) | .account_id')\n```\n\nThe artist record exposes both `id` and `account_id` (both UUIDs). Use **`account_id`** — `id` is the artist row's primary key, `account_id` is the underlying account that owns it. The two are easy to swap; you'll get a 404 from `/api/content/create` if you pass the wrong one.\n\n## Where the song lives\n\nStep 5 (and the async pipeline's lipsync mode) need a `song.mp3`. **Don't assume one exists, and don't assume the user has one locally.** Walk the agent through this fallback chain:\n\n1. **Check the artist's sandbox repo first.** Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths:\n\n ```\n .openclaw/workspace/orgs/{org-slug}/artists/{artist-slug}/songs/{song-slug}/{song-slug}.mp3\n /lyrics.json\n /clips.json\n ```\n\n Discover the repo with [`GET /api/sandboxes`](/api-reference/sandboxes/list) (returns `github_repo` and a `filetree`); fetch a file with [`GET /api/sandboxes/file?path=…`](/api-reference/sandboxes/file). **Binary files (`.mp3`, `.png`, `.mp4`) come back base64-encoded in the `content` field — decode before writing to disk.**\n\n2. **If no song is in the sandbox, ask the user how to proceed.** Two options to offer:\n - *\"Want me to fetch the audio from YouTube?\"* — agent downloads via `yt-dlp` (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications.\n - *\"Want to supply the song yourself?\"* — user uploads / drops a path; agent reads from there.\n\n Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call.\n\n3. **Don't fall back to \"use a placeholder track.\"** A music video without the song is not a deliverable.\n\n## Manual recipe (humans + targeted overrides)\n\nThe rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length).\n\n### Prerequisites\n\n- An auth credential for `api.recoupable.dev`. Two options — pick one and use it for every call below:\n - **API key** (`recoup_sk_…`, recommended for sandbox / agent use): pass as `-H \"x-api-key: $RECOUP_API_KEY\"`.\n - One-shot agent: `POST /api/agents/signup` with an `agent+{unique}@recoupable.com` email returns the key immediately.\n - Real-email signup: same endpoint with a real email mails a 6-digit code; complete with `POST /api/agents/verify`. See [Agents](/agents).\n - **Privy access token** (for end-user flows in chat/UI): pass as `-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\"`.\n - The examples below use `x-api-key`. Substitute `Authorization: Bearer …` if you're using a Privy token.\n- `$ARTIST_NAME`, `$SONG_TITLE`, `$SONG_LYRICS_CLIP` (a 1–2 sentence mood snippet)\n- `$REFERENCE_IMAGE_URL` *(optional)* — an artist photo or album cover to seed the image; if your template's purpose is \"show this exact image\" (e.g. `album-record-store`), set this and skip image generation in step 2\n- A `song.mp3` for step 5. **Don't ask the user for a local file** — fetch from the artist's repo via `/api/sandboxes/file`.\n- `ffmpeg` installed locally for step 5\n\n### Step 0: Scaffold the workspace BEFORE any API call\n\nThe `VIDEO.md` checklist *is* the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box.\n\n```bash\nVIDEO_SLUG=$(echo \"$SONG_TITLE\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-//; s/-$//')\nVIDEO_DIR=\"videos/$VIDEO_SLUG\"\nmkdir -p \"$VIDEO_DIR\"\n\ncat > \"$VIDEO_DIR/VIDEO.md\" < \"$VIDEO_DIR/caption.txt\"\n\n# Single-line filter graph — newlines inside -filter_complex are literal characters and break the [v] label\nffmpeg -y \\\n -stream_loop -1 -i \"$VIDEO_DIR/clip.mp4\" \\\n -i \"$SONG_PATH\" \\\n -filter_complex \"[0:v]crop=ih*9/16:ih,scale=1080:1920,drawtext=fontfile=$CAPTION_FONT:textfile=$VIDEO_DIR/caption.txt:fontcolor=$CAPTION_COLOR:fontsize=$CAPTION_FONT_SIZE:x=(w-text_w)/2:y=h-text_h-120:box=1:boxcolor=$CAPTION_STROKE@0.5:boxborderw=20[v]\" \\\n -map \"[v]\" -map \"1:a\" \\\n -shortest -c:v libx264 -c:a aac -pix_fmt yuv420p \\\n \"$FINAL_PATH\"\n```\n\n**After:** write `finalVideoPath`, tick the box. With every box ticked, the music video is complete.\n\n## Step 6: Publish (optional)\n\nOnce the MP4 is rendered, push it to the artist's socials with the [Connectors API](/api-reference/connectors/list). One heads-up worth knowing:\n\n- **TikTok URL ownership.** `TIKTOK_PUBLISH_VIDEO` (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. `fal.media` URLs will fail with `url_ownership_unverified` — use `TIKTOK_UPLOAD_VIDEO` instead, which accepts the same URL and uploads server-side.\n\n---\n\nThe checklist is the source of truth — if a box isn't ticked, treat the step as not run.\n","headings":[{"title":"Hand it to your LLM","id":"hand-it-to-your-llm"},{"title":"Running as an agent? Use the async pipeline","id":"running-as-an-agent-use-the-async-pipeline"},{"title":"Where the song lives","id":"where-the-song-lives"},{"title":"Manual recipe (humans + targeted overrides)","id":"manual-recipe-humans-targeted-overrides"},{"title":"Step 6: Publish (optional)","id":"step-6-publish-optional"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"This is the canonical recipe used internally by Recoup's \", _jsx(_components.code, {\n children: \"create-content\"\n }), \" background task. Two paths are documented below: the \", _jsx(_components.strong, {\n children: \"async pipeline\"\n }), \" that an LLM agent should use, and the \", _jsx(_components.strong, {\n children: \"manual recipe\"\n }), \" for humans (or for cases where you want to swap a single step).\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hand-it-to-your-llm\",\n children: \"Hand it to your LLM\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a \", _jsx(_components.code, {\n children: \".md\"\n }), \" suffix, so models can fetch and follow it without parsing HTML:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"Generate a music video for The Weeknd – \\\"Blinding Lights\\\" using\\nhttps://docs.recoupable.dev/workflows/generate-music-video.md\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Swap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"running-as-an-agent-use-the-async-pipeline\",\n children: \"Running as an agent? Use the async pipeline\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/video\"\n }), \" is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the async path instead — same five steps, run server-side:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"# Trigger\\nRUN_IDS=$(curl -sS -X POST \\\"https://api.recoupable.dev/api/content/create\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg artist \\\"$ARTIST_ACCOUNT_ID\\\" --arg template \\\"$TEMPLATE\\\" \\\\\\n '{artist_account_id: $artist, template: $template}')\\\" \\\\\\n | jq -r '.runIds[]')\\n\\n# Poll (every ~10s) until COMPLETED / FAILED / CANCELED / CRASHED\\nRUN_ID=$(echo \\\"$RUN_IDS\\\" | head -1)\\nuntil STATUS=$(curl -sS \\\"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq -r '.runs[0].status') && \\\\\\n [[ \\\"$STATUS\\\" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do\\n sleep 10\\ndone\\n\\n# Read the output\\ncurl -sS \\\"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq '.runs[0].output'\\n# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Polling fits inside short shell timeouts and survives session restarts. See \", _jsx(_components.a, {\n href: \"/api-reference/tasks/runs\",\n children: \"Tasks Runs\"\n }), \" for the full status enum (\", _jsx(_components.code, {\n children: \"QUEUED\"\n }), \", \", _jsx(_components.code, {\n children: \"EXECUTING\"\n }), \", \", _jsx(_components.code, {\n children: \"COMPLETED\"\n }), \", \", _jsx(_components.code, {\n children: \"FAILED\"\n }), \", \", _jsx(_components.code, {\n children: \"CANCELED\"\n }), \", \", _jsx(_components.code, {\n children: \"CRASHED\"\n }), \", etc.) and the \", _jsx(_components.code, {\n children: \"CreateContentRunOutput\"\n }), \" schema.\"]\n }), \"\\n\", _jsxs(_components.h3, {\n id: \"resolving-artistaccountid\",\n children: [\"Resolving \", _jsx(_components.code, {\n children: \"$ARTIST_ACCOUNT_ID\"\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/create\"\n }), \" needs the artist's \", _jsx(_components.code, {\n children: \"account_id\"\n }), \". Three calls:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"ORG_ID=$(curl -sS \\\"https://api.recoupable.dev/api/organizations\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" | jq -r '.organizations[0].id')\\n\\nARTIST_ACCOUNT_ID=$(curl -sS \\\"https://api.recoupable.dev/api/artists?org_id=$ORG_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq -r --arg name \\\"$ARTIST_NAME\\\" '.artists[] | select(.name == $name) | .account_id')\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The artist record exposes both \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" (both UUIDs). Use \", _jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"account_id\"\n })\n }), \" — \", _jsx(_components.code, {\n children: \"id\"\n }), \" is the artist row's primary key, \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" is the underlying account that owns it. The two are easy to swap; you'll get a 404 from \", _jsx(_components.code, {\n children: \"/api/content/create\"\n }), \" if you pass the wrong one.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"where-the-song-lives\",\n children: \"Where the song lives\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Step 5 (and the async pipeline's lipsync mode) need a \", _jsx(_components.code, {\n children: \"song.mp3\"\n }), \". \", _jsx(_components.strong, {\n children: \"Don't assume one exists, and don't assume the user has one locally.\"\n }), \" Walk the agent through this fallback chain:\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Check the artist's sandbox repo first.\"\n }), \" Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \".openclaw/workspace/orgs/{org-slug}/artists/{artist-slug}/songs/{song-slug}/{song-slug}.mp3\\n /lyrics.json\\n /clips.json\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Discover the repo with \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes\"\n })\n }), \" (returns \", _jsx(_components.code, {\n children: \"github_repo\"\n }), \" and a \", _jsx(_components.code, {\n children: \"filetree\"\n }), \"); fetch a file with \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/file\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes/file?path=…\"\n })\n }), \". \", _jsxs(_components.strong, {\n children: [\"Binary files (\", _jsx(_components.code, {\n children: \".mp3\"\n }), \", \", _jsx(_components.code, {\n children: \".png\"\n }), \", \", _jsx(_components.code, {\n children: \".mp4\"\n }), \") come back base64-encoded in the \", _jsx(_components.code, {\n children: \"content\"\n }), \" field — decode before writing to disk.\"]\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"If no song is in the sandbox, ask the user how to proceed.\"\n }), \" Two options to offer:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.em, {\n children: \"\\\"Want me to fetch the audio from YouTube?\\\"\"\n }), \" — agent downloads via \", _jsx(_components.code, {\n children: \"yt-dlp\"\n }), \" (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.em, {\n children: \"\\\"Want to supply the song yourself?\\\"\"\n }), \" — user uploads / drops a path; agent reads from there.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Don't fall back to \\\"use a placeholder track.\\\"\"\n }), \" A music video without the song is not a deliverable.\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"manual-recipe-humans-targeted-overrides\",\n children: \"Manual recipe (humans + targeted overrides)\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length).\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"prerequisites\",\n children: \"Prerequisites\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"An auth credential for \", _jsx(_components.code, {\n children: \"api.recoupable.dev\"\n }), \". Two options — pick one and use it for every call below:\", \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"API key\"\n }), \" (\", _jsx(_components.code, {\n children: \"recoup_sk_…\"\n }), \", recommended for sandbox / agent use): pass as \", _jsx(_components.code, {\n children: \"-H \\\"x-api-key: $RECOUP_API_KEY\\\"\"\n }), \".\", \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"One-shot agent: \", _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" with an \", _jsx(_components.code, {\n children: \"agent+{unique}@recoupable.com\"\n }), \" email returns the key immediately.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Real-email signup: same endpoint with a real email mails a 6-digit code; complete with \", _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \". See \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents\"\n }), \".\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Privy access token\"\n }), \" (for end-user flows in chat/UI): pass as \", _jsx(_components.code, {\n children: \"-H \\\"Authorization: Bearer $RECOUP_ACCESS_TOKEN\\\"\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The examples below use \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \". Substitute \", _jsx(_components.code, {\n children: \"Authorization: Bearer …\"\n }), \" if you're using a Privy token.\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$ARTIST_NAME\"\n }), \", \", _jsx(_components.code, {\n children: \"$SONG_TITLE\"\n }), \", \", _jsx(_components.code, {\n children: \"$SONG_LYRICS_CLIP\"\n }), \" (a 1–2 sentence mood snippet)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$REFERENCE_IMAGE_URL\"\n }), \" \", _jsx(_components.em, {\n children: \"(optional)\"\n }), \" — an artist photo or album cover to seed the image; if your template's purpose is \\\"show this exact image\\\" (e.g. \", _jsx(_components.code, {\n children: \"album-record-store\"\n }), \"), set this and skip image generation in step 2\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"A \", _jsx(_components.code, {\n children: \"song.mp3\"\n }), \" for step 5. \", _jsx(_components.strong, {\n children: \"Don't ask the user for a local file\"\n }), \" — fetch from the artist's repo via \", _jsx(_components.code, {\n children: \"/api/sandboxes/file\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"ffmpeg\"\n }), \" installed locally for step 5\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"step-0-scaffold-the-workspace-before-any-api-call\",\n children: \"Step 0: Scaffold the workspace BEFORE any API call\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.code, {\n children: \"VIDEO.md\"\n }), \" checklist \", _jsx(_components.em, {\n children: \"is\"\n }), \" the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"VIDEO_SLUG=$(echo \\\"$SONG_TITLE\\\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-//; s/-$//')\\nVIDEO_DIR=\\\"videos/$VIDEO_SLUG\\\"\\nmkdir -p \\\"$VIDEO_DIR\\\"\\n\\ncat > \\\"$VIDEO_DIR/VIDEO.md\\\" < \\\"$VIDEO_DIR/caption.txt\\\"\\n\\n# Single-line filter graph — newlines inside -filter_complex are literal characters and break the [v] label\\nffmpeg -y \\\\\\n -stream_loop -1 -i \\\"$VIDEO_DIR/clip.mp4\\\" \\\\\\n -i \\\"$SONG_PATH\\\" \\\\\\n -filter_complex \\\"[0:v]crop=ih*9/16:ih,scale=1080:1920,drawtext=fontfile=$CAPTION_FONT:textfile=$VIDEO_DIR/caption.txt:fontcolor=$CAPTION_COLOR:fontsize=$CAPTION_FONT_SIZE:x=(w-text_w)/2:y=h-text_h-120:box=1:boxcolor=$CAPTION_STROKE@0.5:boxborderw=20[v]\\\" \\\\\\n -map \\\"[v]\\\" -map \\\"1:a\\\" \\\\\\n -shortest -c:v libx264 -c:a aac -pix_fmt yuv420p \\\\\\n \\\"$FINAL_PATH\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After:\"\n }), \" write \", _jsx(_components.code, {\n children: \"finalVideoPath\"\n }), \", tick the box. With every box ticked, the music video is complete.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-6-publish-optional\",\n children: \"Step 6: Publish (optional)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once the MP4 is rendered, push it to the artist's socials with the \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors API\"\n }), \". One heads-up worth knowing:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"TikTok URL ownership.\"\n }), \" \", _jsx(_components.code, {\n children: \"TIKTOK_PUBLISH_VIDEO\"\n }), \" (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. \", _jsx(_components.code, {\n children: \"fal.media\"\n }), \" URLs will fail with \", _jsx(_components.code, {\n children: \"url_ownership_unverified\"\n }), \" — use \", _jsx(_components.code, {\n children: \"TIKTOK_UPLOAD_VIDEO\"\n }), \" instead, which accepts the same URL and uploads server-side.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.p, {\n children: \"The checklist is the source of truth — if a box isn't ticked, treat the step as not run.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Generate a Music Video End-to-end workflow to produce a vertical, social-ready music video — image, motion, caption — from an artist and a song. Content Workflows This is the canonical recipe used internally by Recoup's `create-content` background task. Two paths are documented below: the **async pipeline** that an LLM agent should use, and the **manual recipe** for humans (or for cases where you want to swap a single step). ## Hand it to your LLM The fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a `.md` suffix, so models can fetch and follow it without parsing HTML: Swap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL. ## Running as an agent? Use the async pipeline `POST /api/content/video` is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments. Use the async path instead — same five steps, run server-side: Polling fits inside short shell timeouts and survives session restarts. See [Tasks Runs](/api-reference/tasks/runs) for the full status enum (`QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, etc.) and the `CreateContentRunOutput` schema. ### Resolving `$ARTIST_ACCOUNT_ID` `POST /api/content/create` needs the artist's `account_id`. Three calls: The artist record exposes both `id` and `account_id` (both UUIDs). Use **`account_id`** — `id` is the artist row's primary key, `account_id` is the underlying account that owns it. The two are easy to swap; you'll get a 404 from `/api/content/create` if you pass the wrong one. ## Where the song lives Step 5 (and the async pipeline's lipsync mode) need a `song.mp3`. **Don't assume one exists, and don't assume the user has one locally.** Walk the agent through this fallback chain: 1. **Check the artist's sandbox repo first.** Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths: Discover the repo with [`GET /api/sandboxes`](/api-reference/sandboxes/list) (returns `github_repo` and a `filetree`); fetch a file with [`GET /api/sandboxes/file?path=…`](/api-reference/sandboxes/file). **Binary files (`.mp3`, `.png`, `.mp4`) come back base64-encoded in the `content` field — decode before writing to disk.** 2. **If no song is in the sandbox, ask the user how to proceed.** Two options to offer: - *\"Want me to fetch the audio from YouTube?\"* — agent downloads via `yt-dlp` (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications. - *\"Want to supply the song yourself?\"* — user uploads / drops a path; agent reads from there. Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call. 3. **Don't fall back to \"use a placeholder track.\"** A music video without the song is not a deliverable. ## Manual recipe (humans + targeted overrides) The rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length). ### Prerequisites - An auth credential for `api.recoupable.dev`. Two options — pick one and use it for every call below: - **API key** (`recoup_sk_…`, recommended for sandbox / agent use): pass as `-H \"x-api-key: $RECOUP_API_KEY\"`. - One-shot agent: `POST /api/agents/signup` with an `agent+{unique}@recoupable.com` email returns the key immediately. - Real-email signup: same endpoint with a real email mails a 6-digit code; complete with `POST /api/agents/verify`. See [Agents](/agents). - **Privy access token** (for end-user flows in chat/UI): pass as `-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\"`. - The examples below use `x-api-key`. Substitute `Authorization: Bearer …` if you're using a Privy token. - `$ARTIST_NAME`, `$SONG_TITLE`, `$SONG_LYRICS_CLIP` (a 1–2 sentence mood snippet) - `$REFERENCE_IMAGE_URL` *(optional)* — an artist photo or album cover to seed the image; if your template's purpose is \"show this exact image\" (e.g. `album-record-store`), set this and skip image generation in step 2 - A `song.mp3` for step 5. **Don't ask the user for a local file** — fetch from the artist's repo via `/api/sandboxes/file`. - `ffmpeg` installed locally for step 5 ### Step 0: Scaffold the workspace BEFORE any API call The `VIDEO.md` checklist *is* the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box. ### Step 1: Pick a template (required: list **and** detail) Templates carry the prompt, reference images, and styling that drive the rest of the chain — you can't write a good Step 2 prompt without them. List, pick, then fetch detail: **Templates that list \"Requires: face image\"** (e.g. `artist-caption-bedroom`) will fall back to their bundled reference images and produce a generic-likeness subject if you don't supply one — they don't 400. Pass `$REFERENCE_IMAGE_URL` if you want the model to preserve a specific artist's likeness, or omit it for a stock-feeling result. See [List Templates](/api-reference/content/templates) and [Template Detail](/api-reference/content/template-detail). **After:** write `template` into frontmatter, tick the box. ### Step 2: Generate the base image Use the template's own prompt and reference images — don't write your own from scratch. The template encodes the visual style; freeform prompts almost always drift off-brand. **Shortcut:** if `$REFERENCE_IMAGE_URL` is the exact image you want (e.g. an album cover for `album-record-store`, or a final editorial photo), set `IMAGE_URL=$REFERENCE_IMAGE_URL` and skip this call entirely. **Avoid:** prompts that aim for a real artist's likeness. Veo (used in step 3) rejects celebrity-likeness images with a 422. Use the template's prompt as-is and let the reference images carry the style. See [Generate Image](/api-reference/content/generate-image). **After:** write `imageUrl`, tick the box. ### Optional: Upscale (image or video) Same endpoint for both, swap `type`. Skip if you don't need the resolution bump. See [Upscale](/api-reference/content/upscale). ### Step 3: Generate the video Pass the image and a short motion prompt. For lipsync, also pass a presigned `audio_url` to a song clip — the model will animate the artist's mouth. This call routinely takes 60–180s. **From a short-shell agent, use the async pipeline at the top of this page instead.** From a long-lived shell, output is an 8s clip. Step 5 loops it to song length. See [Generate Video](/api-reference/content/generate-video). **After:** write `videoUrl`, tick the box. ### Step 4: Generate the caption `length` accepts `\"short\"` (default), `\"medium\"`, `\"long\"`, or `\"none\"` to skip. The four styling fields (`font`, `color`, `borderColor`, `maxFontSize`) are template-driven hints — Step 5 wires them into ffmpeg's `drawtext` so the burned-in caption matches the template's brand. See [Generate Caption](/api-reference/content/generate-caption). **After:** write `captionText`, tick the box. ### Step 5: Compose the final 9:16 video (local) The API returns a 16:9 motion clip. Compose locally: crop to 9:16, overlay the song audio for the full duration, and burn in the caption with the styling from step 4. **After:** write `finalVideoPath`, tick the box. With every box ticked, the music video is complete. ## Step 6: Publish (optional) Once the MP4 is rendered, push it to the artist's socials with the [Connectors API](/api-reference/connectors/list). One heads-up worth knowing: - **TikTok URL ownership.** `TIKTOK_PUBLISH_VIDEO` (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. `fal.media` URLs will fail with `url_ownership_unverified` — use `TIKTOK_UPLOAD_VIDEO` instead, which accepts the same URL and uploads server-side. --- The checklist is the source of truth — if a box isn't ticked, treat the step as not run. "},{"slug":"api-reference/content/create","title":"Create Content","description":"Trigger 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).","category":"Content","group":"Content Creation","source":"api-reference/content/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/create","spec":"content.json"},"searchText":"Create Content Trigger 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). Content Content Creation POST /api/content/create "},{"slug":"api-reference/content/generate-image","title":"Generate Image","description":"Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL.","category":"Content","group":"Content Creation","source":"api-reference/content/generate-image.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/image","spec":"content.json"},"searchText":"Generate Image Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL. Content Content Creation POST /api/content/image "},{"slug":"api-reference/content/generate-video","title":"Generate Video","description":"Generate a video from a text prompt, optionally animating a still image (`image_url`) or transitioning between two images (`image_url` + `end_image_url`).","category":"Content","group":"Content Creation","source":"api-reference/content/generate-video.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/video","spec":"content.json"},"searchText":"Generate Video Generate a video from a text prompt, optionally animating a still image (`image_url`) or transitioning between two images (`image_url` + `end_image_url`). Content Content Creation POST /api/content/video "},{"slug":"api-reference/content/generate-caption","title":"Generate Caption","description":"Generate a short caption from a topic. Returns the text content and default styling (font, color, size).","category":"Content","group":"Content Creation","source":"api-reference/content/generate-caption.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/caption","spec":"content.json"},"searchText":"Generate Caption Generate a short caption from a topic. Returns the text content and default styling (font, color, size). Content Content Creation POST /api/content/caption "},{"slug":"api-reference/content/transcribe-audio","title":"Transcribe Audio","description":"Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments.","category":"Content","group":"Content Creation","source":"api-reference/content/transcribe-audio.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/transcribe","spec":"content.json"},"searchText":"Transcribe Audio Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments. Content Content Creation POST /api/content/transcribe "},{"slug":"api-reference/content/edit","title":"Edit Content","description":"Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.","category":"Content","group":"Content Creation","source":"api-reference/content/edit.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/content","spec":"content.json"},"searchText":"Edit Content Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array. Content Content Creation PATCH /api/content "},{"slug":"api-reference/content/upscale","title":"Upscale Content","description":"Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL.","category":"Content","group":"Content Creation","source":"api-reference/content/upscale.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/upscale","spec":"content.json"},"searchText":"Upscale Content Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL. Content Content Creation POST /api/content/upscale "},{"slug":"api-reference/content/analyze-video","title":"Analyze Video","description":"Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text.","category":"Content","group":"Content Creation","source":"api-reference/content/analyze-video.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/analyze","spec":"content.json"},"searchText":"Analyze Video Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text. Content Content Creation POST /api/content/analyze "},{"slug":"api-reference/content/templates","title":"List Templates","description":"List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one.","category":"Content","group":"Content Creation","source":"api-reference/content/templates.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/templates","spec":"content.json"},"searchText":"List Templates List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one. Content Content Creation GET /api/content/templates "},{"slug":"api-reference/content/template-detail","title":"Get Template Detail","description":"Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations.","category":"Content","group":"Content Creation","source":"api-reference/content/template-detail.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/templates/{id}","spec":"content.json"},"searchText":"Get Template Detail Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations. Content Content Creation GET /api/content/templates/{id} "},{"slug":"api-reference/content/validate","title":"Validate Artist","description":"Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter.","category":"Content","group":"Content Creation","source":"api-reference/content/validate.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/validate","spec":"content.json"},"searchText":"Validate Artist Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter. Content Content Creation GET /api/content/validate "},{"slug":"api-reference/content/estimate","title":"Estimate Cost","description":"Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits.","category":"Content","group":"Content Creation","source":"api-reference/content/estimate.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/estimate","spec":"content.json"},"searchText":"Estimate Cost Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits. Content Content Creation GET /api/content/estimate "},{"slug":"api-reference/image/generation","title":"Generate Image","description":"Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking.","category":"Content","group":"Content Creation","source":"api-reference/image/generation.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/image/generate","spec":"content.json"},"searchText":"Generate Image Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking. Content Content Creation GET /api/image/generate "},{"slug":"api-reference/transcribe/audio","title":"Transcribe Audio","description":"Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage. The owner account is derived from your credentials; you must have access to the specified artist_account_id.","category":"Content","group":"Content Creation","source":"api-reference/transcribe/audio.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/transcribe","spec":"content.json"},"searchText":"Transcribe Audio Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage. The owner account is derived from your credentials; you must have access to the specified artist_account_id. Content Content Creation POST /api/transcribe "},{"slug":"api-reference/content/lipsync","title":"Generate lipsync (release pending)","description":"Generate audio-driven video (release pending)","category":"Content","group":"Content Creation","source":"api-reference/content/lipsync.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/lipsync","spec":"content.json"},"searchText":"Generate lipsync (release pending) Generate audio-driven video (release pending) Content Content Creation POST /api/content/lipsync "},{"slug":"api-reference/music/generate","title":"Generate Music","description":"Generate music","category":"Content","group":"Music","source":"api-reference/music/generate.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/music","spec":"content.json"},"searchText":"Generate Music Generate music Content Music POST /api/music "},{"slug":"api-reference/music/list","title":"List Music Generations","description":"List music generations","category":"Content","group":"Music","source":"api-reference/music/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/music","spec":"content.json"},"searchText":"List Music Generations List music generations Content Music GET /api/music "},{"slug":"api-reference/music/get","title":"Get Music Generation","description":"Get music generation","category":"Content","group":"Music","source":"api-reference/music/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/music/{generationId}","spec":"content.json"},"searchText":"Get Music Generation Get music generation Content Music GET /api/music/{generationId} "},{"slug":"api-reference/music/legacy","title":"Music API migration","description":"Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths.","category":"Content","group":"Music","source":"api-reference/music/legacy.mdx","body":"## Generate a song now\n\nUse [`POST /api/music`](/api-reference/music/generate) with a prompt and lyrics.\nIt returns `202` with a generation record; poll\n[`GET /api/music/{generationId}`](/api-reference/music/get) for completion and\nthe resulting audio URL. It does not return audio in the initial response.\nSee the current reference for accepted settings, account scope and credits.\n\n## Former music routes\n\nThe six POST paths below are retired from the callable specification because\nthey have no implemented handlers in the current API. They are not aliases for\n`POST /api/music`. Their specialized outcomes are not equivalent to ordinary\nsong generation and are not declared canceled by this correction.\n\n| Former path | Current choice and remaining limit |\n| --- | --- |\n| `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. |\n| `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. |\n| `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. |\n| `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. |\n| `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. |\n| `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. |\n\n## What remains undecided\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the\nspecialized capability decisions. The current music-generation implementation\nis tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and\n[API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every\nformer capability. An agent or local skill may help prepare inputs, but that\ndoes not establish a hosted route or compatibility with the former request.\n\nThis is a reference correction. No provider run or audio-quality check was\nperformed to make these availability statements.\n","headings":[{"title":"Generate a song now","id":"generate-a-song-now"},{"title":"Former music routes","id":"former-music-routes"},{"title":"What remains undecided","id":"what-remains-undecided"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"generate-a-song-now\",\n children: \"Generate a song now\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.a, {\n href: \"/api-reference/music/generate\",\n children: _jsx(_components.code, {\n children: \"POST /api/music\"\n })\n }), \" with a prompt and lyrics.\\nIt returns \", _jsx(_components.code, {\n children: \"202\"\n }), \" with a generation record; poll\\n\", _jsx(_components.a, {\n href: \"/api-reference/music/get\",\n children: _jsx(_components.code, {\n children: \"GET /api/music/{generationId}\"\n })\n }), \" for completion and\\nthe resulting audio URL. It does not return audio in the initial response.\\nSee the current reference for accepted settings, account scope and credits.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"former-music-routes\",\n children: \"Former music routes\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The six POST paths below are retired from the callable specification because\\nthey have no implemented handlers in the current API. They are not aliases for\\n\", _jsx(_components.code, {\n children: \"POST /api/music\"\n }), \". Their specialized outcomes are not equivalent to ordinary\\nsong generation and are not declared canceled by this correction.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Former path\"\n }), _jsx(_components.th, {\n children: \"Current choice and remaining limit\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/compose\"\n })\n }), _jsx(_components.td, {\n children: \"Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/compose/detailed\"\n })\n }), _jsx(_components.td, {\n children: \"Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/plan\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/stream\"\n })\n }), _jsx(_components.td, {\n children: \"Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/video-to-music\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/stem-separation\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems.\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-remains-undecided\",\n children: \"What remains undecided\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" retains the\\nspecialized capability decisions. The current music-generation implementation\\nis tracked in \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/app/issues/1992\",\n children: \"App #1992\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/848\",\n children: \"API #848\"\n }), \"; it is not delivery of every\\nformer capability. An agent or local skill may help prepare inputs, but that\\ndoes not establish a hosted route or compatibility with the former request.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This is a reference correction. No provider run or audio-quality check was\\nperformed to make these availability statements.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Music API migration Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths. Content Music ## Generate a song now Use [`POST /api/music`](/api-reference/music/generate) with a prompt and lyrics. It returns `202` with a generation record; poll [`GET /api/music/{generationId}`](/api-reference/music/get) for completion and the resulting audio URL. It does not return audio in the initial response. See the current reference for accepted settings, account scope and credits. ## Former music routes The six POST paths below are retired from the callable specification because they have no implemented handlers in the current API. They are not aliases for `POST /api/music`. Their specialized outcomes are not equivalent to ordinary song generation and are not declared canceled by this correction. | Former path | Current choice and remaining limit | | --- | --- | | `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. | | `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. | | `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. | | `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. | | `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. | | `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. | ## What remains undecided [Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the specialized capability decisions. The current music-generation implementation is tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and [API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every former capability. An agent or local skill may help prepare inputs, but that does not establish a hosted route or compatibility with the former request. This is a reference correction. No provider run or audio-quality check was performed to make these availability statements. "},{"slug":"api-reference/posts/get","title":"Get Artist Posts","description":"Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections.","category":"Content","group":"Posts & Comments","source":"api-reference/posts/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/posts","spec":"social.json"},"searchText":"Get Artist Posts Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections. Content Posts & Comments GET /api/artists/{id}/posts "},{"slug":"api-reference/comments/get","title":"Get Comments","description":"Read saved comments on an authorized creator’s linked posts","category":"Content","group":"Posts & Comments","source":"api-reference/comments/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/comments","spec":"social.json"},"searchText":"Get Comments Read saved comments on an authorized creator’s linked posts Content Posts & Comments GET /api/comments "},{"slug":"api-reference/social/scrape","title":"Social Scrape","description":"Trigger a scrape of one social profile. Use [Get Artist Socials](/api-reference/artists/socials) first to get the social `id`. The response contains scraper run metadata; poll it with the [Scraper Results API](/api-reference/apify/scraper).","category":"Social Media","group":"Social","source":"api-reference/social/scrape.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/socials/{id}/scrape","spec":"social.json"},"searchText":"Social Scrape Trigger a scrape of one social profile. Use [Get Artist Socials](/api-reference/artists/socials) first to get the social `id`. The response contains scraper run metadata; poll it with the [Scraper Results API](/api-reference/apify/scraper). Social Media Social POST /api/socials/{id}/scrape "},{"slug":"api-reference/artist/socials-scrape","title":"api-reference/artist/socials-scrape","description":"Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper).","category":"Social Media","group":"Social","source":"api-reference/artist/socials-scrape.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/artist/socials/scrape","spec":"releases.json"},"searchText":"api-reference/artist/socials-scrape Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper). Social Media Social POST /api/artist/socials/scrape "},{"slug":"api-reference/spotify/search","title":"Search","description":"Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/search.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/search","spec":"social.json"},"searchText":"Search Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API. Social Media Spotify GET /api/spotify/search "},{"slug":"api-reference/spotify/artist","title":"Get Artist","description":"Get Spotify catalog information for a single artist identified by their unique Spotify ID.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/","spec":"social.json"},"searchText":"Get Artist Get Spotify catalog information for a single artist identified by their unique Spotify ID. Social Media Spotify GET /api/spotify/artist/ "},{"slug":"api-reference/spotify/artist-albums","title":"Get Artist Albums","description":"Get Spotify catalog information about an artist's albums.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist-albums.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/albums","spec":"social.json"},"searchText":"Get Artist Albums Get Spotify catalog information about an artist's albums. Social Media Spotify GET /api/spotify/artist/albums "},{"slug":"api-reference/spotify/artist-top-tracks","title":"Get Artist Top Tracks","description":"Get an artist's top tracks by country.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist-top-tracks.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/topTracks","spec":"social.json"},"searchText":"Get Artist Top Tracks Get an artist's top tracks by country. Social Media Spotify GET /api/spotify/artist/topTracks "},{"slug":"api-reference/spotify/album","title":"Get Album","description":"Get Spotify catalog information for a single album.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/album.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/album","spec":"social.json"},"searchText":"Get Album Get Spotify catalog information for a single album. Social Media Spotify GET /api/spotify/album "},{"slug":"api-reference/apple/songs","title":"Songs by ISRC","description":"Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose.","category":"Social Media","group":"Apple Music","source":"api-reference/apple/songs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/apple/songs","spec":"social.json"},"searchText":"Songs by ISRC Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose. Social Media Apple Music GET /api/apple/songs "},{"slug":"api-reference/apify/scraper","title":"Scraper Results","description":"Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results.","category":"Social Media","group":"Apify","source":"api-reference/apify/scraper.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/apify/runs/{runId}","spec":"social.json"},"searchText":"Scraper Results Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results. Social Media Apify GET /api/apify/runs/{runId} "},{"slug":"api-reference/agents/signup","title":"Agent Signup","description":"Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key.","category":"Agents & Sandboxes","group":"Agent Onboarding","source":"api-reference/agents/signup.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/signup","spec":"accounts.json"},"searchText":"Agent Signup Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key. Agents & Sandboxes Agent Onboarding POST /api/agents/signup "},{"slug":"api-reference/agents/verify","title":"Verify Agent Email","description":"Verify an agent's email with the code sent during signup. Returns an API key on success.","category":"Agents & Sandboxes","group":"Agent Onboarding","source":"api-reference/agents/verify.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/verify","spec":"accounts.json"},"searchText":"Verify Agent Email Verify an agent's email with the code sent during signup. Returns an API key on success. Agents & Sandboxes Agent Onboarding POST /api/agents/verify "},{"slug":"agents","title":"Agents","description":"Verified email onboarding for a separate Recoup REST API key.","category":"Agents & Sandboxes","group":"Agents","source":"agents.mdx","body":"## Use your real account\n\nPrefer [MCP OAuth](/mcp-oauth) for supported AI hosts. REST integrations need a\nseparate API key; an OAuth connection does not export one into your shell.\n\nUse the email verification flow below with an address the user controls. Keep\nthe returned key out of messages and logs, and store it through a secret facility\nor an explicitly approved local environment file. Never use a disposable account\nto recover an existing user's data.\n\nThe source signup contract also supports immediate keys for new `agent+` addresses.\nThat creates a separate identity; it does not grant customer or organization access.\nIt is not the recommended onboarding path for customer work. Multiple API keys per\naccount are supported, without revoking existing keys.\n\n## Standard signup (email verification)\n\nIf you're building a human-facing integration and want the user to verify their real email, use an email address the user controls:\n\nStep 1 — request a verification code:\n\n```bash\ncurl -X POST \"https://api.recoupable.dev/api/agents/signup\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\"}'\n```\n\nStep 2 — submit the 6-digit code from the verification email:\n\n```bash\ncurl -X POST \"https://api.recoupable.dev/api/agents/verify\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"code\": \"123456\"}'\n```\n\nResponse:\n\n```json\n{\n \"account_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"api_key\": \"recoup_sk_abc123...\",\n \"message\": \"Verified\"\n}\n```\n\n## Using your API key\n\nPass the returned `api_key` in the `x-api-key` header on every authenticated request:\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\nSee [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request.\n","headings":[{"title":"Use your real account","id":"use-your-real-account"},{"title":"Standard signup (email verification)","id":"standard-signup-email-verification"},{"title":"Using your API key","id":"using-your-api-key"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"use-your-real-account\",\n children: \"Use your real account\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Prefer \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for supported AI hosts. REST integrations need a\\nseparate API key; an OAuth connection does not export one into your shell.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the email verification flow below with an address the user controls. Keep\\nthe returned key out of messages and logs, and store it through a secret facility\\nor an explicitly approved local environment file. Never use a disposable account\\nto recover an existing user's data.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The source signup contract also supports immediate keys for new \", _jsx(_components.code, {\n children: \"agent+\"\n }), \" addresses.\\nThat creates a separate identity; it does not grant customer or organization access.\\nIt is not the recommended onboarding path for customer work. Multiple API keys per\\naccount are supported, without revoking existing keys.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"standard-signup-email-verification\",\n children: \"Standard signup (email verification)\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you're building a human-facing integration and want the user to verify their real email, use an email address the user controls:\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Step 1 — request a verification code:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X POST \\\"https://api.recoupable.dev/api/agents/signup\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"email\\\": \\\"you@example.com\\\"}'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Step 2 — submit the 6-digit code from the verification email:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X POST \\\"https://api.recoupable.dev/api/agents/verify\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"email\\\": \\\"you@example.com\\\", \\\"code\\\": \\\"123456\\\"}'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\\n \\\"api_key\\\": \\\"recoup_sk_abc123...\\\",\\n \\\"message\\\": \\\"Verified\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"using-your-api-key\",\n children: \"Using your API key\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass the returned \", _jsx(_components.code, {\n children: \"api_key\"\n }), \" in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header on every authenticated request:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"Authentication\"\n }), \" for the full authentication model, including organization access and Bearer token support, and \", _jsx(_components.a, {\n href: \"/quickstart\",\n children: \"Quickstart\"\n }), \" for your first end-to-end request.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Agents Verified email onboarding for a separate Recoup REST API key. Agents & Sandboxes Agents ## Use your real account Prefer [MCP OAuth](/mcp-oauth) for supported AI hosts. REST integrations need a separate API key; an OAuth connection does not export one into your shell. Use the email verification flow below with an address the user controls. Keep the returned key out of messages and logs, and store it through a secret facility or an explicitly approved local environment file. Never use a disposable account to recover an existing user's data. The source signup contract also supports immediate keys for new `agent+` addresses. That creates a separate identity; it does not grant customer or organization access. It is not the recommended onboarding path for customer work. Multiple API keys per account are supported, without revoking existing keys. ## Standard signup (email verification) If you're building a human-facing integration and want the user to verify their real email, use an email address the user controls: Step 1 — request a verification code: Step 2 — submit the 6-digit code from the verification email: Response: ## Using your API key Pass the returned `api_key` in the `x-api-key` header on every authenticated request: See [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request. "},{"slug":"content-agent","title":"Content Agent","description":"Use hosted creative presets and current image, video and composition primitives.","category":"Agents & Sandboxes","group":"Agents","source":"content-agent.mdx","body":"## Release Packs\n\nFor a song-centered content pack, use [Release Packs](/release-packs): collect\nessential context inline, preserve one job, quote the complete scope and produce\nreviewed media. New releases, catalog rediscovery, anniversaries, reissues and\nremixes use the same brief-driven path. These pack operations do not require an\nexisting artist or repository; availability depends on deployed host tools.\n\n## Hosted workflows\n\n`POST /api/content/create` retains the hosted preset workflow. Supply the authorized\n`artist_account_id`, optional `template`, `images`, `songs`, `batch` (defaults to 1; range 1–30), `lipsync`, `upscale`\nand `caption_length`. Discover templates through `/api/content/templates` and its\ndetail route. The response contains `runIds`; poll `/api/tasks/runs?runId=...` until\nterminal. Report failures and inspect the final artifact before delivery.\n\nHosted lipsync is a supported preset intent. The coordinated API/worker repair\nrestores the selected song window to the fixed audio-to-video path; that repaired\njourney is release-pending until deployment and actual output verification.\n\n## Direct primitives\n\nFor images use `POST /api/content/image` with `prompt` and up to 10 unique\n`image_urls`. The house model is Muse Image, switching to its edit path when\nreferences are present. New clients must use `image_urls`; compatibility aliases\nare translated by the reconciliation release.\n\nFor video use `POST /api/content/video` with `prompt`, optional `image_url` and\n`end_image_url`, integer `duration` 5–15, and `resolution` `480P` or `768P`.\nThe house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model,\nreference-only, extend, `video_url` or `audio_url` request control. Unsupported\nsemantic inputs return 400 in the reconciliation release, before paid generation.\n\nThe dedicated `/api/content/lipsync` primitive restores the existing fixed LTX\nmodel for the worker; it is not assumed available on an older deployment.\nCaption, transcribe, analyze, upscale and edit have their own endpoint contracts.\nLocal ffmpeg composition can crop, trim, overlay or mux a song; it does not create\nmouth synchronization or prove a hosted generation succeeded.\n\n## Cost and evidence\n\nEach generation/inference stage can consume credits. `/api/content/estimate`\nreturns an advisory estimate, not a guaranteed price or complete final ledger.\nA later failed composition does not imply that completed upstream work was free.\nOn insufficient credits, surface `billingUrl` and stop. Consult [Credits](/credits).\n\nRecord image inspection, motion review and audio playback. The worker checks for\nan audio stream on lipsync output before composition; perceptual mouth alignment\nstill requires inspection. Automated checks do not replace human QA.\n\n## Slack integration\n\nThe separate [Slack webhook](/api-reference/content-agent/webhook) handles\nContent Agent mentions. Its request/event contract and the [completion callback](/api-reference/content-agent/callback) are distinct from direct primitives.\nWorkspace operators must configure the Slack application and service credentials;\ninstalling a creative skill does not install that integration.\n\n### Set up the Slack app\n\nCreate a Slack app, enable the `chat:write` and `app_mentions:read` bot scopes,\nand subscribe to `app_mention` events at\n`https://api.recoupable.dev/api/content-agent/slack`. Install it in the intended\nworkspace and invite it to the channel.\n\nConfigure `SLACK_CONTENT_BOT_TOKEN`, `SLACK_CONTENT_SIGNING_SECRET`,\n`CODING_AGENT_CALLBACK_SECRET` and `REDIS_URL` in the Recoup API service.\nThe existing Tasks worker uses the same `CODING_AGENT_CALLBACK_SECRET` for\ncompletion callbacks and its authorized Recoup credential and API base URL.\nKeep these values in service secret settings. The current callback secret name\nis `CODING_AGENT_CALLBACK_SECRET`; `CONTENT_AGENT_CALLBACK_SECRET` is obsolete.\n\nSlack sends the signed-request headers listed in the [webhook reference](/api-reference/content-agent/webhook).\nKeep `SLACK_CONTENT_SIGNING_SECRET` matched to that Slack app. Setup requests\nwith missing or invalid signatures, a timestamp outside the five-minute window,\nor an unavailable signing secret return `401` with plain-text `Unauthorized`.\nA verified setup request returns its JSON challenge. If setup fails, check the\napp secret and service clock against [Slack request verification](https://docs.slack.dev/authentication/verifying-requests-from-slack/).\nOrdinary event acknowledgements come from the Slack adapter; they acknowledge\nreceipt while generation completes separately.\n\nMention the installed bot with the authorized artist account UUID:\n\n```text\n@RecoupContentAgent ARTIST_ACCOUNT_UUID artist-caption-bedroom batch=1\n```\n\nThe template, `batch=N` (1–30) and `lipsync` flags are optional. Check the\nacknowledgment, then inspect the completed result or reported failure in the\nthread. Generated output still requires the inspection described above.\n","headings":[{"title":"Release Packs","id":"release-packs"},{"title":"Hosted workflows","id":"hosted-workflows"},{"title":"Direct primitives","id":"direct-primitives"},{"title":"Cost and evidence","id":"cost-and-evidence"},{"title":"Slack integration","id":"slack-integration"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"release-packs\",\n children: \"Release Packs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a song-centered content pack, use \", _jsx(_components.a, {\n href: \"/release-packs\",\n children: \"Release Packs\"\n }), \": collect\\nessential context inline, preserve one job, quote the complete scope and produce\\nreviewed media. New releases, catalog rediscovery, anniversaries, reissues and\\nremixes use the same brief-driven path. These pack operations do not require an\\nexisting artist or repository; availability depends on deployed host tools.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hosted-workflows\",\n children: \"Hosted workflows\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/create\"\n }), \" retains the hosted preset workflow. Supply the authorized\\n\", _jsx(_components.code, {\n children: \"artist_account_id\"\n }), \", optional \", _jsx(_components.code, {\n children: \"template\"\n }), \", \", _jsx(_components.code, {\n children: \"images\"\n }), \", \", _jsx(_components.code, {\n children: \"songs\"\n }), \", \", _jsx(_components.code, {\n children: \"batch\"\n }), \" (defaults to 1; range 1–30), \", _jsx(_components.code, {\n children: \"lipsync\"\n }), \", \", _jsx(_components.code, {\n children: \"upscale\"\n }), \"\\nand \", _jsx(_components.code, {\n children: \"caption_length\"\n }), \". Discover templates through \", _jsx(_components.code, {\n children: \"/api/content/templates\"\n }), \" and its\\ndetail route. The response contains \", _jsx(_components.code, {\n children: \"runIds\"\n }), \"; poll \", _jsx(_components.code, {\n children: \"/api/tasks/runs?runId=...\"\n }), \" until\\nterminal. Report failures and inspect the final artifact before delivery.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Hosted lipsync is a supported preset intent. The coordinated API/worker repair\\nrestores the selected song window to the fixed audio-to-video path; that repaired\\njourney is release-pending until deployment and actual output verification.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"direct-primitives\",\n children: \"Direct primitives\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For images use \", _jsx(_components.code, {\n children: \"POST /api/content/image\"\n }), \" with \", _jsx(_components.code, {\n children: \"prompt\"\n }), \" and up to 10 unique\\n\", _jsx(_components.code, {\n children: \"image_urls\"\n }), \". The house model is Muse Image, switching to its edit path when\\nreferences are present. New clients must use \", _jsx(_components.code, {\n children: \"image_urls\"\n }), \"; compatibility aliases\\nare translated by the reconciliation release.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For video use \", _jsx(_components.code, {\n children: \"POST /api/content/video\"\n }), \" with \", _jsx(_components.code, {\n children: \"prompt\"\n }), \", optional \", _jsx(_components.code, {\n children: \"image_url\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"end_image_url\"\n }), \", integer \", _jsx(_components.code, {\n children: \"duration\"\n }), \" 5–15, and \", _jsx(_components.code, {\n children: \"resolution\"\n }), \" \", _jsx(_components.code, {\n children: \"480P\"\n }), \" or \", _jsx(_components.code, {\n children: \"768P\"\n }), \".\\nThe house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model,\\nreference-only, extend, \", _jsx(_components.code, {\n children: \"video_url\"\n }), \" or \", _jsx(_components.code, {\n children: \"audio_url\"\n }), \" request control. Unsupported\\nsemantic inputs return 400 in the reconciliation release, before paid generation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The dedicated \", _jsx(_components.code, {\n children: \"/api/content/lipsync\"\n }), \" primitive restores the existing fixed LTX\\nmodel for the worker; it is not assumed available on an older deployment.\\nCaption, transcribe, analyze, upscale and edit have their own endpoint contracts.\\nLocal ffmpeg composition can crop, trim, overlay or mux a song; it does not create\\nmouth synchronization or prove a hosted generation succeeded.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"cost-and-evidence\",\n children: \"Cost and evidence\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each generation/inference stage can consume credits. \", _jsx(_components.code, {\n children: \"/api/content/estimate\"\n }), \"\\nreturns an advisory estimate, not a guaranteed price or complete final ledger.\\nA later failed composition does not imply that completed upstream work was free.\\nOn insufficient credits, surface \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \" and stop. Consult \", _jsx(_components.a, {\n href: \"/credits\",\n children: \"Credits\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Record image inspection, motion review and audio playback. The worker checks for\\nan audio stream on lipsync output before composition; perceptual mouth alignment\\nstill requires inspection. Automated checks do not replace human QA.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"slack-integration\",\n children: \"Slack integration\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The separate \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/webhook\",\n children: \"Slack webhook\"\n }), \" handles\\nContent Agent mentions. Its request/event contract and the \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/callback\",\n children: \"completion callback\"\n }), \" are distinct from direct primitives.\\nWorkspace operators must configure the Slack application and service credentials;\\ninstalling a creative skill does not install that integration.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"set-up-the-slack-app\",\n children: \"Set up the Slack app\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Create a Slack app, enable the \", _jsx(_components.code, {\n children: \"chat:write\"\n }), \" and \", _jsx(_components.code, {\n children: \"app_mentions:read\"\n }), \" bot scopes,\\nand subscribe to \", _jsx(_components.code, {\n children: \"app_mention\"\n }), \" events at\\n\", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/api/content-agent/slack\"\n }), \". Install it in the intended\\nworkspace and invite it to the channel.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Configure \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_BOT_TOKEN\"\n }), \", \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_SIGNING_SECRET\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \" and \", _jsx(_components.code, {\n children: \"REDIS_URL\"\n }), \" in the Recoup API service.\\nThe existing Tasks worker uses the same \", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \" for\\ncompletion callbacks and its authorized Recoup credential and API base URL.\\nKeep these values in service secret settings. The current callback secret name\\nis \", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \"; \", _jsx(_components.code, {\n children: \"CONTENT_AGENT_CALLBACK_SECRET\"\n }), \" is obsolete.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Slack sends the signed-request headers listed in the \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/webhook\",\n children: \"webhook reference\"\n }), \".\\nKeep \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_SIGNING_SECRET\"\n }), \" matched to that Slack app. Setup requests\\nwith missing or invalid signatures, a timestamp outside the five-minute window,\\nor an unavailable signing secret return \", _jsx(_components.code, {\n children: \"401\"\n }), \" with plain-text \", _jsx(_components.code, {\n children: \"Unauthorized\"\n }), \".\\nA verified setup request returns its JSON challenge. If setup fails, check the\\napp secret and service clock against \", _jsx(_components.a, {\n href: \"https://docs.slack.dev/authentication/verifying-requests-from-slack/\",\n children: \"Slack request verification\"\n }), \".\\nOrdinary event acknowledgements come from the Slack adapter; they acknowledge\\nreceipt while generation completes separately.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Mention the installed bot with the authorized artist account UUID:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-text\",\n children: \"@RecoupContentAgent ARTIST_ACCOUNT_UUID artist-caption-bedroom batch=1\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The template, \", _jsx(_components.code, {\n children: \"batch=N\"\n }), \" (1–30) and \", _jsx(_components.code, {\n children: \"lipsync\"\n }), \" flags are optional. Check the\\nacknowledgment, then inspect the completed result or reported failure in the\\nthread. Generated output still requires the inspection described above.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Content Agent Use hosted creative presets and current image, video and composition primitives. Agents & Sandboxes Agents ## Release Packs For a song-centered content pack, use [Release Packs](/release-packs): collect essential context inline, preserve one job, quote the complete scope and produce reviewed media. New releases, catalog rediscovery, anniversaries, reissues and remixes use the same brief-driven path. These pack operations do not require an existing artist or repository; availability depends on deployed host tools. ## Hosted workflows `POST /api/content/create` retains the hosted preset workflow. Supply the authorized `artist_account_id`, optional `template`, `images`, `songs`, `batch` (defaults to 1; range 1–30), `lipsync`, `upscale` and `caption_length`. Discover templates through `/api/content/templates` and its detail route. The response contains `runIds`; poll `/api/tasks/runs?runId=...` until terminal. Report failures and inspect the final artifact before delivery. Hosted lipsync is a supported preset intent. The coordinated API/worker repair restores the selected song window to the fixed audio-to-video path; that repaired journey is release-pending until deployment and actual output verification. ## Direct primitives For images use `POST /api/content/image` with `prompt` and up to 10 unique `image_urls`. The house model is Muse Image, switching to its edit path when references are present. New clients must use `image_urls`; compatibility aliases are translated by the reconciliation release. For video use `POST /api/content/video` with `prompt`, optional `image_url` and `end_image_url`, integer `duration` 5–15, and `resolution` `480P` or `768P`. The house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model, reference-only, extend, `video_url` or `audio_url` request control. Unsupported semantic inputs return 400 in the reconciliation release, before paid generation. The dedicated `/api/content/lipsync` primitive restores the existing fixed LTX model for the worker; it is not assumed available on an older deployment. Caption, transcribe, analyze, upscale and edit have their own endpoint contracts. Local ffmpeg composition can crop, trim, overlay or mux a song; it does not create mouth synchronization or prove a hosted generation succeeded. ## Cost and evidence Each generation/inference stage can consume credits. `/api/content/estimate` returns an advisory estimate, not a guaranteed price or complete final ledger. A later failed composition does not imply that completed upstream work was free. On insufficient credits, surface `billingUrl` and stop. Consult [Credits](/credits). Record image inspection, motion review and audio playback. The worker checks for an audio stream on lipsync output before composition; perceptual mouth alignment still requires inspection. Automated checks do not replace human QA. ## Slack integration The separate [Slack webhook](/api-reference/content-agent/webhook) handles Content Agent mentions. Its request/event contract and the [completion callback](/api-reference/content-agent/callback) are distinct from direct primitives. Workspace operators must configure the Slack application and service credentials; installing a creative skill does not install that integration. ### Set up the Slack app Create a Slack app, enable the `chat:write` and `app_mentions:read` bot scopes, and subscribe to `app_mention` events at `https://api.recoupable.dev/api/content-agent/slack`. Install it in the intended workspace and invite it to the channel. Configure `SLACK_CONTENT_BOT_TOKEN`, `SLACK_CONTENT_SIGNING_SECRET`, `CODING_AGENT_CALLBACK_SECRET` and `REDIS_URL` in the Recoup API service. The existing Tasks worker uses the same `CODING_AGENT_CALLBACK_SECRET` for completion callbacks and its authorized Recoup credential and API base URL. Keep these values in service secret settings. The current callback secret name is `CODING_AGENT_CALLBACK_SECRET`; `CONTENT_AGENT_CALLBACK_SECRET` is obsolete. Slack sends the signed-request headers listed in the [webhook reference](/api-reference/content-agent/webhook). Keep `SLACK_CONTENT_SIGNING_SECRET` matched to that Slack app. Setup requests with missing or invalid signatures, a timestamp outside the five-minute window, or an unavailable signing secret return `401` with plain-text `Unauthorized`. A verified setup request returns its JSON challenge. If setup fails, check the app secret and service clock against [Slack request verification](https://docs.slack.dev/authentication/verifying-requests-from-slack/). Ordinary event acknowledgements come from the Slack adapter; they acknowledge receipt while generation completes separately. Mention the installed bot with the authorized artist account UUID: The template, `batch=N` (1–30) and `lipsync` flags are optional. Check the acknowledgment, then inspect the completed result or reported failure in the thread. Generated output still requires the inspection described above. "},{"slug":"release-packs","title":"Release Packs","description":"Turn a song and a campaign occasion into a coherent set of reviewed music assets.","category":"Agents & Sandboxes","group":"Agents","source":"release-packs.mdx","body":"\nThis contract accompanies the Release Packs first-use rollout. Availability depends\non the deployed API and the tools exposed by your connected host. A plugin download\nor successful sign-in alone does not establish that generation is available.\n\n\n## Start with the music\n\nAsk your agent: **“Create a release pack for this song.”** Supply the audio or an\naccessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a\nreissue, a remix, or a catalog rediscovery campaign.\n\nThe agent reuses information you have already supplied and any selected, accessible\nRecoup context. It asks only for essential gaps: the correct artist and recording,\nthe occasion, and artwork or creative direction. You can ask it to propose a\ndirection from the music instead. It must distinguish that proposal from your\nestablished branding.\n\nYou do not need an existing artist profile, Spotify history, connected social\naccounts, a catalog import, or a GitHub workspace to prepare a pack. An empty\nRecoup roster is a valid new account. Sign in through your host's Recoup connection\nwhen the agent needs authenticated execution; it should resume the same request.\n\n**“Plan a release” is a different request.** It produces a creative brief and\nrollout plan. Ask for a release pack to produce media, or ask for both so the agent\ncan carry the same brief into production.\n\nWhen ChatGPT supplies a selected attachment to the upload tool, the tool accepts\nits host file reference directly. It imports the selected download URL into\nprivate Recoup storage and validates the actual media bytes. Other hosts can use\nthe supported source URL, inline or signed-upload modes; a filename alone is not\nan accessible recording.\n\nFor direct API uploads, small inline files are limited to approximately 3 MB\n(4,000,000 base64 characters). For normal song files, request a private signed\nupload, transfer the file and finalize it, or import an accessible HTTPS source\nup to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable\nonly after the agent can access its actual bytes. Audio formats include MP3,\nWAV, FLAC and M4A. Source images can be PNG, JPEG or WebP.\n\n## What the brief contains\n\n| Input | How it is used |\n| --- | --- |\n| Artist, song and exact version | Keep the recording, remix and artist identity consistent |\n| Real audio and selected hook | Put the correct music into the finished clips |\n| Occasion | Choose relevant concepts and copy rather than defaulting to “out now” |\n| Creative direction or references | Keep a coherent visual family and voice |\n| Primary action and destination | Write relevant captions without inventing links |\n| Audience, platforms and constraints | Choose useful formats and respect supplied boundaries |\n\nFor anniversaries, the original release date and campaign date are separate. If\nthe original date is unknown, the agent must obtain it before making dated\nanniversary claims. A catalog request needs a bounded selection of recordings;\nit must not silently generate a pack for every track.\n\nResearch enriches the brief. Missing research or audience metrics should not\nforce unrelated onboarding or fabricated statistics. Existing artwork and\nsupplied preferences can be enough to propose strong creative work. An artist's\nface is optional; artwork-led and typographic work are valid directions.\n\n## Scope and budget before generation\n\n### Save a direction and choose how involved to be\n\nConnections exposing `brief.creative_context` can save an established visual world,\na rough idea or an exploratory direction in the same pack. The field is optional;\nolder connections keep their existing brief behavior. It holds attributed references,\nup to three direction candidates and the selected candidate.\n\n**Run with it** uses `working_mode: \"autonomous\"`: the agent records its direction\nselection and continues within the approved budget. **Show me directions first**\nuses `working_mode: \"guided\"`: final quoting and generation wait for a selection\nrecorded from the customer's feedback. An agent's own choice does not count as\ncustomer selection in guided mode.\n\nSave candidates under `directions`, then record `selection.direction_id`,\n`selection.selected_by` (`customer` or `agent`) and a short `decision_note`.\nDirection and reference IDs must be unique within this brief; selections cannot\npoint to another pack's candidate. Updating these fields follows the same saved\njob and expected-revision rules and invalidates its earlier quote.\n\nA reference manifest item declares its source, media type and `usage`:\n`reference_only` is inspiration, while `production` explicitly makes an image\neligible as a selected generation input. Only production images referenced by\nthe chosen direction enter the renderer. Together with explicit legacy\n`reference_image_urls`, at most five distinct production images are supported.\nThe original source manifest stays unchanged when production inputs are resolved.\n\nThis first slice accepts supplied direction boards through an optional `board_url`.\nIt does not add automatic mood-board generation, public-profile harvesting or new\nasset types. Discover those capabilities before promising them. An optional\ncustomer checkpoint does not authorize additional spending or publication.\n\nPreparation and generation are separate operations. Before paid production, the\nagent shows the proposed direction, deliverables, cost scope and maximum budget.\nThe quote binds the current brief and deliverables. Changing the song or scope\nrequires a new quote; an earlier approval cannot silently authorize different work.\n\nThe default scope is 15 creative pieces: eight video clips, four quote cards, one\nartwork, one carousel and one visualizer, with captions. A carousel is one piece;\nits slides and alternate aspect ratios are identified as components or variants.\nYou can request a smaller scope. The quote must describe the actual selected work,\nincluding chargeable stages and any retry allowance. Current quotes charge for\nimage and motion generation; captioning, audio analysis, composition and inspection\nare included without an added customer fee. The approved amount is held before\nproduction; unused stages are refunded. A new paid retry needs its own quote.\n\nThe older `GET /api/content/estimate` is an advisory per-video estimate. It is not\na complete Release Packs quote. On insufficient credits the agent surfaces the\nreturned `billingUrl`; it must not buy credits, switch accounts or retry paid\ngeneration automatically.\n\n## One job, with visible progress\n\nThe pack retains its brief, revision, quote, individual asset states and completed\nwork. Signing in, waiting for a render, or recovering from a failed stage should\nnot make you repeat the request or regenerate the whole pack.\n\nThe first representative asset is produced and inspected early. The agent then\ncontinues the agreed batch within your budget, unless you requested a preview\ncheckpoint. Progress distinguishes requested, generated, inspected and delivered\nassets. A partly generated pack is reported as partial.\n\n## Review and delivery\n\nA finished music-bearing asset must contain the selected recording and the correct\naudio window. Inspection covers sound, timing, duration, framing, readable text,\nvisual consistency and the campaign brief. A render request, a prompt or a concept\nis not a finished asset. Static image inspection and video inspection are separate.\n\nDelivery includes previews, usable files, captions, a manifest and any unresolved\ngaps. The agent retains successful work when a stage fails and retries only within\nthe approved scope and budget. Release Packs stops at the assets: posting and\nscheduling need a separate request.\n\nAfter delivery, you can save confirmed artist preferences for next time. A\none-off creative proposal must not overwrite established branding or become a\npermanent public knowledge-base entry automatically.\n\n## API and connected tools\n\nConnected operations are `prepare_release_pack`, `get_release_pack`,\n`estimate_release_pack`, `generate_release_pack`, `retry_release_pack`,\n`upload_release_pack_asset` and `export_release_pack`. Discover their actual schemas\nin the connected host; older connections may need a refresh.\n\nThe shared API contract separates preparation, reading, quoting, generation,\nretry and selected-asset upload. Connected tools use the same account and job\nrules. Credentials remain with the host; an agent must not extract OAuth tokens\ninto REST requests or ask for an API key to compensate for a missing MCP tool.\n\nIf a required operation is unavailable, the agent should name that operation,\nretain the brief and explain the next step. It must not claim the entire account\nis disconnected or present a plan as completed media.\n","headings":[{"title":"Start with the music","id":"start-with-the-music"},{"title":"What the brief contains","id":"what-the-brief-contains"},{"title":"Scope and budget before generation","id":"scope-and-budget-before-generation"},{"title":"One job, with visible progress","id":"one-job-with-visible-progress"},{"title":"Review and delivery","id":"review-and-delivery"},{"title":"API and connected tools","id":"api-and-connected-tools"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n }, {Info} = _components;\n if (!Info) _missingMdxReference(\"Info\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Info, {\n children: _jsx(_components.p, {\n children: \"This contract accompanies the Release Packs first-use rollout. Availability depends\\non the deployed API and the tools exposed by your connected host. A plugin download\\nor successful sign-in alone does not establish that generation is available.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"start-with-the-music\",\n children: \"Start with the music\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Ask your agent: \", _jsx(_components.strong, {\n children: \"“Create a release pack for this song.”\"\n }), \" Supply the audio or an\\naccessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a\\nreissue, a remix, or a catalog rediscovery campaign.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The agent reuses information you have already supplied and any selected, accessible\\nRecoup context. It asks only for essential gaps: the correct artist and recording,\\nthe occasion, and artwork or creative direction. You can ask it to propose a\\ndirection from the music instead. It must distinguish that proposal from your\\nestablished branding.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"You do not need an existing artist profile, Spotify history, connected social\\naccounts, a catalog import, or a GitHub workspace to prepare a pack. An empty\\nRecoup roster is a valid new account. Sign in through your host's Recoup connection\\nwhen the agent needs authenticated execution; it should resume the same request.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"“Plan a release” is a different request.\"\n }), \" It produces a creative brief and\\nrollout plan. Ask for a release pack to produce media, or ask for both so the agent\\ncan carry the same brief into production.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"When ChatGPT supplies a selected attachment to the upload tool, the tool accepts\\nits host file reference directly. It imports the selected download URL into\\nprivate Recoup storage and validates the actual media bytes. Other hosts can use\\nthe supported source URL, inline or signed-upload modes; a filename alone is not\\nan accessible recording.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"For direct API uploads, small inline files are limited to approximately 3 MB\\n(4,000,000 base64 characters). For normal song files, request a private signed\\nupload, transfer the file and finalize it, or import an accessible HTTPS source\\nup to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable\\nonly after the agent can access its actual bytes. Audio formats include MP3,\\nWAV, FLAC and M4A. Source images can be PNG, JPEG or WebP.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-the-brief-contains\",\n children: \"What the brief contains\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Input\"\n }), _jsx(_components.th, {\n children: \"How it is used\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Artist, song and exact version\"\n }), _jsx(_components.td, {\n children: \"Keep the recording, remix and artist identity consistent\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Real audio and selected hook\"\n }), _jsx(_components.td, {\n children: \"Put the correct music into the finished clips\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Occasion\"\n }), _jsx(_components.td, {\n children: \"Choose relevant concepts and copy rather than defaulting to “out now”\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Creative direction or references\"\n }), _jsx(_components.td, {\n children: \"Keep a coherent visual family and voice\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Primary action and destination\"\n }), _jsx(_components.td, {\n children: \"Write relevant captions without inventing links\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Audience, platforms and constraints\"\n }), _jsx(_components.td, {\n children: \"Choose useful formats and respect supplied boundaries\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For anniversaries, the original release date and campaign date are separate. If\\nthe original date is unknown, the agent must obtain it before making dated\\nanniversary claims. A catalog request needs a bounded selection of recordings;\\nit must not silently generate a pack for every track.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Research enriches the brief. Missing research or audience metrics should not\\nforce unrelated onboarding or fabricated statistics. Existing artwork and\\nsupplied preferences can be enough to propose strong creative work. An artist's\\nface is optional; artwork-led and typographic work are valid directions.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"scope-and-budget-before-generation\",\n children: \"Scope and budget before generation\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"save-a-direction-and-choose-how-involved-to-be\",\n children: \"Save a direction and choose how involved to be\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connections exposing \", _jsx(_components.code, {\n children: \"brief.creative_context\"\n }), \" can save an established visual world,\\na rough idea or an exploratory direction in the same pack. The field is optional;\\nolder connections keep their existing brief behavior. It holds attributed references,\\nup to three direction candidates and the selected candidate.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Run with it\"\n }), \" uses \", _jsx(_components.code, {\n children: \"working_mode: \\\"autonomous\\\"\"\n }), \": the agent records its direction\\nselection and continues within the approved budget. \", _jsx(_components.strong, {\n children: \"Show me directions first\"\n }), \"\\nuses \", _jsx(_components.code, {\n children: \"working_mode: \\\"guided\\\"\"\n }), \": final quoting and generation wait for a selection\\nrecorded from the customer's feedback. An agent's own choice does not count as\\ncustomer selection in guided mode.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save candidates under \", _jsx(_components.code, {\n children: \"directions\"\n }), \", then record \", _jsx(_components.code, {\n children: \"selection.direction_id\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"selection.selected_by\"\n }), \" (\", _jsx(_components.code, {\n children: \"customer\"\n }), \" or \", _jsx(_components.code, {\n children: \"agent\"\n }), \") and a short \", _jsx(_components.code, {\n children: \"decision_note\"\n }), \".\\nDirection and reference IDs must be unique within this brief; selections cannot\\npoint to another pack's candidate. Updating these fields follows the same saved\\njob and expected-revision rules and invalidates its earlier quote.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A reference manifest item declares its source, media type and \", _jsx(_components.code, {\n children: \"usage\"\n }), \":\\n\", _jsx(_components.code, {\n children: \"reference_only\"\n }), \" is inspiration, while \", _jsx(_components.code, {\n children: \"production\"\n }), \" explicitly makes an image\\neligible as a selected generation input. Only production images referenced by\\nthe chosen direction enter the renderer. Together with explicit legacy\\n\", _jsx(_components.code, {\n children: \"reference_image_urls\"\n }), \", at most five distinct production images are supported.\\nThe original source manifest stays unchanged when production inputs are resolved.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This first slice accepts supplied direction boards through an optional \", _jsx(_components.code, {\n children: \"board_url\"\n }), \".\\nIt does not add automatic mood-board generation, public-profile harvesting or new\\nasset types. Discover those capabilities before promising them. An optional\\ncustomer checkpoint does not authorize additional spending or publication.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Preparation and generation are separate operations. Before paid production, the\\nagent shows the proposed direction, deliverables, cost scope and maximum budget.\\nThe quote binds the current brief and deliverables. Changing the song or scope\\nrequires a new quote; an earlier approval cannot silently authorize different work.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The default scope is 15 creative pieces: eight video clips, four quote cards, one\\nartwork, one carousel and one visualizer, with captions. A carousel is one piece;\\nits slides and alternate aspect ratios are identified as components or variants.\\nYou can request a smaller scope. The quote must describe the actual selected work,\\nincluding chargeable stages and any retry allowance. Current quotes charge for\\nimage and motion generation; captioning, audio analysis, composition and inspection\\nare included without an added customer fee. The approved amount is held before\\nproduction; unused stages are refunded. A new paid retry needs its own quote.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The older \", _jsx(_components.code, {\n children: \"GET /api/content/estimate\"\n }), \" is an advisory per-video estimate. It is not\\na complete Release Packs quote. On insufficient credits the agent surfaces the\\nreturned \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \"; it must not buy credits, switch accounts or retry paid\\ngeneration automatically.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"one-job-with-visible-progress\",\n children: \"One job, with visible progress\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The pack retains its brief, revision, quote, individual asset states and completed\\nwork. Signing in, waiting for a render, or recovering from a failed stage should\\nnot make you repeat the request or regenerate the whole pack.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The first representative asset is produced and inspected early. The agent then\\ncontinues the agreed batch within your budget, unless you requested a preview\\ncheckpoint. Progress distinguishes requested, generated, inspected and delivered\\nassets. A partly generated pack is reported as partial.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"review-and-delivery\",\n children: \"Review and delivery\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"A finished music-bearing asset must contain the selected recording and the correct\\naudio window. Inspection covers sound, timing, duration, framing, readable text,\\nvisual consistency and the campaign brief. A render request, a prompt or a concept\\nis not a finished asset. Static image inspection and video inspection are separate.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Delivery includes previews, usable files, captions, a manifest and any unresolved\\ngaps. The agent retains successful work when a stage fails and retries only within\\nthe approved scope and budget. Release Packs stops at the assets: posting and\\nscheduling need a separate request.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"After delivery, you can save confirmed artist preferences for next time. A\\none-off creative proposal must not overwrite established branding or become a\\npermanent public knowledge-base entry automatically.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"api-and-connected-tools\",\n children: \"API and connected tools\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connected operations are \", _jsx(_components.code, {\n children: \"prepare_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"get_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"estimate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"generate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"retry_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"upload_release_pack_asset\"\n }), \" and \", _jsx(_components.code, {\n children: \"export_release_pack\"\n }), \". Discover their actual schemas\\nin the connected host; older connections may need a refresh.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The shared API contract separates preparation, reading, quoting, generation,\\nretry and selected-asset upload. Connected tools use the same account and job\\nrules. Credentials remain with the host; an agent must not extract OAuth tokens\\ninto REST requests or ask for an API key to compensate for a missing MCP tool.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If a required operation is unavailable, the agent should name that operation,\\nretain the brief and explain the next step. It must not claim the entire account\\nis disconnected or present a plan as completed media.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Release Packs Turn a song and a campaign occasion into a coherent set of reviewed music assets. Agents & Sandboxes Agents This contract accompanies the Release Packs first-use rollout. Availability depends on the deployed API and the tools exposed by your connected host. A plugin download or successful sign-in alone does not establish that generation is available. ## Start with the music Ask your agent: **“Create a release pack for this song.”** Supply the audio or an accessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a reissue, a remix, or a catalog rediscovery campaign. The agent reuses information you have already supplied and any selected, accessible Recoup context. It asks only for essential gaps: the correct artist and recording, the occasion, and artwork or creative direction. You can ask it to propose a direction from the music instead. It must distinguish that proposal from your established branding. You do not need an existing artist profile, Spotify history, connected social accounts, a catalog import, or a GitHub workspace to prepare a pack. An empty Recoup roster is a valid new account. Sign in through your host's Recoup connection when the agent needs authenticated execution; it should resume the same request. **“Plan a release” is a different request.** It produces a creative brief and rollout plan. Ask for a release pack to produce media, or ask for both so the agent can carry the same brief into production. When ChatGPT supplies a selected attachment to the upload tool, the tool accepts its host file reference directly. It imports the selected download URL into private Recoup storage and validates the actual media bytes. Other hosts can use the supported source URL, inline or signed-upload modes; a filename alone is not an accessible recording. For direct API uploads, small inline files are limited to approximately 3 MB (4,000,000 base64 characters). For normal song files, request a private signed upload, transfer the file and finalize it, or import an accessible HTTPS source up to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable only after the agent can access its actual bytes. Audio formats include MP3, WAV, FLAC and M4A. Source images can be PNG, JPEG or WebP. ## What the brief contains | Input | How it is used | | --- | --- | | Artist, song and exact version | Keep the recording, remix and artist identity consistent | | Real audio and selected hook | Put the correct music into the finished clips | | Occasion | Choose relevant concepts and copy rather than defaulting to “out now” | | Creative direction or references | Keep a coherent visual family and voice | | Primary action and destination | Write relevant captions without inventing links | | Audience, platforms and constraints | Choose useful formats and respect supplied boundaries | For anniversaries, the original release date and campaign date are separate. If the original date is unknown, the agent must obtain it before making dated anniversary claims. A catalog request needs a bounded selection of recordings; it must not silently generate a pack for every track. Research enriches the brief. Missing research or audience metrics should not force unrelated onboarding or fabricated statistics. Existing artwork and supplied preferences can be enough to propose strong creative work. An artist's face is optional; artwork-led and typographic work are valid directions. ## Scope and budget before generation ### Save a direction and choose how involved to be Connections exposing `brief.creative_context` can save an established visual world, a rough idea or an exploratory direction in the same pack. The field is optional; older connections keep their existing brief behavior. It holds attributed references, up to three direction candidates and the selected candidate. **Run with it** uses `working_mode: \"autonomous\"`: the agent records its direction selection and continues within the approved budget. **Show me directions first** uses `working_mode: \"guided\"`: final quoting and generation wait for a selection recorded from the customer's feedback. An agent's own choice does not count as customer selection in guided mode. Save candidates under `directions`, then record `selection.direction_id`, `selection.selected_by` (`customer` or `agent`) and a short `decision_note`. Direction and reference IDs must be unique within this brief; selections cannot point to another pack's candidate. Updating these fields follows the same saved job and expected-revision rules and invalidates its earlier quote. A reference manifest item declares its source, media type and `usage`: `reference_only` is inspiration, while `production` explicitly makes an image eligible as a selected generation input. Only production images referenced by the chosen direction enter the renderer. Together with explicit legacy `reference_image_urls`, at most five distinct production images are supported. The original source manifest stays unchanged when production inputs are resolved. This first slice accepts supplied direction boards through an optional `board_url`. It does not add automatic mood-board generation, public-profile harvesting or new asset types. Discover those capabilities before promising them. An optional customer checkpoint does not authorize additional spending or publication. Preparation and generation are separate operations. Before paid production, the agent shows the proposed direction, deliverables, cost scope and maximum budget. The quote binds the current brief and deliverables. Changing the song or scope requires a new quote; an earlier approval cannot silently authorize different work. The default scope is 15 creative pieces: eight video clips, four quote cards, one artwork, one carousel and one visualizer, with captions. A carousel is one piece; its slides and alternate aspect ratios are identified as components or variants. You can request a smaller scope. The quote must describe the actual selected work, including chargeable stages and any retry allowance. Current quotes charge for image and motion generation; captioning, audio analysis, composition and inspection are included without an added customer fee. The approved amount is held before production; unused stages are refunded. A new paid retry needs its own quote. The older `GET /api/content/estimate` is an advisory per-video estimate. It is not a complete Release Packs quote. On insufficient credits the agent surfaces the returned `billingUrl`; it must not buy credits, switch accounts or retry paid generation automatically. ## One job, with visible progress The pack retains its brief, revision, quote, individual asset states and completed work. Signing in, waiting for a render, or recovering from a failed stage should not make you repeat the request or regenerate the whole pack. The first representative asset is produced and inspected early. The agent then continues the agreed batch within your budget, unless you requested a preview checkpoint. Progress distinguishes requested, generated, inspected and delivered assets. A partly generated pack is reported as partial. ## Review and delivery A finished music-bearing asset must contain the selected recording and the correct audio window. Inspection covers sound, timing, duration, framing, readable text, visual consistency and the campaign brief. A render request, a prompt or a concept is not a finished asset. Static image inspection and video inspection are separate. Delivery includes previews, usable files, captions, a manifest and any unresolved gaps. The agent retains successful work when a stage fails and retries only within the approved scope and budget. Release Packs stops at the assets: posting and scheduling need a separate request. After delivery, you can save confirmed artist preferences for next time. A one-off creative proposal must not overwrite established branding or become a permanent public knowledge-base entry automatically. ## API and connected tools Connected operations are `prepare_release_pack`, `get_release_pack`, `estimate_release_pack`, `generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and `export_release_pack`. Discover their actual schemas in the connected host; older connections may need a refresh. The shared API contract separates preparation, reading, quoting, generation, retry and selected-asset upload. Connected tools use the same account and job rules. Credentials remain with the host; an agent must not extract OAuth tokens into REST requests or ask for an API key to compensate for a missing MCP tool. If a required operation is unavailable, the agent should name that operation, retain the brief and explain the next step. It must not claim the entire account is disconnected or present a plan as completed media. "},{"slug":"api-reference/templates/list","title":"List Templates","description":"List templates","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/agents/templates","spec":"templates.json"},"searchText":"List Templates List templates Agents & Sandboxes Templates GET /api/agents/templates "},{"slug":"api-reference/templates/create","title":"Create Template","description":"Create a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/templates","spec":"templates.json"},"searchText":"Create Template Create a template Agents & Sandboxes Templates POST /api/agents/templates "},{"slug":"api-reference/templates/update","title":"Update Template","description":"Update a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/agents/templates/{id}","spec":"templates.json"},"searchText":"Update Template Update a template Agents & Sandboxes Templates PATCH /api/agents/templates/{id} "},{"slug":"api-reference/templates/delete","title":"Delete Template","description":"Delete a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/agents/templates/{id}","spec":"templates.json"},"searchText":"Delete Template Delete a template Agents & Sandboxes Templates DELETE /api/agents/templates/{id} "},{"slug":"api-reference/templates/favorite","title":"Favorite Template","description":"Toggle favorite on a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/favorite.mdx","body":"","headings":[],"api":{"method":"PUT","path":"/api/agents/templates/{id}/favorite","spec":"templates.json"},"searchText":"Favorite Template Toggle favorite on a template Agents & Sandboxes Templates PUT /api/agents/templates/{id}/favorite "},{"slug":"api-reference/tasks/get","title":"Get Tasks","description":"Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/tasks","spec":"releases.json"},"searchText":"Get Tasks Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id. Agents & Sandboxes Tasks GET /api/tasks "},{"slug":"api-reference/tasks/create","title":"Create Task","description":"Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array).","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/tasks","spec":"releases.json"},"searchText":"Create Task Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array). Agents & Sandboxes Tasks POST /api/tasks "},{"slug":"api-reference/tasks/update","title":"Update Task","description":"Update scheduled task","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/tasks","spec":"releases.json"},"searchText":"Update Task Update scheduled task Agents & Sandboxes Tasks PATCH /api/tasks "},{"slug":"api-reference/tasks/delete","title":"Delete Task","description":"Delete scheduled task","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/tasks","spec":"releases.json"},"searchText":"Delete Task Delete scheduled task Agents & Sandboxes Tasks DELETE /api/tasks "},{"slug":"api-reference/tasks/runs","title":"Get Task Runs","description":"Get task runs","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/runs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/tasks/runs","spec":"releases.json"},"searchText":"Get Task Runs Get task runs Agents & Sandboxes Tasks GET /api/tasks/runs "},{"slug":"api-reference/content-agent/webhook","title":"Slack Webhook","description":"Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread.","category":"Agents & Sandboxes","group":"Content Agent","source":"api-reference/content-agent/webhook.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content-agent/{platform}","spec":"content.json"},"searchText":"Slack Webhook Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread. Agents & Sandboxes Content Agent POST /api/content-agent/{platform} "},{"slug":"api-reference/content-agent/callback","title":"Task Callback","description":"Internal worker callback for a configured content agent. Requires the shared callback secret in x-callback-secret. Public content creation uses POST /api/content/create.","category":"Agents & Sandboxes","group":"Content Agent","source":"api-reference/content-agent/callback.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content-agent/callback","spec":"content.json"},"searchText":"Task Callback Internal worker callback for a configured content agent. Requires the shared callback secret in x-callback-secret. Public content creation uses POST /api/content/create. Agents & Sandboxes Content Agent POST /api/content-agent/callback "},{"slug":"api-reference/sandboxes/list","title":"List Sandboxes","description":"List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandboxes","spec":"content.json"},"searchText":"List Sandboxes List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes GET /api/sandboxes "},{"slug":"api-reference/sandboxes/create","title":"Create Sandbox","description":"Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes","spec":"content.json"},"searchText":"Create Sandbox Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes "},{"slug":"api-reference/sandboxes/snapshot","title":"Update Snapshot","description":"Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/snapshot.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sandboxes","spec":"content.json"},"searchText":"Update Snapshot Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files. Agents & Sandboxes Sandboxes PATCH /api/sandboxes "},{"slug":"api-reference/sandboxes/delete","title":"Delete Sandbox","description":"Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/sandboxes","spec":"content.json"},"searchText":"Delete Sandbox Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes DELETE /api/sandboxes "},{"slug":"api-reference/sandboxes/setup","title":"Setup Sandbox","description":"Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/setup.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/setup","spec":"content.json"},"searchText":"Setup Sandbox Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes/setup "},{"slug":"api-reference/sandboxes/get-file","title":"Get File Contents","description":"Read a file from the authenticated account's Git-backed repository, or an explicitly authorized target account's repository, including resolved submodule paths, on `main`. The repository comes from the [account's snapshot](/api-reference/sandboxes/list). Authenticate with `x-api-key` or an Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/get-file.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandboxes/file","spec":"content.json"},"searchText":"Get File Contents Read a file from the authenticated account's Git-backed repository, or an explicitly authorized target account's repository, including resolved submodule paths, on `main`. The repository comes from the [account's snapshot](/api-reference/sandboxes/list). Authenticate with `x-api-key` or an Authorization Bearer token. Agents & Sandboxes Sandboxes GET /api/sandboxes/file "},{"slug":"api-reference/sandboxes/stage-file","title":"Stage File","description":"Issue a presigned upload token so the browser can upload a file directly to Vercel Blob, then call `POST /api/sandboxes/files` with the resulting blob URL to commit it to the sandbox repo. Use `upload()` from `@vercel/blob/client` rather than calling this route by hand. Max file size 100MB.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/stage-file.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/staged-file","spec":"content.json"},"searchText":"Stage File Issue a presigned upload token so the browser can upload a file directly to Vercel Blob, then call `POST /api/sandboxes/files` with the resulting blob URL to commit it to the sandbox repo. Use `upload()` from `@vercel/blob/client` rather than calling this route by hand. Max file size 100MB. Agents & Sandboxes Sandboxes POST /api/sandboxes/staged-file "},{"slug":"api-reference/sandboxes/upload-files","title":"Upload Files","description":"Upload one or more files to the authenticated account's Git-backed repository. Each file URL is committed separately; paths inside a submodule resolve to that repository. Authenticate with `x-api-key` or an Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/upload-files.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/files","spec":"content.json"},"searchText":"Upload Files Upload one or more files to the authenticated account's Git-backed repository. Each file URL is committed separately; paths inside a submodule resolve to that repository. Authenticate with `x-api-key` or an Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes/files "},{"slug":"api-reference/sessions/create","title":"Create Session","description":"Create session","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions","spec":"sessions.json"},"searchText":"Create Session Create session Agents & Sandboxes Sessions POST /api/sessions "},{"slug":"api-reference/sessions/get","title":"Get Session","description":"Get session by id","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}","spec":"sessions.json"},"searchText":"Get Session Get session by id Agents & Sandboxes Sessions GET /api/sessions/{sessionId} "},{"slug":"api-reference/sessions/patch","title":"Update Session","description":"Rename a session, change lifecycle status, or update line counters.","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/patch.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sessions/{sessionId}","spec":"sessions.json"},"searchText":"Update Session Rename a session, change lifecycle status, or update line counters. Agents & Sandboxes Sessions PATCH /api/sessions/{sessionId} "},{"slug":"api-reference/sessions/list-chats","title":"List Session Chats","description":"List session chats","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/list-chats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}/chats","spec":"sessions.json"},"searchText":"List Session Chats List session chats Agents & Sandboxes Sessions GET /api/sessions/{sessionId}/chats "},{"slug":"api-reference/sessions/create-chat","title":"Create Session Chat","description":"Create session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/create-chat.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions/{sessionId}/chats","spec":"sessions.json"},"searchText":"Create Session Chat Create session chat Agents & Sandboxes Sessions POST /api/sessions/{sessionId}/chats "},{"slug":"api-reference/sessions/get-chat","title":"Get Session Chat","description":"Get session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/get-chat.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Get Session Chat Get session chat Agents & Sandboxes Sessions GET /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/patch-chat","title":"Update Session Chat","description":"Update session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/patch-chat.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Update Session Chat Update session chat Agents & Sandboxes Sessions PATCH /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/delete-chat","title":"Delete Session Chat","description":"Delete session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/delete-chat.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Delete Session Chat Delete session chat Agents & Sandboxes Sessions DELETE /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/mark-chat-read","title":"Mark Chat Read","description":"Marks a session chat as read for the authenticated account.","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/mark-chat-read.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions/{sessionId}/chats/{chatId}/read","spec":"sessions.json"},"searchText":"Mark Chat Read Marks a session chat as read for the authenticated account. Agents & Sandboxes Sessions POST /api/sessions/{sessionId}/chats/{chatId}/read "},{"slug":"api-reference/sandbox/create","title":"Create or restore session sandbox","description":"Create or restore session sandbox","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandbox","spec":"sandbox.json"},"searchText":"Create or restore session sandbox Create or restore session sandbox Agents & Sandboxes Session Sandboxes POST /api/sandbox "},{"slug":"api-reference/sandbox/status","title":"Get session sandbox status","description":"Get session sandbox status","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/status.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandbox/status","spec":"sandbox.json"},"searchText":"Get session sandbox status Get session sandbox status Agents & Sandboxes Session Sandboxes GET /api/sandbox/status "},{"slug":"api-reference/sandbox/reconnect","title":"Reconnect to session sandbox","description":"Reconnect to session sandbox","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/reconnect.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandbox/reconnect","spec":"sandbox.json"},"searchText":"Reconnect to session sandbox Reconnect to session sandbox Agents & Sandboxes Session Sandboxes GET /api/sandbox/reconnect "},{"slug":"api-reference/accounts/id","title":"Get Account ID","description":"Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/id.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/id","spec":"accounts.json"},"searchText":"Get Account ID Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId. Accounts Accounts GET /api/accounts/id "},{"slug":"api-reference/accounts/get","title":"Get Account","description":"Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}","spec":"accounts.json"},"searchText":"Get Account Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses. Accounts Accounts GET /api/accounts/{id} "},{"slug":"api-reference/accounts/create","title":"Create Account","description":"Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts","spec":"accounts.json"},"searchText":"Create Account Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits. Accounts Accounts POST /api/accounts "},{"slug":"api-reference/accounts/update","title":"Update Account","description":"Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/accounts","spec":"accounts.json"},"searchText":"Update Account Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override. Accounts Accounts PATCH /api/accounts "},{"slug":"api-reference/accounts/add-artist","title":"Add Artist to Account","description":"Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/add-artist.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/artists","spec":"accounts.json"},"searchText":"Add Artist to Account Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification. Accounts Accounts POST /api/accounts/artists "},{"slug":"api-reference/subscriptions/sessions-create","title":"Create Subscription Session","description":"Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial.","category":"Accounts","group":"Billing","source":"api-reference/subscriptions/sessions-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/subscriptions/sessions","spec":"accounts.json"},"searchText":"Create Subscription Session Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial. Accounts Billing POST /api/subscriptions/sessions "},{"slug":"api-reference/subscriptions/claim-create","title":"Claim Subscription","description":"Attach a subscription bought through [Create Subscription Session](/api-reference/subscriptions/sessions-create) (anonymous path) to the authenticated account. Needed only when the signed-in email differs from the email typed into Stripe Checkout; when they match, the webhook already linked the subscription and this call is a no-op that returns 200.","category":"Accounts","group":"Billing","source":"api-reference/subscriptions/claim-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/subscriptions/claim","spec":"accounts.json"},"searchText":"Claim Subscription Attach a subscription bought through [Create Subscription Session](/api-reference/subscriptions/sessions-create) (anonymous path) to the authenticated account. Needed only when the signed-in email differs from the email typed into Stripe Checkout; when they match, the webhook already linked the subscription and this call is a no-op that returns 200. Accounts Billing POST /api/subscriptions/claim "},{"slug":"api-reference/accounts/subscription-get","title":"Get Account Subscription","description":"Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/subscription-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/subscription","spec":"accounts.json"},"searchText":"Get Account Subscription Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/subscription "},{"slug":"api-reference/accounts/portal-create","title":"Create Billing Portal Session","description":"Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. The portal opens on the Stripe customer that owns the account's active subscription, so accounts without an active subscription get a 400 even when a tagged customer with a card exists. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with an active subscription.","category":"Accounts","group":"Billing","source":"api-reference/accounts/portal-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/{id}/portal","spec":"accounts.json"},"searchText":"Create Billing Portal Session Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. The portal opens on the Stripe customer that owns the account's active subscription, so accounts without an active subscription get a 400 even when a tagged customer with a card exists. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with an active subscription. Accounts Billing POST /api/accounts/{id}/portal "},{"slug":"api-reference/accounts/payment-method-get","title":"Get Default Payment Method","description":"Retrieve the default payment method on file for an account. An account may be tagged on more than one Stripe customer (for example an organization whose card was saved on one customer and whose invoiced plan lives on another); the card is read from the tagged customer that holds a default payment method. Returns `card: null` when the selected customer has no supported default card, including when no tagged customer exists — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline. Removing the selected card does not remove other saved cards: a later read can select a different remaining card. Auto top-up stays off after successful removal until explicitly re-enabled.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Get Default Payment Method Retrieve the default payment method on file for an account. An account may be tagged on more than one Stripe customer (for example an organization whose card was saved on one customer and whose invoiced plan lives on another); the card is read from the tagged customer that holds a default payment method. Returns `card: null` when the selected customer has no supported default card, including when no tagged customer exists — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline. Removing the selected card does not remove other saved cards: a later read can select a different remaining card. Auto top-up stays off after successful removal until explicitly re-enabled. Accounts Billing GET /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payment-method-create","title":"Save a Payment Method","description":"Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The card is saved on the account's Stripe customer that already holds a default card, or the newest tagged customer; a customer is created (and tagged with the account id) if none exists yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Save a Payment Method Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The card is saved on the account's Stripe customer that already holds a default card, or the newest tagged customer; a customer is created (and tagged with the account id) if none exists yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing POST /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payment-method-delete","title":"Remove the Payment Method","description":"Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Remove the Payment Method Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing DELETE /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payments-get","title":"List Account Payments","description":"List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payments-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/payments","spec":"accounts.json"},"searchText":"List Account Payments List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/payments "},{"slug":"api-reference/accounts/auto-top-up-get","title":"Get Auto Top-up Settings","description":"Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/auto-top-up-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/auto-top-up","spec":"accounts.json"},"searchText":"Get Auto Top-up Settings Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/auto-top-up "},{"slug":"api-reference/accounts/auto-top-up-update","title":"Update Auto Top-up Settings","description":"Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/auto-top-up-update.mdx","body":"","headings":[],"api":{"method":"PUT","path":"/api/accounts/{id}/auto-top-up","spec":"accounts.json"},"searchText":"Update Auto Top-up Settings Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing PUT /api/accounts/{id}/auto-top-up "},{"slug":"api-reference/credits/sessions-create","title":"Create Credits Top-Up Session","description":"Top up credits on the authenticated account.","category":"Accounts","group":"Billing","source":"api-reference/credits/sessions-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/credits/sessions","spec":"accounts.json"},"searchText":"Create Credits Top-Up Session Top up credits on the authenticated account. Accounts Billing POST /api/credits/sessions "},{"slug":"api-reference/accounts/credits-get","title":"Get Account Credits","description":"Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update.","category":"Accounts","group":"Billing","source":"api-reference/accounts/credits-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/credits","spec":"accounts.json"},"searchText":"Get Account Credits Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update. Accounts Billing GET /api/accounts/{id}/credits "},{"slug":"api-reference/accounts/usage-get","title":"Get Account Usage","description":"List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership.","category":"Accounts","group":"Billing","source":"api-reference/accounts/usage-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/usage","spec":"accounts.json"},"searchText":"Get Account Usage List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership. Accounts Billing GET /api/accounts/{id}/usage "},{"slug":"api-reference/pulses/update","title":"Update Pulse","description":"Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint.","category":"Accounts","group":"Pulses","source":"api-reference/pulses/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/pulses","spec":"accounts.json"},"searchText":"Update Pulse Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint. Accounts Pulses PATCH /api/pulses "},{"slug":"api-reference/pulses/list","title":"List Pulses","description":"Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations.","category":"Accounts","group":"Pulses","source":"api-reference/pulses/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/pulses","spec":"accounts.json"},"searchText":"List Pulses Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations. Accounts Pulses GET /api/pulses "},{"slug":"api-reference/organizations/list","title":"Get Organizations","description":"Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations","spec":"accounts.json"},"searchText":"Get Organizations Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to. Accounts Organizations GET /api/organizations "},{"slug":"api-reference/organizations/create","title":"Create Organization","description":"Create a new organization. The creator is automatically added as a member of the organization.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations","spec":"accounts.json"},"searchText":"Create Organization Create a new organization. The creator is automatically added as a member of the organization. Accounts Organizations POST /api/organizations "},{"slug":"api-reference/organizations/add-artist","title":"Add Artist to Organization","description":"Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-artist.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/artists","spec":"accounts.json"},"searchText":"Add Artist to Organization Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records. Accounts Organizations POST /api/organizations/artists "},{"slug":"api-reference/organizations/add-member","title":"Add Member to Organization","description":"Add a member to an organization. This endpoint is idempotent - Adding an existing member returns the existing membership.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-member.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/members","spec":"accounts.json"},"searchText":"Add Member to Organization Add a member to an organization. This endpoint is idempotent - Adding an existing member returns the existing membership. Accounts Organizations POST /api/organizations/members "},{"slug":"api-reference/organizations/remove-member","title":"Remove Member from Organization","description":"Remove a member from an organization. This endpoint is idempotent - Removing an account that is not a member succeeds without error.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/remove-member.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/organizations/members","spec":"accounts.json"},"searchText":"Remove Member from Organization Remove a member from an organization. This endpoint is idempotent - Removing an account that is not a member succeeds without error. Accounts Organizations DELETE /api/organizations/members "},{"slug":"api-reference/organizations/list-domains","title":"List Organization Domains","description":"List the email domains mapped to an organization. Accounts that sign up with an email at a mapped domain automatically join the organization.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/list-domains.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"List Organization Domains List the email domains mapped to an organization. Accounts that sign up with an email at a mapped domain automatically join the organization. Accounts Organizations GET /api/organizations/domains "},{"slug":"api-reference/organizations/add-domain","title":"Add Organization Domain","description":"Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-domain.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"Add Organization Domain Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping. Accounts Organizations POST /api/organizations/domains "},{"slug":"api-reference/organizations/remove-domain","title":"Remove Organization Domain","description":"Remove an email domain mapping from an organization. New signups at this domain will no longer auto-join the organization; existing members are not affected. This endpoint is idempotent.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/remove-domain.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"Remove Organization Domain Remove an email domain mapping from an organization. New signups at this domain will no longer auto-join the organization; existing members are not affected. This endpoint is idempotent. Accounts Organizations DELETE /api/organizations/domains "},{"slug":"api-reference/organizations/professionals","title":"List Professional Roster","description":"List professional roster","category":"Accounts","group":"Organizations","source":"api-reference/organizations/professionals.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations/professionals","spec":"accounts.json"},"searchText":"List Professional Roster List professional roster Accounts Organizations GET /api/organizations/professionals "},{"slug":"api-reference/organizations/professionals-confirm","title":"Confirm Professional Roster Addition","description":"Confirm professional roster addition","category":"Accounts","group":"Organizations","source":"api-reference/organizations/professionals-confirm.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/professionals","spec":"accounts.json"},"searchText":"Confirm Professional Roster Addition Confirm professional roster addition Accounts Organizations POST /api/organizations/professionals "},{"slug":"api-reference/admins/check","title":"Check Admin Status","description":"Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header.","category":"Accounts","group":"Admins","source":"api-reference/admins/check.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins","spec":"accounts.json"},"searchText":"Check Admin Status Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header. Accounts Admins GET /api/admins "},{"slug":"api-reference/admins/sandboxes","title":"List Account Sandboxes (Admin)","description":"Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/sandboxes.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/sandboxes","spec":"accounts.json"},"searchText":"List Account Sandboxes (Admin) Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/sandboxes "},{"slug":"api-reference/admins/sandboxes-orgs","title":"List Org Repo Stats (Admin)","description":"Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/sandboxes-orgs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/sandboxes/orgs","spec":"accounts.json"},"searchText":"List Org Repo Stats (Admin) Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/sandboxes/orgs "},{"slug":"api-reference/admins/emails","title":"List Account Emails (Admin)","description":"Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email).","category":"Accounts","group":"Admins","source":"api-reference/admins/emails.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/emails","spec":"accounts.json"},"searchText":"List Account Emails (Admin) Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email). Accounts Admins GET /api/admins/emails "},{"slug":"api-reference/admins/privy","title":"List Privy Logins (Admin)","description":"Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/privy.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/privy","spec":"accounts.json"},"searchText":"List Privy Logins (Admin) Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/privy "},{"slug":"api-reference/admins/coding-agent-slack-tags","title":"List Coding Agent Slack Tags (Admin)","description":"Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Optional tag filters by the exact, case-sensitive Slack author ID after trimming whitespace. Filtering happens after the existing period collection and before all totals are calculated; omission preserves the unfiltered report, and an unknown ID returns empty tags with zero totals. Empty or whitespace-only tag values return 400 after admin authentication. This is display filtering, not authorization or a reduction in Slack collection work. Collection retains its existing channel access, retention, history/thread pagination and partial-failure limits. No automatic caller, UI, polling, scheduled action or Slack send is added.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-agent-slack-tags.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding/slack","spec":"accounts.json"},"searchText":"List Coding Agent Slack Tags (Admin) Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Optional tag filters by the exact, case-sensitive Slack author ID after trimming whitespace. Filtering happens after the existing period collection and before all totals are calculated; omission preserves the unfiltered report, and an unknown ID returns empty tags with zero totals. Empty or whitespace-only tag values return 400 after admin authentication. This is display filtering, not authorization or a reduction in Slack collection work. Collection retains its existing channel access, retention, history/thread pagination and partial-failure limits. No automatic caller, UI, polling, scheduled action or Slack send is added. Accounts Admins GET /api/admins/coding/slack "},{"slug":"api-reference/admins/coding-agent-slack-authors","title":"List Coding Agent Slack Authors (Admin)","description":"Returns distinct authors of collected Coding Agent mentions for an admin author selector. Requires the authenticated account to be a Recoup admin, using exactly one of x-api-key or Authorization Bearer. No query parameters are defined. Each authorized request runs the existing all-period Slack collector once, then deduplicates by Slack author ID, retains the first collected profile and sorts by display name using localeCompare; identical names do not merge different IDs. The result is authors in that collected data, not a complete all-time Slack directory. Existing channel access, retention, paginated history, first-page thread replies and partial-failure limits remain; partial collection can still produce an incomplete successful result. Thrown collection failures return 500. This call is not free cached metadata: a future caller must account for scan latency and quotas. The release adds no automatic caller, UI, polling, scheduled action, new Slack scope or Slack send. Production admin access, history coverage, latency and quotas were not verified by the source contract tests.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-agent-slack-authors.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding-agent/slack-tags","spec":"accounts.json"},"searchText":"List Coding Agent Slack Authors (Admin) Returns distinct authors of collected Coding Agent mentions for an admin author selector. Requires the authenticated account to be a Recoup admin, using exactly one of x-api-key or Authorization Bearer. No query parameters are defined. Each authorized request runs the existing all-period Slack collector once, then deduplicates by Slack author ID, retains the first collected profile and sorts by display name using localeCompare; identical names do not merge different IDs. The result is authors in that collected data, not a complete all-time Slack directory. Existing channel access, retention, paginated history, first-page thread replies and partial-failure limits remain; partial collection can still produce an incomplete successful result. Thrown collection failures return 500. This call is not free cached metadata: a future caller must account for scan latency and quotas. The release adds no automatic caller, UI, polling, scheduled action, new Slack scope or Slack send. Production admin access, history coverage, latency and quotas were not verified by the source contract tests. Accounts Admins GET /api/admins/coding-agent/slack-tags "},{"slug":"api-reference/admins/coding-pr","title":"Get Coding Agent PR Merged Status (Admin)","description":"Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-pr.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding/pr","spec":"accounts.json"},"searchText":"Get Coding Agent PR Merged Status (Admin) Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/coding/pr "},{"slug":"api-reference/admins/content-slack-tags","title":"List Content Agent Slack Tags (Admin)","description":"Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/content-slack-tags.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/content/slack","spec":"accounts.json"},"searchText":"List Content Agent Slack Tags (Admin) Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/content/slack "},{"slug":"api-reference/admins/agent-signups","title":"Admin signup report availability","description":"An admin key-metadata report is available; the former signup-report URL and broader reporting outcome remain separate.","category":"Accounts","group":"Admins","source":"api-reference/admins/agent-signups.mdx","body":"`GET /api/admins/agent/signups` is not available. The new\n[admin key-metadata report](/api-reference/admins/agent-key-metadata) uses\n`GET /api/admins/agent-signups` (a different URL).\n\nA Recoup admin can use the new report to inspect key-record IDs, names, creation\ntimes and matching current `agent+…` email addresses. It never returns API-key\ncredentials or hashes. Its `total` counts the returned key records; several keys\ncan belong to one account. It does not establish where an account signed up,\nhow many unique agents signed up, which keys are active, or whether people use\nthe product. Current email associations, database visibility and server row limits\nalso prevent a guarantee of complete historical reporting.\n\n## Unfinished reporting outcome\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the\nbroader reporting decision. The bounded metadata route from\n[API #1095](https://github.com/recoupable/api/pull/1095) does not complete the original\n[API #428](https://github.com/recoupable/api/issues/428) customer outcome or restore\nthe former URL. Follow the new route's period, admin-access and collection-limit\nnotes when using it; do not treat key-record counts as signup-origin or adoption\nmeasurements.\n","headings":[{"title":"Unfinished reporting outcome","id":"unfinished-reporting-outcome"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/admins/agent/signups\"\n }), \" is not available. The new\\n\", _jsx(_components.a, {\n href: \"/api-reference/admins/agent-key-metadata\",\n children: \"admin key-metadata report\"\n }), \" uses\\n\", _jsx(_components.code, {\n children: \"GET /api/admins/agent-signups\"\n }), \" (a different URL).\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A Recoup admin can use the new report to inspect key-record IDs, names, creation\\ntimes and matching current \", _jsx(_components.code, {\n children: \"agent+…\"\n }), \" email addresses. It never returns API-key\\ncredentials or hashes. Its \", _jsx(_components.code, {\n children: \"total\"\n }), \" counts the returned key records; several keys\\ncan belong to one account. It does not establish where an account signed up,\\nhow many unique agents signed up, which keys are active, or whether people use\\nthe product. Current email associations, database visibility and server row limits\\nalso prevent a guarantee of complete historical reporting.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"unfinished-reporting-outcome\",\n children: \"Unfinished reporting outcome\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" retains the\\nbroader reporting decision. The bounded metadata route from\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/1095\",\n children: \"API #1095\"\n }), \" does not complete the original\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/issues/428\",\n children: \"API #428\"\n }), \" customer outcome or restore\\nthe former URL. Follow the new route's period, admin-access and collection-limit\\nnotes when using it; do not treat key-record counts as signup-origin or adoption\\nmeasurements.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Admin signup report availability An admin key-metadata report is available; the former signup-report URL and broader reporting outcome remain separate. Accounts Admins `GET /api/admins/agent/signups` is not available. The new [admin key-metadata report](/api-reference/admins/agent-key-metadata) uses `GET /api/admins/agent-signups` (a different URL). A Recoup admin can use the new report to inspect key-record IDs, names, creation times and matching current `agent+…` email addresses. It never returns API-key credentials or hashes. Its `total` counts the returned key records; several keys can belong to one account. It does not establish where an account signed up, how many unique agents signed up, which keys are active, or whether people use the product. Current email associations, database visibility and server row limits also prevent a guarantee of complete historical reporting. ## Unfinished reporting outcome [Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the broader reporting decision. The bounded metadata route from [API #1095](https://github.com/recoupable/api/pull/1095) does not complete the original [API #428](https://github.com/recoupable/api/issues/428) customer outcome or restore the former URL. Follow the new route's period, admin-access and collection-limit notes when using it; do not treat key-record counts as signup-origin or adoption measurements. "},{"slug":"api-reference/admins/agent-key-metadata","title":"List Agent Key Metadata (Admin)","description":"List agent-prefixed API-key metadata (Admin)","category":"Accounts","group":"Admins","source":"api-reference/admins/agent-key-metadata.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/agent-signups","spec":"accounts.json"},"searchText":"List Agent Key Metadata (Admin) List agent-prefixed API-key metadata (Admin) Accounts Admins GET /api/admins/agent-signups "},{"slug":"api-reference/admins/artists-pro","title":"List Pro Artists (Admin)","description":"Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is \"pro\" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts.","category":"Accounts","group":"Admins","source":"api-reference/admins/artists-pro.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/artists/pro","spec":"accounts.json"},"searchText":"List Pro Artists (Admin) Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is \"pro\" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts. Accounts Admins GET /api/admins/artists/pro "},{"slug":"api-reference/admins/credits-rollup","title":"Credit Usage Rollup (Admin)","description":"Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-rollup.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/credits/rollup","spec":"accounts.json"},"searchText":"Credit Usage Rollup (Admin) Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin. Accounts Admins GET /api/admins/credits/rollup "},{"slug":"api-reference/admins/credits-events","title":"Credit Usage Events (Admin)","description":"Returns the raw `usage_events` rows for a single account over the selected period, sorted by `created_at` descending. Powers the drilldown view that expands when a row in the [`/api/admins/credits/rollup`](/api-reference/admins/credits-rollup) table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and `credits_deducted` matching the wallet drop on `credits_usage` for that account.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-events.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/credits/events","spec":"accounts.json"},"searchText":"Credit Usage Events (Admin) Returns the raw `usage_events` rows for a single account over the selected period, sorted by `created_at` descending. Powers the drilldown view that expands when a row in the [`/api/admins/credits/rollup`](/api-reference/admins/credits-rollup) table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and `credits_deducted` matching the wallet drop on `credits_usage` for that account. Accounts Admins GET /api/admins/credits/events "},{"slug":"api-reference/admins/credits-grant","title":"Grant Credits (Admin)","description":"Sets an account's credit balance, and records who set it and why. Requires the authenticated account to be a Recoup admin.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-grant.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/admins/credits","spec":"accounts.json"},"searchText":"Grant Credits (Admin) Sets an account's credit balance, and records who set it and why. Requires the authenticated account to be a Recoup admin. Accounts Admins POST /api/admins/credits "},{"slug":"api-reference/emails/create","title":"Send Email","description":"Send an email to one or more recipients. Emails are sent from `Agent by Recoup `.","category":"Accounts","group":"Emails","source":"api-reference/emails/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/emails","spec":"accounts.json"},"searchText":"Send Email Send an email to one or more recipients. Emails are sent from `Agent by Recoup `. Accounts Emails POST /api/emails "},{"slug":"api-reference/projects/get","title":"Get Project","description":"Get project","category":"Accounts","group":"Projects","source":"api-reference/projects/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}","spec":"projects.json"},"searchText":"Get Project Get project Accounts Projects GET /api/projects/{projectId} "},{"slug":"api-reference/projects/task-get","title":"Get Project Task","description":"Get project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Get Project Task Get project task Accounts Projects GET /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/task-create","title":"Create Project Task","description":"Create project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/projects/{projectId}/tasks","spec":"projects.json"},"searchText":"Create Project Task Create project task Accounts Projects POST /api/projects/{projectId}/tasks "},{"slug":"api-reference/projects/task-update","title":"Update Project Task","description":"Update project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Update Project Task Update project task Accounts Projects PATCH /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/task-delete","title":"Delete Project Task","description":"Delete project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Delete Project Task Delete project task Accounts Projects DELETE /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/comments-get","title":"List Task Comments","description":"List task comments","category":"Accounts","group":"Projects","source":"api-reference/projects/comments-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}/tasks/{taskId}/comments","spec":"projects.json"},"searchText":"List Task Comments List task comments Accounts Projects GET /api/projects/{projectId}/tasks/{taskId}/comments "},{"slug":"api-reference/projects/comments-create","title":"Add Task Comment","description":"Add task comment","category":"Accounts","group":"Projects","source":"api-reference/projects/comments-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/projects/{projectId}/tasks/{taskId}/comments","spec":"projects.json"},"searchText":"Add Task Comment Add task comment Accounts Projects POST /api/projects/{projectId}/tasks/{taskId}/comments "},{"slug":"connectors/ownership","title":"Connection Ownership","description":"The connector connection-ownership and authority contract: who owns a connection, who can act through it, and why roster membership never grants execute rights.","category":"Connectors","group":"Concepts","source":"connectors/ownership.mdx","body":"## Overview\n\nConnectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the **ownership and authority contract** for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it.\n\nThis contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the [Connectors API reference](/api-reference/connectors/list).\n\n---\n\n## Association ≠ Authority\n\nArtists in Recoup are **canonical and shared**. The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections:\n\n- An artist appearing in an account's roster (`account_artist_ids`) grants **read and analytics access only**.\n- An artist appearing in an organization's roster likewise grants **read and analytics access only** to org members.\n- Neither form of association ever grants the right to authorize, execute, or disconnect a connection.\n\n\nRoster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does **not** let Account B post through that connection.\n\n\n---\n\n## Connection Scope\n\nConnections are scoped to the **relationship between an owner and an artist**, not to the bare canonical artist:\n\n| Connection type | Scoped to |\n|-----------------|-----------|\n| Personal | The `(account, artist)` pair |\n| Org-shared | The `(organization, artist)` pair |\n\nThe connection is keyed on the **join row** (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist.\n\n**Whoever establishes a connection owns it.** Ownership is set at authorization time and does not transfer through roster changes.\n\nBecause artists stay canonical and shared, **isolation lives on the connection**: sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it.\n\n---\n\n## Authority Matrix\n\n| Capability | Who has it |\n|------------|-----------|\n| Read / analytics on an artist | Any account or org member with the artist in their roster |\n| Authorize a new connection | The account (or org member, for org-shared) establishing the connection, who then owns it |\n| Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org |\n| Disconnect a connection | The owning account only; for org-shared connections, members of the owning org |\n| Admin override | Recoup staff only (admins of the Recoup internal organization) |\n\n\nThe admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection.\n\n\n---\n\n## Relationship to the Current API Reference\n\nThe [Connectors endpoint reference](/api-reference/connectors/list) currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-`(account, artist)` / per-`(organization, artist)` model defined here. Where the two disagree, **this page is the authority contract**. Endpoint docs will be updated as the re-keyed API ships.\n\nEndpoint request and response shapes for the re-keyed model are deliberately not documented here yet.\n","headings":[{"title":"Overview","id":"overview"},{"title":"Association ≠ Authority","id":"association-authority"},{"title":"Connection Scope","id":"connection-scope"},{"title":"Authority Matrix","id":"authority-matrix"},{"title":"Relationship to the Current API Reference","id":"relationship-to-the-current-api-reference"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n hr: \"hr\",\n li: \"li\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n }, {Note, Warning} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"overview\",\n children: \"Overview\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the \", _jsx(_components.strong, {\n children: \"ownership and authority contract\"\n }), \" for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors API reference\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"association-authority\",\n children: \"Association ≠ Authority\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Artists in Recoup are \", _jsx(_components.strong, {\n children: \"canonical and shared\"\n }), \". The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"An artist appearing in an account's roster (\", _jsx(_components.code, {\n children: \"account_artist_ids\"\n }), \") grants \", _jsx(_components.strong, {\n children: \"read and analytics access only\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"An artist appearing in an organization's roster likewise grants \", _jsx(_components.strong, {\n children: \"read and analytics access only\"\n }), \" to org members.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Neither form of association ever grants the right to authorize, execute, or disconnect a connection.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsxs(_components.p, {\n children: [\"Roster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does \", _jsx(_components.strong, {\n children: \"not\"\n }), \" let Account B post through that connection.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"connection-scope\",\n children: \"Connection Scope\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connections are scoped to the \", _jsx(_components.strong, {\n children: \"relationship between an owner and an artist\"\n }), \", not to the bare canonical artist:\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Connection type\"\n }), _jsx(_components.th, {\n children: \"Scoped to\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Personal\"\n }), _jsxs(_components.td, {\n children: [\"The \", _jsx(_components.code, {\n children: \"(account, artist)\"\n }), \" pair\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Org-shared\"\n }), _jsxs(_components.td, {\n children: [\"The \", _jsx(_components.code, {\n children: \"(organization, artist)\"\n }), \" pair\"]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The connection is keyed on the \", _jsx(_components.strong, {\n children: \"join row\"\n }), \" (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Whoever establishes a connection owns it.\"\n }), \" Ownership is set at authorization time and does not transfer through roster changes.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Because artists stay canonical and shared, \", _jsx(_components.strong, {\n children: \"isolation lives on the connection\"\n }), \": sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"authority-matrix\",\n children: \"Authority Matrix\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Capability\"\n }), _jsx(_components.th, {\n children: \"Who has it\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Read / analytics on an artist\"\n }), _jsx(_components.td, {\n children: \"Any account or org member with the artist in their roster\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Authorize a new connection\"\n }), _jsx(_components.td, {\n children: \"The account (or org member, for org-shared) establishing the connection, who then owns it\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Execute actions through a connection\"\n }), _jsx(_components.td, {\n children: \"The owning account only; for org-shared connections, members of the owning org\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Disconnect a connection\"\n }), _jsx(_components.td, {\n children: \"The owning account only; for org-shared connections, members of the owning org\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Admin override\"\n }), _jsx(_components.td, {\n children: \"Recoup staff only (admins of the Recoup internal organization)\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"The admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection.\"\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"relationship-to-the-current-api-reference\",\n children: \"Relationship to the Current API Reference\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors endpoint reference\"\n }), \" currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-\", _jsx(_components.code, {\n children: \"(account, artist)\"\n }), \" / per-\", _jsx(_components.code, {\n children: \"(organization, artist)\"\n }), \" model defined here. Where the two disagree, \", _jsx(_components.strong, {\n children: \"this page is the authority contract\"\n }), \". Endpoint docs will be updated as the re-keyed API ships.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Endpoint request and response shapes for the re-keyed model are deliberately not documented here yet.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Connection Ownership The connector connection-ownership and authority contract: who owns a connection, who can act through it, and why roster membership never grants execute rights. Connectors Concepts ## Overview Connectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the **ownership and authority contract** for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it. This contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the [Connectors API reference](/api-reference/connectors/list). --- ## Association ≠ Authority Artists in Recoup are **canonical and shared**. The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections: - An artist appearing in an account's roster (`account_artist_ids`) grants **read and analytics access only**. - An artist appearing in an organization's roster likewise grants **read and analytics access only** to org members. - Neither form of association ever grants the right to authorize, execute, or disconnect a connection. Roster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does **not** let Account B post through that connection. --- ## Connection Scope Connections are scoped to the **relationship between an owner and an artist**, not to the bare canonical artist: | Connection type | Scoped to | |-----------------|-----------| | Personal | The `(account, artist)` pair | | Org-shared | The `(organization, artist)` pair | The connection is keyed on the **join row** (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist. **Whoever establishes a connection owns it.** Ownership is set at authorization time and does not transfer through roster changes. Because artists stay canonical and shared, **isolation lives on the connection**: sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it. --- ## Authority Matrix | Capability | Who has it | |------------|-----------| | Read / analytics on an artist | Any account or org member with the artist in their roster | | Authorize a new connection | The account (or org member, for org-shared) establishing the connection, who then owns it | | Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org | | Disconnect a connection | The owning account only; for org-shared connections, members of the owning org | | Admin override | Recoup staff only (admins of the Recoup internal organization) | The admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection. --- ## Relationship to the Current API Reference The [Connectors endpoint reference](/api-reference/connectors/list) currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-`(account, artist)` / per-`(organization, artist)` model defined here. Where the two disagree, **this page is the authority contract**. Endpoint docs will be updated as the re-keyed API ships. Endpoint request and response shapes for the re-keyed model are deliberately not documented here yet. "},{"slug":"api-reference/connectors/list","title":"List Connectors","description":"List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok, YouTube, X (Twitter), LinkedIn) along with whether they are currently connected.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/connectors","spec":"social.json"},"searchText":"List Connectors List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok, YouTube, X (Twitter), LinkedIn) along with whether they are currently connected. Connectors Connectors GET /api/connectors "},{"slug":"api-reference/connectors/authorize","title":"Authorize Connector","description":"Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/authorize.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors","spec":"social.json"},"searchText":"Authorize Connector Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow. Connectors Connectors POST /api/connectors "},{"slug":"api-reference/connectors/disconnect","title":"Disconnect Connector","description":"Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/disconnect.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/connectors","spec":"social.json"},"searchText":"Disconnect Connector Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials. Connectors Connectors DELETE /api/connectors "},{"slug":"api-reference/connectors/list-actions","title":"List Connector Actions","description":"List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/list-actions.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/connectors/actions","spec":"social.json"},"searchText":"List Connector Actions List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors. Connectors Connectors GET /api/connectors/actions "},{"slug":"api-reference/connectors/upload-file","title":"Upload Connector File","description":"Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action).","category":"Connectors","group":"Connectors","source":"api-reference/connectors/upload-file.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors/files","spec":"social.json"},"searchText":"Upload Connector File Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action). Connectors Connectors POST /api/connectors/files "},{"slug":"api-reference/connectors/execute-action","title":"Execute Connector Action","description":"Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/execute-action.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors/actions","spec":"social.json"},"searchText":"Execute Connector Action Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor. Connectors Connectors POST /api/connectors/actions "},{"slug":"api-reference/publishing/create","title":"Create Post","description":"Create post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/posts","spec":"social.json"},"searchText":"Create Post Create post Connectors Publishing POST /api/posts "},{"slug":"api-reference/publishing/list","title":"List Posts","description":"List posts","category":"Connectors","group":"Publishing","source":"api-reference/publishing/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/posts","spec":"social.json"},"searchText":"List Posts List posts Connectors Publishing GET /api/posts "},{"slug":"api-reference/publishing/get","title":"Get Post","description":"Get post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/posts/{id}","spec":"social.json"},"searchText":"Get Post Get post Connectors Publishing GET /api/posts/{id} "},{"slug":"api-reference/publishing/stats","title":"Get Post Stats","description":"Get post stats","category":"Connectors","group":"Publishing","source":"api-reference/publishing/stats.mdx","body":"## Data coverage\n\nLinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds.\n","headings":[{"title":"Data coverage","id":"data-coverage"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"data-coverage\",\n children: \"Data coverage\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"LinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","api":{"method":"GET","path":"/api/posts/{id}/stats","spec":"social.json"},"searchText":"Get Post Stats Get post stats Connectors Publishing GET /api/posts/{id}/stats ## Data coverage LinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds. "},{"slug":"api-reference/publishing/cancel","title":"Cancel Post","description":"Cancel post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/cancel.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/posts/{id}","spec":"social.json"},"searchText":"Cancel Post Cancel post Connectors Publishing DELETE /api/posts/{id} "},{"slug":"api-reference/applications/validate-registration","title":"Check an application proposal","description":"Validate proposed app addresses in your workspace without registering or activating an application.","category":"Sites","group":"Application proposals","source":"api-reference/applications/validate-registration.mdx","body":"\n Pending coordinated release. This checks a proposal; it does not register an\n app or make its origins trusted. Discover tool availability in your connected\n host before use.\n\n\nBefore connecting an external app, check its proposed name, environment, origins\nand return URLs. A successful result means those values passed validation for\nthe selected workspace. It does not prove domain ownership.\n\n## What happens\n\nThe preflight runs after normal Recoup authentication. First-time sign-in can\nperform normal account provisioning and send its welcome email. After that,\nthis validator does not persist an application or issue application credentials.\nIt does not edit provider callbacks, create fan identities or sessions, allocate\ncapacity, or authorize purchases and spending.\n\n`workspace_id` and `billing_owner_id` come from the authenticated account or an\norganization it can access. They describe the proposed owner only. Supplying\n`organization_id` does not grant workspace access. Do not submit account or\nbilling ownership overrides, secrets or tokens in the proposal.\n\nThe result is flat and includes `status: \"validated\"`, `persisted: false` and\n`origins_verified: false`. It contains no application ID or token to install.\n\n## Addresses and environments\n\n- Choose `development` or `production` explicitly for each proposal.\n- Use exact canonical origins such as `https://music.example`, without a trailing\n slash, wildcard, path, credentials, query or fragment. Different hosts and\n ports are different origins.\n- HTTPS is required. Development also accepts HTTP on `localhost`, `127.0.0.1`\n and `[::1]`; these loopback hosts are rejected in production.\n- A return URL must be an exact canonical URL on one of the proposed origins,\n without credentials or fragments. For a bare host use its canonical trailing\n slash, such as `https://music.example/`. Query strings are retained literally.\n- Each list takes 1–32 distinct addresses, each at most 2048 characters. The name\n is trimmed and must then contain 1–120 characters. These are input limits,\n not subscription or usage allowances.\n\nMatching a return URL to a caller-proposed origin does not establish that the\ncaller owns either address. No DNS check, URL fetch or domain proof is performed.\n\n## Standard MCP\n\nOn a standard API-key MCP connection that exposes `validate_application_registration`,\nuse the same proposal fields as HTTP. Account identity comes from the connection;\ndo not add `account_id` or extract a host-managed OAuth token.\n\n```json\n{\n \"name\": \"Release companion\",\n \"environment\": \"production\",\n \"allowed_origins\": [\"https://music.example\"],\n \"return_urls\": [\"https://music.example/listen?connected=spotify\"]\n}\n```\n\nDelegated OAuth excludes this tool, including connections with `mcp:tools`.\nHTTP and standard MCP share proposal validation; their transport-specific error\nenvelopes differ. HTTP authentication errors can use `error` or `message`, while\nhandled preflight errors use `status: \"error\"` and `error`. MCP failures are tool\nerrors or SDK input-validation errors. None confirms registration or activation.\n\nSee [authentication](/authentication) and [MCP connection guidance](/mcp).\nApplication persistence, origin proof/reverification, provider configuration,\nfan bootstrap, suspension and quota policy require their own completed contracts.\n","headings":[{"title":"What happens","id":"what-happens"},{"title":"Addresses and environments","id":"addresses-and-environments"},{"title":"Standard MCP","id":"standard-mcp"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n ul: \"ul\",\n ...props.components\n }, {Warning} = _components;\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Pending coordinated release. This checks a proposal; it does not register an\\napp or make its origins trusted. Discover tool availability in your connected\\nhost before use.\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before connecting an external app, check its proposed name, environment, origins\\nand return URLs. A successful result means those values passed validation for\\nthe selected workspace. It does not prove domain ownership.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-happens\",\n children: \"What happens\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The preflight runs after normal Recoup authentication. First-time sign-in can\\nperform normal account provisioning and send its welcome email. After that,\\nthis validator does not persist an application or issue application credentials.\\nIt does not edit provider callbacks, create fan identities or sessions, allocate\\ncapacity, or authorize purchases and spending.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"workspace_id\"\n }), \" and \", _jsx(_components.code, {\n children: \"billing_owner_id\"\n }), \" come from the authenticated account or an\\norganization it can access. They describe the proposed owner only. Supplying\\n\", _jsx(_components.code, {\n children: \"organization_id\"\n }), \" does not grant workspace access. Do not submit account or\\nbilling ownership overrides, secrets or tokens in the proposal.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The result is flat and includes \", _jsx(_components.code, {\n children: \"status: \\\"validated\\\"\"\n }), \", \", _jsx(_components.code, {\n children: \"persisted: false\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"origins_verified: false\"\n }), \". It contains no application ID or token to install.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"addresses-and-environments\",\n children: \"Addresses and environments\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Choose \", _jsx(_components.code, {\n children: \"development\"\n }), \" or \", _jsx(_components.code, {\n children: \"production\"\n }), \" explicitly for each proposal.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use exact canonical origins such as \", _jsx(_components.code, {\n children: \"https://music.example\"\n }), \", without a trailing\\nslash, wildcard, path, credentials, query or fragment. Different hosts and\\nports are different origins.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"HTTPS is required. Development also accepts HTTP on \", _jsx(_components.code, {\n children: \"localhost\"\n }), \", \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \"\\nand \", _jsx(_components.code, {\n children: \"[::1]\"\n }), \"; these loopback hosts are rejected in production.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"A return URL must be an exact canonical URL on one of the proposed origins,\\nwithout credentials or fragments. For a bare host use its canonical trailing\\nslash, such as \", _jsx(_components.code, {\n children: \"https://music.example/\"\n }), \". Query strings are retained literally.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Each list takes 1–32 distinct addresses, each at most 2048 characters. The name\\nis trimmed and must then contain 1–120 characters. These are input limits,\\nnot subscription or usage allowances.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Matching a return URL to a caller-proposed origin does not establish that the\\ncaller owns either address. No DNS check, URL fetch or domain proof is performed.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"standard-mcp\",\n children: \"Standard MCP\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"On a standard API-key MCP connection that exposes \", _jsx(_components.code, {\n children: \"validate_application_registration\"\n }), \",\\nuse the same proposal fields as HTTP. Account identity comes from the connection;\\ndo not add \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" or extract a host-managed OAuth token.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"name\\\": \\\"Release companion\\\",\\n \\\"environment\\\": \\\"production\\\",\\n \\\"allowed_origins\\\": [\\\"https://music.example\\\"],\\n \\\"return_urls\\\": [\\\"https://music.example/listen?connected=spotify\\\"]\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Delegated OAuth excludes this tool, including connections with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \".\\nHTTP and standard MCP share proposal validation; their transport-specific error\\nenvelopes differ. HTTP authentication errors can use \", _jsx(_components.code, {\n children: \"error\"\n }), \" or \", _jsx(_components.code, {\n children: \"message\"\n }), \", while\\nhandled preflight errors use \", _jsx(_components.code, {\n children: \"status: \\\"error\\\"\"\n }), \" and \", _jsx(_components.code, {\n children: \"error\"\n }), \". MCP failures are tool\\nerrors or SDK input-validation errors. None confirms registration or activation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"authentication\"\n }), \" and \", _jsx(_components.a, {\n href: \"/mcp\",\n children: \"MCP connection guidance\"\n }), \".\\nApplication persistence, origin proof/reverification, provider configuration,\\nfan bootstrap, suspension and quota policy require their own completed contracts.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"POST","path":"/api/applications/registration/validate","spec":"applications.json"},"searchText":"Check an application proposal Validate proposed app addresses in your workspace without registering or activating an application. Sites Application proposals POST /api/applications/registration/validate Pending coordinated release. This checks a proposal; it does not register an app or make its origins trusted. Discover tool availability in your connected host before use. Before connecting an external app, check its proposed name, environment, origins and return URLs. A successful result means those values passed validation for the selected workspace. It does not prove domain ownership. ## What happens The preflight runs after normal Recoup authentication. First-time sign-in can perform normal account provisioning and send its welcome email. After that, this validator does not persist an application or issue application credentials. It does not edit provider callbacks, create fan identities or sessions, allocate capacity, or authorize purchases and spending. `workspace_id` and `billing_owner_id` come from the authenticated account or an organization it can access. They describe the proposed owner only. Supplying `organization_id` does not grant workspace access. Do not submit account or billing ownership overrides, secrets or tokens in the proposal. The result is flat and includes `status: \"validated\"`, `persisted: false` and `origins_verified: false`. It contains no application ID or token to install. ## Addresses and environments - Choose `development` or `production` explicitly for each proposal. - Use exact canonical origins such as `https://music.example`, without a trailing slash, wildcard, path, credentials, query or fragment. Different hosts and ports are different origins. - HTTPS is required. Development also accepts HTTP on `localhost`, `127.0.0.1` and `[::1]`; these loopback hosts are rejected in production. - A return URL must be an exact canonical URL on one of the proposed origins, without credentials or fragments. For a bare host use its canonical trailing slash, such as `https://music.example/`. Query strings are retained literally. - Each list takes 1–32 distinct addresses, each at most 2048 characters. The name is trimmed and must then contain 1–120 characters. These are input limits, not subscription or usage allowances. Matching a return URL to a caller-proposed origin does not establish that the caller owns either address. No DNS check, URL fetch or domain proof is performed. ## Standard MCP On a standard API-key MCP connection that exposes `validate_application_registration`, use the same proposal fields as HTTP. Account identity comes from the connection; do not add `account_id` or extract a host-managed OAuth token. Delegated OAuth excludes this tool, including connections with `mcp:tools`. HTTP and standard MCP share proposal validation; their transport-specific error envelopes differ. HTTP authentication errors can use `error` or `message`, while handled preflight errors use `status: \"error\"` and `error`. MCP failures are tool errors or SDK input-validation errors. None confirms registration or activation. See [authentication](/authentication) and [MCP connection guidance](/mcp). Application persistence, origin proof/reverification, provider configuration, fan bootstrap, suspension and quota policy require their own completed contracts. "},{"slug":"api-reference/sites/overview","title":"Sites","description":"Create, generate, and publish fan experiences through the API or MCP.","category":"Sites","group":"Sites","source":"api-reference/sites/overview.mdx","body":"Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a **private draft**. Generation never publishes it automatically.\n\n## Authentication\n\nPrivate HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`.\nMCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection.\n\nThe caller is derived from authentication. Do not send an `account_id`. An optional `organizationId` selects a workspace the caller can access. Omit it for the authenticated account's workspace.\n\n## Endpoints and tools\n\n| HTTP | MCP tool | Result |\n| --- | --- | --- |\n| `GET /api/sites` | `list_sites` | `{ sites: [...] }` |\n| `POST /api/sites` | `create_site` | `{ site: ... }`, HTTP 201 |\n| `GET /api/sites/{id}` | `get_site` | `{ site: ... }` |\n| `PATCH /api/sites/{id}` action `concepts` | `propose_site_concepts` | Short pitches or missing context |\n| `PATCH /api/sites/{id}` action `generate` | `generate_site` | Generate from an optional customer-selected pitch; otherwise select a concept |\n| `PATCH /api/sites/{id}` action `generation` | `get_site_generation` | Status for the specified generation token |\n| `PATCH /api/sites/{id}` action `publish` | `publish_site` | Publish the saved draft or the playable build selected by `generationToken` |\n| `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained |\n| `PATCH /api/sites/{id}` action `delete` | `delete_site` | `{ \"deleted\": true, \"id\": \"...\" }` |\n| `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 |\n| `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` |\n\nListing accepts optional `organizationId` and `artistId` query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response.\n\n## Create and generate\n\nCreate a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL.\n\n```bash\ncurl https://api.recoupable.dev/api/sites \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"releaseUrl\":\"https://open.spotify.com/track/TRACK_ID\",\"brief\":\"Build a maze game\"}'\n```\n\nOptional creation fields: `name` (120 characters), `brief` (6,000), `organizationId`, `artistId`, and `assets` (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used.\n\nRead `site.id` and `site.revision`, then start automatic generation:\n\n```json\n{\"action\":\"generate\",\"revision\":0}\n```\n\nFor Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused.\n\nTo choose a concept yourself before generation, optionally request pitches:\n\n```json\n{\"action\":\"concepts\",\"revision\":0}\n```\n\nSend this to `PATCH /api/sites/{id}`, or call MCP `propose_site_concepts` with `id` and `revision`. Optional `instruction` and `contextBriefId` apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft.\n\nThe response is `{ concepts: { status, candidates, reason }, revision }`. Status is `ready`, `needs-context`, or `no-good-concept`. Metadata and cover details alone return `needs-context`; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork.\n\nIn the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains `name`, `activity`, `fanMotivation`, `songOrArtistConnection`, and `friendHook`. Pass the selected object unchanged as `approvedConcept`:\n\n```json\n{\n \"action\": \"generate\",\n \"revision\": 0,\n \"approvedConcept\": {\n \"name\": \"CUSTOMER_SELECTED_NAME\",\n \"activity\": \"SELECTED_ACTIVITY\",\n \"fanMotivation\": \"SELECTED_MOTIVATION\",\n \"songOrArtistConnection\": \"SELECTED_CONNECTION\",\n \"friendHook\": \"SELECTED_HOOK\"\n }\n}\n```\n\nMCP `generate_site` accepts the same fields plus `id`, without `action`. A customer-authored concept is also accepted. The optional `approvedConcept` preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context.\n\nGeneration defaults to background execution and returns a generation token; poll `get_site_generation` (HTTP action `generation`) for the result. Set `background: false` only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked `needs-review`; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass.\n\nGeneration failures identify the stopped stage and leave the saved draft unchanged. A `409` means another edit changed the revision; read the site again before retrying.\n\n### Poll background generation\n\nSend this JSON body to `PATCH /api/sites/{id}` using the token returned by the\ngeneration request. MCP `get_site_generation` takes `id` and `token`, without `action`.\nPolling uses `token`; publishing and cancellation use `generationToken`.\n\n```json\n{\"action\":\"generation\",\"token\":\"TOKEN_FROM_GENERATION\"}\n```\n\nThe token is bound to its site and caller and expires. Invalid, expired or\nmismatched tokens return 404 during token verification; a missing or empty token\nis invalid input (400). A running job is not proof that a\nplayable build or a published page exists; read the returned status and progress.\n\n## Generate from saved Context Engine evidence\n\nSave a single-song `creative_direction` brief using the Context Engine `save_brief` action, then pass its snapshot ID when requesting pitches:\n\n```json\n{\n \"action\": \"concepts\",\n \"revision\": 0,\n \"contextBriefId\": \"SAVED_BRIEF_UUID\"\n}\n```\n\nPass the same `contextBriefId` with the selected `approvedConcept` to generation. It is available on both MCP `propose_site_concepts` and `generate_site`. Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied.\n\nThis path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial.\n\nGeneration still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response.\n\n## Publish\n\nAfter reviewing the intended draft or preview, publish through the same PATCH\nendpoint or MCP `publish_site`, using the site's current saved revision.\n\nPublishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports `fanConnection: \"enabled\"`.\n\nFor a custom hosted destination, HTTP callers may include `returnUrl` (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations.\n\nThe public page is `https://chat.recoupable.dev/s/{id}`.\n\n### Publish the saved draft\n\nUse the current revision from the saved site (3 in this example):\n\n```json\n{\"action\":\"publish\",\"revision\":3}\n```\n\nOmitting `generationToken` selects the saved draft, even when a background job has\na newer preview. MCP `publish_site` takes `id` and `revision`, without `action`.\n\n### Publish a working preview\n\nTo publish a specific working preview from a background generation, pass its\ntoken as `generationToken` and the site's current saved revision:\n\n```json\n{\"action\":\"publish\",\"revision\":3,\"generationToken\":\"TOKEN_FROM_GENERATION\"}\n```\n\nMCP `publish_site` uses the same fields plus `id`, without `action`. The token must\nmatch the site and caller. The selected build must contain a completed playable\nbuild step for the current site/workspace/revision; the whole generation job need\nnot already be completed. A preview that is not ready returns 400, a stale build\nreturns 409, and invalid or expired token access returns 404. A temporary saved-build\nfailure may return 503. Without `generationToken`, publication uses the saved draft;\nit does not automatically select the newest background preview.\n\n### Upgrade required\n\nAn ineligible workspace receives HTTP 402 with an error body, for example:\n\n```json\n{\"error\":\"An active paid Recoup subscription is required to publish a site. Subscribe in this site’s workspace, then publish again.\"}\n```\n\nSubscribe in the site's owning workspace before retrying the intended publish.\nThis response does not publish the site or create a checkout session.\n\n### Unpublish\n\nSend `PATCH /api/sites/{id}` with the current revision to remove the public\nsnapshot while retaining the draft. MCP `unpublish_site` takes `id` and `revision`.\n\n```json\n{\"action\":\"unpublish\",\"revision\":3}\n```\n\nAgents should publish, unpublish or delete only when explicitly instructed.\n\n## Delete and cancel generation\n\nDelete only when explicitly instructed. Send `PATCH /api/sites/{id}` with `action: \"delete\"` and the current `revision` in its JSON request body (Content-Type: application/json). Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.\n\nFor example, use the current saved revision and the token returned by a known generation:\n\n```json\n{\"action\":\"delete\",\"revision\":3,\"generationToken\":\"TOKEN_FROM_GENERATION\"}\n```\n\nOmit generationToken when no known generation needs cancellation.\n\nDeletion checks workspace access and revision, then returns `{ \"deleted\": true, \"id\": \"...\" }`. A stale revision returns 409; reload before retrying. Unpublish with `action: \"unpublish\"` when the draft should remain available.\n\n## Uploads\n\nHTTP uploads are multipart forms with a `file` field and optional `organizationId` query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature.\n\nMCP's `upload_site_asset` accepts `name`, `contentType`, `base64` file bytes, and optional `organizationId`. It uses the same validation and storage path as HTTP.\n\n## Public endpoints\n\n- `GET /api/sites/public/{id}` returns `{ snapshot: ... }` for a published site only. Drafts, account identifiers, and signup data are excluded.\n- `POST /api/sites/public/{id}/signup` accepts `{\"email\":\"fan@example.com\",\"consent\":\"yes\"}`. An optional `website` honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups.\n\nPublic pages and the browser music player render in the chat app. The API provides\nsnapshots, generation, uploads, signup persistence and the fan-connection integration\nroutes listed below.\n\n## Route coverage\n\nThe lifecycle and public snapshot/signup operations above are documented here in\nprose; they are not a complete Sites OpenAPI specification. The following existing\nroutes are accounted for as integration surfaces, outside the copyable lifecycle\nexamples. Listing them does not establish live authorization or add an MCP tool.\n\n### Authenticated integration routes\n\n| HTTP | Purpose |\n| --- | --- |\n| `GET /api/sites/{id}/fan-connection` | Read fan-connection configuration |\n| `PUT /api/sites/{id}/fan-connection` | Configure the fan connection through the authenticated integration |\n| `GET /api/sites/{id}/fans` | Fan reporting |\n| `GET /api/sites/{id}/activity` | Activity reporting |\n\n### Browser integration routes\n\n| HTTP | Purpose |\n| --- | --- |\n| `GET /api/sites/apple/config` | Browser music configuration |\n| `POST /api/sites/public/{id}/activity` | Published-site activity collection |\n| `GET /api/sites/public/{id}/spotify` | Show the fan-connection acceptance page |\n| `POST /api/sites/public/{id}/spotify` | Begin Spotify authorization after acceptance |\n\nThese browser flows are not replacements for a private lifecycle request or proof\nof a completed fan connection. Email signup and Spotify connection are distinct.\n\n### Provider callback\n\n`GET /api/sites/spotify/callback` completes the provider redirect flow. It is\nintentionally excluded from agent lifecycle examples; do not invoke it as a\nstandalone operation. OPTIONS preflight handlers are also excluded from the\noperation tables because they serve browser CORS negotiation.\n\n## Errors\n\n- `402`: publication requires an eligible paid workspace.\n\n`400` invalid input; `401` missing/invalid authentication; `403` workspace or artist access denied; `404` missing/unpublished site; `409` stale revision; `422` Spotify metadata unavailable; `503` temporary operation failure.\n","headings":[{"title":"Authentication","id":"authentication"},{"title":"Endpoints and tools","id":"endpoints-and-tools"},{"title":"Create and generate","id":"create-and-generate"},{"title":"Generate from saved Context Engine evidence","id":"generate-from-saved-context-engine-evidence"},{"title":"Publish","id":"publish"},{"title":"Delete and cancel generation","id":"delete-and-cancel-generation"},{"title":"Uploads","id":"uploads"},{"title":"Public endpoints","id":"public-endpoints"},{"title":"Route coverage","id":"route-coverage"},{"title":"Errors","id":"errors"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a \", _jsx(_components.strong, {\n children: \"private draft\"\n }), \". Generation never publishes it automatically.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication\",\n children: \"Authentication\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Private HTTP endpoints accept exactly one of \", _jsx(_components.code, {\n children: \"x-api-key: YOUR_API_KEY\"\n }), \" or \", _jsx(_components.code, {\n children: \"Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN\"\n }), \".\\nMCP uses the existing authenticated \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" connection.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The caller is derived from authentication. Do not send an \", _jsx(_components.code, {\n children: \"account_id\"\n }), \". An optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" selects a workspace the caller can access. Omit it for the authenticated account's workspace.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"endpoints-and-tools\",\n children: \"Endpoints and tools\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"MCP tool\"\n }), _jsx(_components.th, {\n children: \"Result\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"list_sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ sites: [...] }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"create_site\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"{ site: ... }\"\n }), \", HTTP 201\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ site: ... }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"concepts\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"propose_site_concepts\"\n })\n }), _jsx(_components.td, {\n children: \"Short pitches or missing context\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"generate\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"generate_site\"\n })\n }), _jsx(_components.td, {\n children: \"Generate from an optional customer-selected pitch; otherwise select a concept\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"generation\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site_generation\"\n })\n }), _jsx(_components.td, {\n children: \"Status for the specified generation token\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"publish\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"publish_site\"\n })\n }), _jsxs(_components.td, {\n children: [\"Publish the saved draft or the playable build selected by \", _jsx(_components.code, {\n children: \"generationToken\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"unpublish\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"unpublish_site\"\n })\n }), _jsx(_components.td, {\n children: \"Public snapshot removed, draft retained\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"delete\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"delete_site\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ \\\"deleted\\\": true, \\\"id\\\": \\\"...\\\" }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/signups\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site_signups\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"{ signups: [{ email, created_at }] }\"\n }), \", up to 10,000\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/assets\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"upload_site_asset\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ asset: { url, name, type } }\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Listing accepts optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" and \", _jsx(_components.code, {\n children: \"artistId\"\n }), \" query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"create-and-generate\",\n children: \"Create and generate\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Create a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL.\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl https://api.recoupable.dev/api/sites \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"releaseUrl\\\":\\\"https://open.spotify.com/track/TRACK_ID\\\",\\\"brief\\\":\\\"Build a maze game\\\"}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Optional creation fields: \", _jsx(_components.code, {\n children: \"name\"\n }), \" (120 characters), \", _jsx(_components.code, {\n children: \"brief\"\n }), \" (6,000), \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \", \", _jsx(_components.code, {\n children: \"artistId\"\n }), \", and \", _jsx(_components.code, {\n children: \"assets\"\n }), \" (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Read \", _jsx(_components.code, {\n children: \"site.id\"\n }), \" and \", _jsx(_components.code, {\n children: \"site.revision\"\n }), \", then start automatic generation:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"generate\\\",\\\"revision\\\":0}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"For Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"To choose a concept yourself before generation, optionally request pitches:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"concepts\\\",\\\"revision\\\":0}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send this to \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \", or call MCP \", _jsx(_components.code, {\n children: \"propose_site_concepts\"\n }), \" with \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \". Optional \", _jsx(_components.code, {\n children: \"instruction\"\n }), \" and \", _jsx(_components.code, {\n children: \"contextBriefId\"\n }), \" apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response is \", _jsx(_components.code, {\n children: \"{ concepts: { status, candidates, reason }, revision }\"\n }), \". Status is \", _jsx(_components.code, {\n children: \"ready\"\n }), \", \", _jsx(_components.code, {\n children: \"needs-context\"\n }), \", or \", _jsx(_components.code, {\n children: \"no-good-concept\"\n }), \". Metadata and cover details alone return \", _jsx(_components.code, {\n children: \"needs-context\"\n }), \"; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"In the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"activity\"\n }), \", \", _jsx(_components.code, {\n children: \"fanMotivation\"\n }), \", \", _jsx(_components.code, {\n children: \"songOrArtistConnection\"\n }), \", and \", _jsx(_components.code, {\n children: \"friendHook\"\n }), \". Pass the selected object unchanged as \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"action\\\": \\\"generate\\\",\\n \\\"revision\\\": 0,\\n \\\"approvedConcept\\\": {\\n \\\"name\\\": \\\"CUSTOMER_SELECTED_NAME\\\",\\n \\\"activity\\\": \\\"SELECTED_ACTIVITY\\\",\\n \\\"fanMotivation\\\": \\\"SELECTED_MOTIVATION\\\",\\n \\\"songOrArtistConnection\\\": \\\"SELECTED_CONNECTION\\\",\\n \\\"friendHook\\\": \\\"SELECTED_HOOK\\\"\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP \", _jsx(_components.code, {\n children: \"generate_site\"\n }), \" accepts the same fields plus \", _jsx(_components.code, {\n children: \"id\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \". A customer-authored concept is also accepted. The optional \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \" preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Generation defaults to background execution and returns a generation token; poll \", _jsx(_components.code, {\n children: \"get_site_generation\"\n }), \" (HTTP action \", _jsx(_components.code, {\n children: \"generation\"\n }), \") for the result. Set \", _jsx(_components.code, {\n children: \"background: false\"\n }), \" only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked \", _jsx(_components.code, {\n children: \"needs-review\"\n }), \"; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Generation failures identify the stopped stage and leave the saved draft unchanged. A \", _jsx(_components.code, {\n children: \"409\"\n }), \" means another edit changed the revision; read the site again before retrying.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"poll-background-generation\",\n children: \"Poll background generation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send this JSON body to \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" using the token returned by the\\ngeneration request. MCP \", _jsx(_components.code, {\n children: \"get_site_generation\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"token\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \".\\nPolling uses \", _jsx(_components.code, {\n children: \"token\"\n }), \"; publishing and cancellation use \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"generation\\\",\\\"token\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"The token is bound to its site and caller and expires. Invalid, expired or\\nmismatched tokens return 404 during token verification; a missing or empty token\\nis invalid input (400). A running job is not proof that a\\nplayable build or a published page exists; read the returned status and progress.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"generate-from-saved-context-engine-evidence\",\n children: \"Generate from saved Context Engine evidence\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save a single-song \", _jsx(_components.code, {\n children: \"creative_direction\"\n }), \" brief using the Context Engine \", _jsx(_components.code, {\n children: \"save_brief\"\n }), \" action, then pass its snapshot ID when requesting pitches:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"action\\\": \\\"concepts\\\",\\n \\\"revision\\\": 0,\\n \\\"contextBriefId\\\": \\\"SAVED_BRIEF_UUID\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass the same \", _jsx(_components.code, {\n children: \"contextBriefId\"\n }), \" with the selected \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \" to generation. It is available on both MCP \", _jsx(_components.code, {\n children: \"propose_site_concepts\"\n }), \" and \", _jsx(_components.code, {\n children: \"generate_site\"\n }), \". Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Generation still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"publish\",\n children: \"Publish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"After reviewing the intended draft or preview, publish through the same PATCH\\nendpoint or MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \", using the site's current saved revision.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Publishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports \", _jsx(_components.code, {\n children: \"fanConnection: \\\"enabled\\\"\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a custom hosted destination, HTTP callers may include \", _jsx(_components.code, {\n children: \"returnUrl\"\n }), \" (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The public page is \", _jsx(_components.code, {\n children: \"https://chat.recoupable.dev/s/{id}\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"publish-the-saved-draft\",\n children: \"Publish the saved draft\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the current revision from the saved site (3 in this example):\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"publish\\\",\\\"revision\\\":3}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Omitting \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" selects the saved draft, even when a background job has\\na newer preview. MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"publish-a-working-preview\",\n children: \"Publish a working preview\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To publish a specific working preview from a background generation, pass its\\ntoken as \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" and the site's current saved revision:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"publish\\\",\\\"revision\\\":3,\\\"generationToken\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \" uses the same fields plus \", _jsx(_components.code, {\n children: \"id\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \". The token must\\nmatch the site and caller. The selected build must contain a completed playable\\nbuild step for the current site/workspace/revision; the whole generation job need\\nnot already be completed. A preview that is not ready returns 400, a stale build\\nreturns 409, and invalid or expired token access returns 404. A temporary saved-build\\nfailure may return 503. Without \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \", publication uses the saved draft;\\nit does not automatically select the newest background preview.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"upgrade-required\",\n children: \"Upgrade required\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"An ineligible workspace receives HTTP 402 with an error body, for example:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"error\\\":\\\"An active paid Recoup subscription is required to publish a site. Subscribe in this site’s workspace, then publish again.\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Subscribe in the site's owning workspace before retrying the intended publish.\\nThis response does not publish the site or create a checkout session.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"unpublish\",\n children: \"Unpublish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" with the current revision to remove the public\\nsnapshot while retaining the draft. MCP \", _jsx(_components.code, {\n children: \"unpublish_site\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"unpublish\\\",\\\"revision\\\":3}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Agents should publish, unpublish or delete only when explicitly instructed.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"delete-and-cancel-generation\",\n children: \"Delete and cancel generation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Delete only when explicitly instructed. Send \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" with \", _jsx(_components.code, {\n children: \"action: \\\"delete\\\"\"\n }), \" and the current \", _jsx(_components.code, {\n children: \"revision\"\n }), \" in its JSON request body (Content-Type: application/json). Include \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For example, use the current saved revision and the token returned by a known generation:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"delete\\\",\\\"revision\\\":3,\\\"generationToken\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Omit generationToken when no known generation needs cancellation.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Deletion checks workspace access and revision, then returns \", _jsx(_components.code, {\n children: \"{ \\\"deleted\\\": true, \\\"id\\\": \\\"...\\\" }\"\n }), \". A stale revision returns 409; reload before retrying. Unpublish with \", _jsx(_components.code, {\n children: \"action: \\\"unpublish\\\"\"\n }), \" when the draft should remain available.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"uploads\",\n children: \"Uploads\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP uploads are multipart forms with a \", _jsx(_components.code, {\n children: \"file\"\n }), \" field and optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP's \", _jsx(_components.code, {\n children: \"upload_site_asset\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"contentType\"\n }), \", \", _jsx(_components.code, {\n children: \"base64\"\n }), \" file bytes, and optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \". It uses the same validation and storage path as HTTP.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"public-endpoints\",\n children: \"Public endpoints\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{id}\"\n }), \" returns \", _jsx(_components.code, {\n children: \"{ snapshot: ... }\"\n }), \" for a published site only. Drafts, account identifiers, and signup data are excluded.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/signup\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{\\\"email\\\":\\\"fan@example.com\\\",\\\"consent\\\":\\\"yes\\\"}\"\n }), \". An optional \", _jsx(_components.code, {\n children: \"website\"\n }), \" honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Public pages and the browser music player render in the chat app. The API provides\\nsnapshots, generation, uploads, signup persistence and the fan-connection integration\\nroutes listed below.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"route-coverage\",\n children: \"Route coverage\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The lifecycle and public snapshot/signup operations above are documented here in\\nprose; they are not a complete Sites OpenAPI specification. The following existing\\nroutes are accounted for as integration surfaces, outside the copyable lifecycle\\nexamples. Listing them does not establish live authorization or add an MCP tool.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"authenticated-integration-routes\",\n children: \"Authenticated integration routes\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"Purpose\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/fan-connection\"\n })\n }), _jsx(_components.td, {\n children: \"Read fan-connection configuration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"PUT /api/sites/{id}/fan-connection\"\n })\n }), _jsx(_components.td, {\n children: \"Configure the fan connection through the authenticated integration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/fans\"\n })\n }), _jsx(_components.td, {\n children: \"Fan reporting\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/activity\"\n })\n }), _jsx(_components.td, {\n children: \"Activity reporting\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"browser-integration-routes\",\n children: \"Browser integration routes\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"Purpose\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/apple/config\"\n })\n }), _jsx(_components.td, {\n children: \"Browser music configuration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/activity\"\n })\n }), _jsx(_components.td, {\n children: \"Published-site activity collection\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/public/{id}/spotify\"\n })\n }), _jsx(_components.td, {\n children: \"Show the fan-connection acceptance page\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/spotify\"\n })\n }), _jsx(_components.td, {\n children: \"Begin Spotify authorization after acceptance\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"These browser flows are not replacements for a private lifecycle request or proof\\nof a completed fan connection. Email signup and Spotify connection are distinct.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"provider-callback\",\n children: \"Provider callback\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/spotify/callback\"\n }), \" completes the provider redirect flow. It is\\nintentionally excluded from agent lifecycle examples; do not invoke it as a\\nstandalone operation. OPTIONS preflight handlers are also excluded from the\\noperation tables because they serve browser CORS negotiation.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"errors\",\n children: \"Errors\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"402\"\n }), \": publication requires an eligible paid workspace.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"400\"\n }), \" invalid input; \", _jsx(_components.code, {\n children: \"401\"\n }), \" missing/invalid authentication; \", _jsx(_components.code, {\n children: \"403\"\n }), \" workspace or artist access denied; \", _jsx(_components.code, {\n children: \"404\"\n }), \" missing/unpublished site; \", _jsx(_components.code, {\n children: \"409\"\n }), \" stale revision; \", _jsx(_components.code, {\n children: \"422\"\n }), \" Spotify metadata unavailable; \", _jsx(_components.code, {\n children: \"503\"\n }), \" temporary operation failure.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Sites Create, generate, and publish fan experiences through the API or MCP. Sites Sites Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a **private draft**. Generation never publishes it automatically. ## Authentication Private HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`. MCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection. The caller is derived from authentication. Do not send an `account_id`. An optional `organizationId` selects a workspace the caller can access. Omit it for the authenticated account's workspace. ## Endpoints and tools | HTTP | MCP tool | Result | | --- | --- | --- | | `GET /api/sites` | `list_sites` | `{ sites: [...] }` | | `POST /api/sites` | `create_site` | `{ site: ... }`, HTTP 201 | | `GET /api/sites/{id}` | `get_site` | `{ site: ... }` | | `PATCH /api/sites/{id}` action `concepts` | `propose_site_concepts` | Short pitches or missing context | | `PATCH /api/sites/{id}` action `generate` | `generate_site` | Generate from an optional customer-selected pitch; otherwise select a concept | | `PATCH /api/sites/{id}` action `generation` | `get_site_generation` | Status for the specified generation token | | `PATCH /api/sites/{id}` action `publish` | `publish_site` | Publish the saved draft or the playable build selected by `generationToken` | | `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained | | `PATCH /api/sites/{id}` action `delete` | `delete_site` | `{ \"deleted\": true, \"id\": \"...\" }` | | `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 | | `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` | Listing accepts optional `organizationId` and `artistId` query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response. ## Create and generate Create a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL. Optional creation fields: `name` (120 characters), `brief` (6,000), `organizationId`, `artistId`, and `assets` (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used. Read `site.id` and `site.revision`, then start automatic generation: For Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused. To choose a concept yourself before generation, optionally request pitches: Send this to `PATCH /api/sites/{id}`, or call MCP `propose_site_concepts` with `id` and `revision`. Optional `instruction` and `contextBriefId` apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft. The response is `{ concepts: { status, candidates, reason }, revision }`. Status is `ready`, `needs-context`, or `no-good-concept`. Metadata and cover details alone return `needs-context`; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork. In the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains `name`, `activity`, `fanMotivation`, `songOrArtistConnection`, and `friendHook`. Pass the selected object unchanged as `approvedConcept`: MCP `generate_site` accepts the same fields plus `id`, without `action`. A customer-authored concept is also accepted. The optional `approvedConcept` preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context. Generation defaults to background execution and returns a generation token; poll `get_site_generation` (HTTP action `generation`) for the result. Set `background: false` only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked `needs-review`; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass. Generation failures identify the stopped stage and leave the saved draft unchanged. A `409` means another edit changed the revision; read the site again before retrying. ### Poll background generation Send this JSON body to `PATCH /api/sites/{id}` using the token returned by the generation request. MCP `get_site_generation` takes `id` and `token`, without `action`. Polling uses `token`; publishing and cancellation use `generationToken`. The token is bound to its site and caller and expires. Invalid, expired or mismatched tokens return 404 during token verification; a missing or empty token is invalid input (400). A running job is not proof that a playable build or a published page exists; read the returned status and progress. ## Generate from saved Context Engine evidence Save a single-song `creative_direction` brief using the Context Engine `save_brief` action, then pass its snapshot ID when requesting pitches: Pass the same `contextBriefId` with the selected `approvedConcept` to generation. It is available on both MCP `propose_site_concepts` and `generate_site`. Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied. This path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial. Generation still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response. ## Publish After reviewing the intended draft or preview, publish through the same PATCH endpoint or MCP `publish_site`, using the site's current saved revision. Publishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports `fanConnection: \"enabled\"`. For a custom hosted destination, HTTP callers may include `returnUrl` (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations. The public page is `https://chat.recoupable.dev/s/{id}`. ### Publish the saved draft Use the current revision from the saved site (3 in this example): Omitting `generationToken` selects the saved draft, even when a background job has a newer preview. MCP `publish_site` takes `id` and `revision`, without `action`. ### Publish a working preview To publish a specific working preview from a background generation, pass its token as `generationToken` and the site's current saved revision: MCP `publish_site` uses the same fields plus `id`, without `action`. The token must match the site and caller. The selected build must contain a completed playable build step for the current site/workspace/revision; the whole generation job need not already be completed. A preview that is not ready returns 400, a stale build returns 409, and invalid or expired token access returns 404. A temporary saved-build failure may return 503. Without `generationToken`, publication uses the saved draft; it does not automatically select the newest background preview. ### Upgrade required An ineligible workspace receives HTTP 402 with an error body, for example: Subscribe in the site's owning workspace before retrying the intended publish. This response does not publish the site or create a checkout session. ### Unpublish Send `PATCH /api/sites/{id}` with the current revision to remove the public snapshot while retaining the draft. MCP `unpublish_site` takes `id` and `revision`. Agents should publish, unpublish or delete only when explicitly instructed. ## Delete and cancel generation Delete only when explicitly instructed. Send `PATCH /api/sites/{id}` with `action: \"delete\"` and the current `revision` in its JSON request body (Content-Type: application/json). Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job. For example, use the current saved revision and the token returned by a known generation: Omit generationToken when no known generation needs cancellation. Deletion checks workspace access and revision, then returns `{ \"deleted\": true, \"id\": \"...\" }`. A stale revision returns 409; reload before retrying. Unpublish with `action: \"unpublish\"` when the draft should remain available. ## Uploads HTTP uploads are multipart forms with a `file` field and optional `organizationId` query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature. MCP's `upload_site_asset` accepts `name`, `contentType`, `base64` file bytes, and optional `organizationId`. It uses the same validation and storage path as HTTP. ## Public endpoints - `GET /api/sites/public/{id}` returns `{ snapshot: ... }` for a published site only. Drafts, account identifiers, and signup data are excluded. - `POST /api/sites/public/{id}/signup` accepts `{\"email\":\"fan@example.com\",\"consent\":\"yes\"}`. An optional `website` honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups. Public pages and the browser music player render in the chat app. The API provides snapshots, generation, uploads, signup persistence and the fan-connection integration routes listed below. ## Route coverage The lifecycle and public snapshot/signup operations above are documented here in prose; they are not a complete Sites OpenAPI specification. The following existing routes are accounted for as integration surfaces, outside the copyable lifecycle examples. Listing them does not establish live authorization or add an MCP tool. ### Authenticated integration routes | HTTP | Purpose | | --- | --- | | `GET /api/sites/{id}/fan-connection` | Read fan-connection configuration | | `PUT /api/sites/{id}/fan-connection` | Configure the fan connection through the authenticated integration | | `GET /api/sites/{id}/fans` | Fan reporting | | `GET /api/sites/{id}/activity` | Activity reporting | ### Browser integration routes | HTTP | Purpose | | --- | --- | | `GET /api/sites/apple/config` | Browser music configuration | | `POST /api/sites/public/{id}/activity` | Published-site activity collection | | `GET /api/sites/public/{id}/spotify` | Show the fan-connection acceptance page | | `POST /api/sites/public/{id}/spotify` | Begin Spotify authorization after acceptance | These browser flows are not replacements for a private lifecycle request or proof of a completed fan connection. Email signup and Spotify connection are distinct. ### Provider callback `GET /api/sites/spotify/callback` completes the provider redirect flow. It is intentionally excluded from agent lifecycle examples; do not invoke it as a standalone operation. OPTIONS preflight handlers are also excluded from the operation tables because they serve browser CORS negotiation. ## Errors - `402`: publication requires an eligible paid workspace. `400` invalid input; `401` missing/invalid authentication; `403` workspace or artist access denied; `404` missing/unpublished site; `409` stale revision; `422` Spotify metadata unavailable; `503` temporary operation failure. "},{"slug":"essentials/site-fan-connection","title":"Connect Spotify fans to a site","description":"Configure paid fan connection from an artist agent and retrieve fans attributed to its site.","category":"Sites","group":"Sites","source":"essentials/site-fan-connection.mdx","body":"Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: `https://api.recoupable.dev`.\n\nPrivate calls use `x-api-key: $RECOUP_API_KEY` (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key.\n\n## Customer and site\n\n- `GET /api/accounts/id`: verify the current credential.\n- `POST /api/agents/signup` with `{ \"email\": \"customer@example.com\" }`: request email verification.\n- `POST /api/agents/verify` with `{ \"email\": \"customer@example.com\", \"code\": \"123456\" }`: receive `api_key`; never echo it.\n- `GET /api/artists`: inspect the caller's roster and choose the artist's account ID.\n- `GET /api/sites`: inspect existing site records.\n- `POST /api/sites` with `{ \"name\": \"Release experience\", \"artistId\": \"ARTIST_ACCOUNT_UUID\", \"releaseUrl\": \"https://open.spotify.com/track/TRACK_ID\" }`: register a site. Add `organizationId` only for a selected authorized workspace. Read the returned `site.id`. Omit owner/account ID fields; ownership comes from authentication.\n\n## Configure\n\n`GET /api/sites/{siteId}/fan-connection` returns:\n\n```json\n{\n \"siteId\": \"SITE_UUID\",\n \"ownerId\": \"WORKSPACE_ACCOUNT_UUID\",\n \"artistId\": \"ARTIST_ACCOUNT_UUID\",\n \"config\": null,\n \"connectUrl\": null\n}\n```\n\nExisting `config` contains `site_id`, `return_url`, `marketing_text`, `enabled` and `revision`. Update with `PUT /api/sites/{siteId}/fan-connection`:\n\n```json\n{\n \"returnUrl\": \"https://artist.example/release\",\n \"marketingText\": \"I agree to receive release announcements and offers by email from Example Artist.\",\n \"enabled\": true,\n \"revision\": 0\n}\n```\n\nUse the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public `connectUrl`; always use that returned URL.\n\n- 400: invalid input or missing artist attribution.\n- 401/403: reconnect the customer or select an authorized workspace.\n- 402: no eligible paid subscription for the site's owning account.\n- 404: missing site or API not deployed; inspect the actual response.\n- 409: another configuration update won; reload and reconcile before retry.\n- 503: provider, billing or storage unavailable; surface the dependency.\n\nSpotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing `POST /api/subscriptions/sessions` accepts `{plan: \"starter\" | \"pro\", successUrl, cancelUrl?}` and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature.\n\n## Public fan journey\n\n`GET /api/sites/public/{siteId}/spotify` displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's `/api/sites/spotify/callback`; Recoup then returns to the configured site URL with `recoup_spotify=connected`, `cancelled` or `failed`.\n\nOnly a successful provider exchange with `user-read-email` and `user-read-private` creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site.\n\n## Read fans\n\n`GET /api/sites/{siteId}/fans?offset=0&limit=50` (private):\n\n```json\n{\n \"fans\": [],\n \"total\": 0,\n \"offset\": 0,\n \"limit\": 50\n}\n```\n\nEach fan has `id`, `site_id`, `spotify_id`, `display_name`, `email`, first/last connection timestamps and nested `site_fan_connections` with `site_fan_permissions` and `site_fan_marketing_consents`. Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data.\n\nStarter Checkout can return HTTP 400 `starter_unavailable` when its price is not\nconfigured. Explain the unavailable option and use a configured plan; do not retry\nit as a transient provider failure.\n\n## Recoup operator setup\n\nOperators must apply `20260928010000_site_fan_connections.sql`, configure `SITES_SPOTIFY_CLIENT_ID`, register an HTTPS callback ending `/api/sites/spotify/callback`, set `SITES_FAN_SPOTIFY_REDIRECT_URI`. This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate.\n\n## Activity reporting\n\n`GET /api/sites/{siteId}/activity` returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. `POST /api/sites/public/{siteId}/activity` accepts `{id: EVENT_UUID, visitId: VISIT_UUID, event: \"visit\" | \"start\" | \"complete\" | \"replay\" | \"share\"}`. Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history.\n\nRecoup-hosted generated sites use the trusted host bridge: `window.recoup.track(event)` reports approved events; `window.recoup.join()` reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server.\n\n## Playback for Premium and Free listeners\n\nThe hosted player reads the connected Spotify profile's `product` field. Premium listeners use the Spotify Web Playback SDK. Free (`free` or `open`) listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording.\n\n`GET /api/sites/public/{siteId}` includes `playbackAudioUrl`, a fresh signed audio URL valid for one hour, or `null` when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans.\n\nFile playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable.\n","headings":[{"title":"Customer and site","id":"customer-and-site"},{"title":"Configure","id":"configure"},{"title":"Public fan journey","id":"public-fan-journey"},{"title":"Read fans","id":"read-fans"},{"title":"Recoup operator setup","id":"recoup-operator-setup"},{"title":"Activity reporting","id":"activity-reporting"},{"title":"Playback for Premium and Free listeners","id":"playback-for-premium-and-free-listeners"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Private calls use \", _jsx(_components.code, {\n children: \"x-api-key: $RECOUP_API_KEY\"\n }), \" (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"customer-and-site\",\n children: \"Customer and site\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n }), \": verify the current credential.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"email\\\": \\\"customer@example.com\\\" }\"\n }), \": request email verification.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"email\\\": \\\"customer@example.com\\\", \\\"code\\\": \\\"123456\\\" }\"\n }), \": receive \", _jsx(_components.code, {\n children: \"api_key\"\n }), \"; never echo it.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/artists\"\n }), \": inspect the caller's roster and choose the artist's account ID.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites\"\n }), \": inspect existing site records.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/sites\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"name\\\": \\\"Release experience\\\", \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\", \\\"releaseUrl\\\": \\\"https://open.spotify.com/track/TRACK_ID\\\" }\"\n }), \": register a site. Add \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" only for a selected authorized workspace. Read the returned \", _jsx(_components.code, {\n children: \"site.id\"\n }), \". Omit owner/account ID fields; ownership comes from authentication.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"configure\",\n children: \"Configure\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/fan-connection\"\n }), \" returns:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"siteId\\\": \\\"SITE_UUID\\\",\\n \\\"ownerId\\\": \\\"WORKSPACE_ACCOUNT_UUID\\\",\\n \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\",\\n \\\"config\\\": null,\\n \\\"connectUrl\\\": null\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Existing \", _jsx(_components.code, {\n children: \"config\"\n }), \" contains \", _jsx(_components.code, {\n children: \"site_id\"\n }), \", \", _jsx(_components.code, {\n children: \"return_url\"\n }), \", \", _jsx(_components.code, {\n children: \"marketing_text\"\n }), \", \", _jsx(_components.code, {\n children: \"enabled\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \". Update with \", _jsx(_components.code, {\n children: \"PUT /api/sites/{siteId}/fan-connection\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"returnUrl\\\": \\\"https://artist.example/release\\\",\\n \\\"marketingText\\\": \\\"I agree to receive release announcements and offers by email from Example Artist.\\\",\\n \\\"enabled\\\": true,\\n \\\"revision\\\": 0\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public \", _jsx(_components.code, {\n children: \"connectUrl\"\n }), \"; always use that returned URL.\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"400: invalid input or missing artist attribution.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"401/403: reconnect the customer or select an authorized workspace.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"402: no eligible paid subscription for the site's owning account.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"404: missing site or API not deployed; inspect the actual response.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"409: another configuration update won; reload and reconcile before retry.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"503: provider, billing or storage unavailable; surface the dependency.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Spotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing \", _jsx(_components.code, {\n children: \"POST /api/subscriptions/sessions\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{plan: \\\"starter\\\" | \\\"pro\\\", successUrl, cancelUrl?}\"\n }), \" and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"public-fan-journey\",\n children: \"Public fan journey\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{siteId}/spotify\"\n }), \" displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's \", _jsx(_components.code, {\n children: \"/api/sites/spotify/callback\"\n }), \"; Recoup then returns to the configured site URL with \", _jsx(_components.code, {\n children: \"recoup_spotify=connected\"\n }), \", \", _jsx(_components.code, {\n children: \"cancelled\"\n }), \" or \", _jsx(_components.code, {\n children: \"failed\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Only a successful provider exchange with \", _jsx(_components.code, {\n children: \"user-read-email\"\n }), \" and \", _jsx(_components.code, {\n children: \"user-read-private\"\n }), \" creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"read-fans\",\n children: \"Read fans\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/fans?offset=0&limit=50\"\n }), \" (private):\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"fans\\\": [],\\n \\\"total\\\": 0,\\n \\\"offset\\\": 0,\\n \\\"limit\\\": 50\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each fan has \", _jsx(_components.code, {\n children: \"id\"\n }), \", \", _jsx(_components.code, {\n children: \"site_id\"\n }), \", \", _jsx(_components.code, {\n children: \"spotify_id\"\n }), \", \", _jsx(_components.code, {\n children: \"display_name\"\n }), \", \", _jsx(_components.code, {\n children: \"email\"\n }), \", first/last connection timestamps and nested \", _jsx(_components.code, {\n children: \"site_fan_connections\"\n }), \" with \", _jsx(_components.code, {\n children: \"site_fan_permissions\"\n }), \" and \", _jsx(_components.code, {\n children: \"site_fan_marketing_consents\"\n }), \". Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Starter Checkout can return HTTP 400 \", _jsx(_components.code, {\n children: \"starter_unavailable\"\n }), \" when its price is not\\nconfigured. Explain the unavailable option and use a configured plan; do not retry\\nit as a transient provider failure.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"recoup-operator-setup\",\n children: \"Recoup operator setup\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Operators must apply \", _jsx(_components.code, {\n children: \"20260928010000_site_fan_connections.sql\"\n }), \", configure \", _jsx(_components.code, {\n children: \"SITES_SPOTIFY_CLIENT_ID\"\n }), \", register an HTTPS callback ending \", _jsx(_components.code, {\n children: \"/api/sites/spotify/callback\"\n }), \", set \", _jsx(_components.code, {\n children: \"SITES_FAN_SPOTIFY_REDIRECT_URI\"\n }), \". This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"activity-reporting\",\n children: \"Activity reporting\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/activity\"\n }), \" returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. \", _jsx(_components.code, {\n children: \"POST /api/sites/public/{siteId}/activity\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{id: EVENT_UUID, visitId: VISIT_UUID, event: \\\"visit\\\" | \\\"start\\\" | \\\"complete\\\" | \\\"replay\\\" | \\\"share\\\"}\"\n }), \". Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Recoup-hosted generated sites use the trusted host bridge: \", _jsx(_components.code, {\n children: \"window.recoup.track(event)\"\n }), \" reports approved events; \", _jsx(_components.code, {\n children: \"window.recoup.join()\"\n }), \" reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"playback-for-premium-and-free-listeners\",\n children: \"Playback for Premium and Free listeners\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The hosted player reads the connected Spotify profile's \", _jsx(_components.code, {\n children: \"product\"\n }), \" field. Premium listeners use the Spotify Web Playback SDK. Free (\", _jsx(_components.code, {\n children: \"free\"\n }), \" or \", _jsx(_components.code, {\n children: \"open\"\n }), \") listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{siteId}\"\n }), \" includes \", _jsx(_components.code, {\n children: \"playbackAudioUrl\"\n }), \", a fresh signed audio URL valid for one hour, or \", _jsx(_components.code, {\n children: \"null\"\n }), \" when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"File playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Connect Spotify fans to a site Configure paid fan connection from an artist agent and retrieve fans attributed to its site. Sites Sites Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: `https://api.recoupable.dev`. Private calls use `x-api-key: $RECOUP_API_KEY` (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key. ## Customer and site - `GET /api/accounts/id`: verify the current credential. - `POST /api/agents/signup` with `{ \"email\": \"customer@example.com\" }`: request email verification. - `POST /api/agents/verify` with `{ \"email\": \"customer@example.com\", \"code\": \"123456\" }`: receive `api_key`; never echo it. - `GET /api/artists`: inspect the caller's roster and choose the artist's account ID. - `GET /api/sites`: inspect existing site records. - `POST /api/sites` with `{ \"name\": \"Release experience\", \"artistId\": \"ARTIST_ACCOUNT_UUID\", \"releaseUrl\": \"https://open.spotify.com/track/TRACK_ID\" }`: register a site. Add `organizationId` only for a selected authorized workspace. Read the returned `site.id`. Omit owner/account ID fields; ownership comes from authentication. ## Configure `GET /api/sites/{siteId}/fan-connection` returns: Existing `config` contains `site_id`, `return_url`, `marketing_text`, `enabled` and `revision`. Update with `PUT /api/sites/{siteId}/fan-connection`: Use the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public `connectUrl`; always use that returned URL. - 400: invalid input or missing artist attribution. - 401/403: reconnect the customer or select an authorized workspace. - 402: no eligible paid subscription for the site's owning account. - 404: missing site or API not deployed; inspect the actual response. - 409: another configuration update won; reload and reconcile before retry. - 503: provider, billing or storage unavailable; surface the dependency. Spotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing `POST /api/subscriptions/sessions` accepts `{plan: \"starter\" | \"pro\", successUrl, cancelUrl?}` and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature. ## Public fan journey `GET /api/sites/public/{siteId}/spotify` displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's `/api/sites/spotify/callback`; Recoup then returns to the configured site URL with `recoup_spotify=connected`, `cancelled` or `failed`. Only a successful provider exchange with `user-read-email` and `user-read-private` creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site. ## Read fans `GET /api/sites/{siteId}/fans?offset=0&limit=50` (private): Each fan has `id`, `site_id`, `spotify_id`, `display_name`, `email`, first/last connection timestamps and nested `site_fan_connections` with `site_fan_permissions` and `site_fan_marketing_consents`. Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data. Starter Checkout can return HTTP 400 `starter_unavailable` when its price is not configured. Explain the unavailable option and use a configured plan; do not retry it as a transient provider failure. ## Recoup operator setup Operators must apply `20260928010000_site_fan_connections.sql`, configure `SITES_SPOTIFY_CLIENT_ID`, register an HTTPS callback ending `/api/sites/spotify/callback`, set `SITES_FAN_SPOTIFY_REDIRECT_URI`. This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate. ## Activity reporting `GET /api/sites/{siteId}/activity` returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. `POST /api/sites/public/{siteId}/activity` accepts `{id: EVENT_UUID, visitId: VISIT_UUID, event: \"visit\" | \"start\" | \"complete\" | \"replay\" | \"share\"}`. Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history. Recoup-hosted generated sites use the trusted host bridge: `window.recoup.track(event)` reports approved events; `window.recoup.join()` reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server. ## Playback for Premium and Free listeners The hosted player reads the connected Spotify profile's `product` field. Premium listeners use the Spotify Web Playback SDK. Free (`free` or `open`) listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording. `GET /api/sites/public/{siteId}` includes `playbackAudioUrl`, a fresh signed audio URL valid for one hour, or `null` when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans. File playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable. "},{"slug":"essentials/release-player","title":"One player for every release","description":"Create a listening page or embed Spotify and Apple Music playback on your artist website.","category":"Players","group":"Release players","source":"essentials/release-player.mdx","body":"Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.\n\n## Create and publish\n\nUse the [Recoup API](/api-reference/players/create) or the `create_release_player` MCP tool. Choose an artist you can access, name the player, and provide a `spotifyUrl`, an `appleUrl`, or both. Use `organizationId` to create it in your organization workspace.\n\nFor website embeds, add the exact website origins to `allowedOrigins`. An origin includes the scheme, hostname and any non-default port, such as `https://artist.example:8443`. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.\n\nExample create request:\n\n```json\n{\n \"artistId\": \"ARTIST_ACCOUNT_UUID\",\n \"organizationId\": \"ORGANIZATION_UUID\",\n \"name\": \"Release title\",\n \"spotifyUrl\": \"https://open.spotify.com/album/ALBUM_ID\",\n \"appleUrl\": \"https://music.apple.com/us/album/release/APPLE_ID\",\n \"allowedOrigins\": [\"https://artist.example\", \"https://www.artist.example\"]\n}\n```\n\nNew players start unpublished. Review the music links, then publish with `update_release_player`, passing `id`, the current `revision`, and `enabled: true`. Publishing requires an active paid Recoup workspace.\n\nUse the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.\n\nSee [update a release player](/api-reference/players/update) for the REST request and fields.\n\n## Share a listening page\n\nUse the returned `listenUrl` as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.\n\nTo track campaign traffic, add `source`, `medium`, `campaign`, and `content` query parameters. The listening page also accepts `utm_source`, `utm_medium`, `utm_campaign`, and `utm_content`. Use campaign labels, such as `instagram` and `release`; keep personal information out of links.\n\n## Embed on your website\n\nUse the returned `spotifyEmbedUrl` or `appleEmbedUrl` for each configured service. The `parent` parameter must match an approved website origin.\n\n```html\n\n```\n\nKeep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.\n\nFor Spotify Free handoffs, the embed sends a `recoup:open-dsp` message with `provider: \"spotify\"`. Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.\n\n## What fans can play\n\nSpotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.\n\nSpotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.\n\nApple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.\n\n## Optional uploaded audio for Spotify Free fans\n\nYou can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set `freePlayback: \"audio\"` and provide `audioUrl`. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.\n\nUpload an MP3 or WAV through `POST /api/sites/assets` in the same workspace, then use the returned `asset.url`. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.\n\nMCP arguments for `update_release_player`:\n\n```json\n{\n \"id\": \"PLAYER_UUID\",\n \"revision\": 1,\n \"freePlayback\": \"audio\",\n \"audioUrl\": \"WORKSPACE_UPLOADED_ASSET_URL\"\n}\n```\n\nFor REST, send `PATCH /api/players/PLAYER_UUID` with the same body except `id`; the player ID belongs in the URL.\n\nAudio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.\n\nTo restore the Spotify handoff, set `freePlayback: \"spotify\"`. You can also clear `audioUrl` by setting it to `null`.\n\n## Fan contacts belong to your workspace\n\nSpotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.\n\nIf that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.\n\n- Use `get_workspace_player_fans` or [read workspace player fans](/api-reference/players/workspace-fans) to list contacts and their artist relationships.\n- Use `get_release_player_fans` or [read artist player fans](/api-reference/players/fans) to list fan relationships across that artist's players in the workspace.\n\n`contact_id` identifies the workspace contact. Each artist relationship has its own `id`; activity records refer to that relationship as `fan_id`.\n\nSpotify sign-in does **not** grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.\n\n## Measure listening activity\n\nUse `get_release_player_activity` or [read listening activity](/api-reference/players/activity) for 30-day campaign totals and individual track, play, pause and skip events.\n\nThese reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are **not confirmed music-service stream counts** and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.\n\n## Check your fan journey\n\nBefore promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.\n","headings":[{"title":"Create and publish","id":"create-and-publish"},{"title":"Share a listening page","id":"share-a-listening-page"},{"title":"Embed on your website","id":"embed-on-your-website"},{"title":"What fans can play","id":"what-fans-can-play"},{"title":"Optional uploaded audio for Spotify Free fans","id":"optional-uploaded-audio-for-spotify-free-fans"},{"title":"Fan contacts belong to your workspace","id":"fan-contacts-belong-to-your-workspace"},{"title":"Measure listening activity","id":"measure-listening-activity"},{"title":"Check your fan journey","id":"check-your-fan-journey"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"create-and-publish\",\n children: \"Create and publish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the \", _jsx(_components.a, {\n href: \"/api-reference/players/create\",\n children: \"Recoup API\"\n }), \" or the \", _jsx(_components.code, {\n children: \"create_release_player\"\n }), \" MCP tool. Choose an artist you can access, name the player, and provide a \", _jsx(_components.code, {\n children: \"spotifyUrl\"\n }), \", an \", _jsx(_components.code, {\n children: \"appleUrl\"\n }), \", or both. Use \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" to create it in your organization workspace.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For website embeds, add the exact website origins to \", _jsx(_components.code, {\n children: \"allowedOrigins\"\n }), \". An origin includes the scheme, hostname and any non-default port, such as \", _jsx(_components.code, {\n children: \"https://artist.example:8443\"\n }), \". Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Example create request:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\",\\n \\\"organizationId\\\": \\\"ORGANIZATION_UUID\\\",\\n \\\"name\\\": \\\"Release title\\\",\\n \\\"spotifyUrl\\\": \\\"https://open.spotify.com/album/ALBUM_ID\\\",\\n \\\"appleUrl\\\": \\\"https://music.apple.com/us/album/release/APPLE_ID\\\",\\n \\\"allowedOrigins\\\": [\\\"https://artist.example\\\", \\\"https://www.artist.example\\\"]\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"New players start unpublished. Review the music links, then publish with \", _jsx(_components.code, {\n children: \"update_release_player\"\n }), \", passing \", _jsx(_components.code, {\n children: \"id\"\n }), \", the current \", _jsx(_components.code, {\n children: \"revision\"\n }), \", and \", _jsx(_components.code, {\n children: \"enabled: true\"\n }), \". Publishing requires an active paid Recoup workspace.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/players/update\",\n children: \"update a release player\"\n }), \" for the REST request and fields.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"share-a-listening-page\",\n children: \"Share a listening page\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the returned \", _jsx(_components.code, {\n children: \"listenUrl\"\n }), \" as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To track campaign traffic, add \", _jsx(_components.code, {\n children: \"source\"\n }), \", \", _jsx(_components.code, {\n children: \"medium\"\n }), \", \", _jsx(_components.code, {\n children: \"campaign\"\n }), \", and \", _jsx(_components.code, {\n children: \"content\"\n }), \" query parameters. The listening page also accepts \", _jsx(_components.code, {\n children: \"utm_source\"\n }), \", \", _jsx(_components.code, {\n children: \"utm_medium\"\n }), \", \", _jsx(_components.code, {\n children: \"utm_campaign\"\n }), \", and \", _jsx(_components.code, {\n children: \"utm_content\"\n }), \". Use campaign labels, such as \", _jsx(_components.code, {\n children: \"instagram\"\n }), \" and \", _jsx(_components.code, {\n children: \"release\"\n }), \"; keep personal information out of links.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"embed-on-your-website\",\n children: \"Embed on your website\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the returned \", _jsx(_components.code, {\n children: \"spotifyEmbedUrl\"\n }), \" or \", _jsx(_components.code, {\n children: \"appleEmbedUrl\"\n }), \" for each configured service. The \", _jsx(_components.code, {\n children: \"parent\"\n }), \" parameter must match an approved website origin.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-html\",\n children: \"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For Spotify Free handoffs, the embed sends a \", _jsx(_components.code, {\n children: \"recoup:open-dsp\"\n }), \" message with \", _jsx(_components.code, {\n children: \"provider: \\\"spotify\\\"\"\n }), \". Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-fans-can-play\",\n children: \"What fans can play\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"optional-uploaded-audio-for-spotify-free-fans\",\n children: \"Optional uploaded audio for Spotify Free fans\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set \", _jsx(_components.code, {\n children: \"freePlayback: \\\"audio\\\"\"\n }), \" and provide \", _jsx(_components.code, {\n children: \"audioUrl\"\n }), \". This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Upload an MP3 or WAV through \", _jsx(_components.code, {\n children: \"POST /api/sites/assets\"\n }), \" in the same workspace, then use the returned \", _jsx(_components.code, {\n children: \"asset.url\"\n }), \". The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP arguments for \", _jsx(_components.code, {\n children: \"update_release_player\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"id\\\": \\\"PLAYER_UUID\\\",\\n \\\"revision\\\": 1,\\n \\\"freePlayback\\\": \\\"audio\\\",\\n \\\"audioUrl\\\": \\\"WORKSPACE_UPLOADED_ASSET_URL\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For REST, send \", _jsx(_components.code, {\n children: \"PATCH /api/players/PLAYER_UUID\"\n }), \" with the same body except \", _jsx(_components.code, {\n children: \"id\"\n }), \"; the player ID belongs in the URL.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To restore the Spotify handoff, set \", _jsx(_components.code, {\n children: \"freePlayback: \\\"spotify\\\"\"\n }), \". You can also clear \", _jsx(_components.code, {\n children: \"audioUrl\"\n }), \" by setting it to \", _jsx(_components.code, {\n children: \"null\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"fan-contacts-belong-to-your-workspace\",\n children: \"Fan contacts belong to your workspace\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_workspace_player_fans\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/workspace-fans\",\n children: \"read workspace player fans\"\n }), \" to list contacts and their artist relationships.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_release_player_fans\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/fans\",\n children: \"read artist player fans\"\n }), \" to list fan relationships across that artist's players in the workspace.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"contact_id\"\n }), \" identifies the workspace contact. Each artist relationship has its own \", _jsx(_components.code, {\n children: \"id\"\n }), \"; activity records refer to that relationship as \", _jsx(_components.code, {\n children: \"fan_id\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Spotify sign-in does \", _jsx(_components.strong, {\n children: \"not\"\n }), \" grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"measure-listening-activity\",\n children: \"Measure listening activity\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_release_player_activity\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/activity\",\n children: \"read listening activity\"\n }), \" for 30-day campaign totals and individual track, play, pause and skip events.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are \", _jsx(_components.strong, {\n children: \"not confirmed music-service stream counts\"\n }), \" and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"check-your-fan-journey\",\n children: \"Check your fan journey\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"One player for every release Create a listening page or embed Spotify and Apple Music playback on your artist website. Players Release players Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting. ## Create and publish Use the [Recoup API](/api-reference/players/create) or the `create_release_player` MCP tool. Choose an artist you can access, name the player, and provide a `spotifyUrl`, an `appleUrl`, or both. Use `organizationId` to create it in your organization workspace. For website embeds, add the exact website origins to `allowedOrigins`. An origin includes the scheme, hostname and any non-default port, such as `https://artist.example:8443`. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page. Example create request: New players start unpublished. Review the music links, then publish with `update_release_player`, passing `id`, the current `revision`, and `enabled: true`. Publishing requires an active paid Recoup workspace. Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect. See [update a release player](/api-reference/players/update) for the REST request and fields. ## Share a listening page Use the returned `listenUrl` as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player. To track campaign traffic, add `source`, `medium`, `campaign`, and `content` query parameters. The listening page also accepts `utm_source`, `utm_medium`, `utm_campaign`, and `utm_content`. Use campaign labels, such as `instagram` and `release`; keep personal information out of links. ## Embed on your website Use the returned `spotifyEmbedUrl` or `appleEmbedUrl` for each configured service. The `parent` parameter must match an approved website origin. Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable. For Spotify Free handoffs, the embed sends a `recoup:open-dsp` message with `provider: \"spotify\"`. Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message. ## What fans can play Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify. Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free. Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup. ## Optional uploaded audio for Spotify Free fans You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set `freePlayback: \"audio\"` and provide `audioUrl`. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify. Upload an MP3 or WAV through `POST /api/sites/assets` in the same workspace, then use the returned `asset.url`. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback. MCP arguments for `update_release_player`: For REST, send `PATCH /api/players/PLAYER_UUID` with the same body except `id`; the player ID belongs in the URL. Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link. To restore the Spotify handoff, set `freePlayback: \"spotify\"`. You can also clear `audioUrl` by setting it to `null`. ## Fan contacts belong to your workspace Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace. If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans. - Use `get_workspace_player_fans` or [read workspace player fans](/api-reference/players/workspace-fans) to list contacts and their artist relationships. - Use `get_release_player_fans` or [read artist player fans](/api-reference/players/fans) to list fan relationships across that artist's players in the workspace. `contact_id` identifies the workspace contact. Each artist relationship has its own `id`; activity records refer to that relationship as `fan_id`. Spotify sign-in does **not** grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts. ## Measure listening activity Use `get_release_player_activity` or [read listening activity](/api-reference/players/activity) for 30-day campaign totals and individual track, play, pause and skip events. These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are **not confirmed music-service stream counts** and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance. ## Check your fan journey Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace. "},{"slug":"api-reference/players/create","title":"Create a release player","description":"Create a release player","category":"Players","group":"Release players","source":"api-reference/players/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/players","spec":"players.json"},"searchText":"Create a release player Create a release player Players Release players POST /api/players "},{"slug":"api-reference/players/list","title":"List release players","description":"List release players","category":"Players","group":"Release players","source":"api-reference/players/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players","spec":"players.json"},"searchText":"List release players List release players Players Release players GET /api/players "},{"slug":"api-reference/players/get","title":"Read a release player","description":"Read a release player","category":"Players","group":"Release players","source":"api-reference/players/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}","spec":"players.json"},"searchText":"Read a release player Read a release player Players Release players GET /api/players/{id} "},{"slug":"api-reference/players/update","title":"Update a release player","description":"Update a release player","category":"Players","group":"Release players","source":"api-reference/players/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/players/{id}","spec":"players.json"},"searchText":"Update a release player Update a release player Players Release players PATCH /api/players/{id} "},{"slug":"api-reference/players/activity","title":"Read listening activity","description":"Read player listening activity","category":"Players","group":"Release players","source":"api-reference/players/activity.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}/activity","spec":"players.json"},"searchText":"Read listening activity Read player listening activity Players Release players GET /api/players/{id}/activity "},{"slug":"api-reference/players/fans","title":"Read artist player fans","description":"Read artist player fans","category":"Players","group":"Release players","source":"api-reference/players/fans.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}/fans","spec":"players.json"},"searchText":"Read artist player fans Read artist player fans Players Release players GET /api/players/{id}/fans "},{"slug":"api-reference/players/workspace-fans","title":"Read workspace player fans","description":"Read workspace player fans","category":"Players","group":"Release players","source":"api-reference/players/workspace-fans.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/fans","spec":"players.json"},"searchText":"Read workspace player fans Read workspace player fans Players Release players GET /api/players/fans "},{"slug":"api-reference/complete/content/post-content-packs","title":"POST /api/content/packs","description":"Release rollout pending; discover current host capabilities before execution. Prepare a resumable pack brief. No artist profile or GitHub repository required; no paid generation.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs","spec":"content.json"},"searchText":"POST /api/content/packs Release rollout pending; discover current host capabilities before execution. Prepare a resumable pack brief. No artist profile or GitHub repository required; no paid generation."},{"slug":"api-reference/complete/content/get-content-packs-id","title":"GET /api/content/packs/{id}","description":"Release rollout pending; discover current host capabilities before execution. Read current owned job, assets, gaps and next action.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"GET","path":"/api/content/packs/{id}","spec":"content.json"},"searchText":"GET /api/content/packs/{id} Release rollout pending; discover current host capabilities before execution. Read current owned job, assets, gaps and next action."},{"slug":"api-reference/complete/content/patch-content-packs-id","title":"PATCH /api/content/packs/{id}","description":"Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"PATCH","path":"/api/content/packs/{id}","spec":"content.json"},"searchText":"PATCH /api/content/packs/{id} Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes."},{"slug":"api-reference/complete/content/post-content-packs-id-estimate","title":"POST /api/content/packs/{id}/estimate","description":"Release rollout pending; discover current host capabilities before execution. Quote complete scope at existing house image/video rates. Caption, inspection and composition are included at no additional customer charge.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/estimate","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/estimate Release rollout pending; discover current host capabilities before execution. Quote complete scope at existing house image/video rates. Caption, inspection and composition are included at no additional customer charge."},{"slug":"api-reference/complete/content/post-content-packs-id-generate","title":"POST /api/content/packs/{id}/generate","description":"Release rollout pending; discover current host capabilities before execution. Approve the current quote and budget ceiling. Start or resume the same job without duplicate submission.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/generate","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/generate Release rollout pending; discover current host capabilities before execution. Approve the current quote and budget ceiling. Start or resume the same job without duplicate submission."},{"slug":"api-reference/complete/content/post-content-packs-id-retry","title":"POST /api/content/packs/{id}/retry","description":"Release rollout pending; discover current host capabilities before execution. Retry only the selected failed asset within approved scope and ceiling; retain successful work.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/retry","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/retry Release rollout pending; discover current host capabilities before execution. Retry only the selected failed asset within approved scope and ceiling; retain successful work."},{"slug":"api-reference/complete/content/post-content-packs-assets","title":"POST /api/content/packs/assets","description":"Release rollout pending; discover current host capabilities before execution. Upload explicitly selected audio or reference artwork to owned private storage; return a temporary locator.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/assets","spec":"content.json"},"searchText":"POST /api/content/packs/assets Release rollout pending; discover current host capabilities before execution. Upload explicitly selected audio or reference artwork to owned private storage; return a temporary locator."},{"slug":"api-reference/complete/content/get-content-packs-id-export","title":"GET /api/content/packs/{id}/export","description":"Release rollout pending; discover current host capabilities before execution. Retrieve an authenticated JSON manifest with captions, gaps and refreshed signed file URLs. Does not publish.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"GET","path":"/api/content/packs/{id}/export","spec":"content.json"},"searchText":"GET /api/content/packs/{id}/export Release rollout pending; discover current host capabilities before execution. Retrieve an authenticated JSON manifest with captions, gaps and refreshed signed file URLs. Does not publish."},{"slug":"api-reference/complete/players/get-players-public-id","title":"Read public player metadata without creating a session","description":"Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"GET","path":"/api/players/public/{id}","spec":"players.json"},"searchText":"GET /api/players/public/{id} Read public player metadata without creating a session Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials."},{"slug":"api-reference/complete/players/post-players-events","title":"Record reported listening","description":"Internal trusted Recoup player transport. Requires its Origin plus signed flow; browser-facing same-origin app proxy forwards to API. Provider and fan attribution come from the stored session. Event UUID makes retries idempotent, listenedMs is capped at 30 seconds and checked against elapsed server time. Recording failures do not stop music.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/events","spec":"players.json"},"searchText":"POST /api/players/events Record reported listening Internal trusted Recoup player transport. Requires its Origin plus signed flow; browser-facing same-origin app proxy forwards to API. Provider and fan attribution come from the stored session. Event UUID makes retries idempotent, listenedMs is capped at 30 seconds and checked against elapsed server time. Recording failures do not stop music."},{"slug":"api-reference/complete/players/post-players-spotify-session","title":"Exchange player Spotify authorization","description":"Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/spotify/session","spec":"players.json"},"searchText":"POST /api/players/spotify/session Exchange player Spotify authorization Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent."},{"slug":"api-reference/complete/players/post-players-public-id-session","title":"Acquire or resume a registered player session","description":"Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/public/{id}/session","spec":"players.json"},"searchText":"POST /api/players/public/{id}/session Acquire or resume a registered player session Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials."}] \ No newline at end of file +[{"slug":"","title":"Recoup API Documentation","description":"Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints.","category":"Quickstart","group":"Getting started","source":"index.mdx","body":"These guides cover the authenticated music-platform API. For anonymous search,\nreading, and website tools, use the separate [public website API](/public-website-api)\nand its [OpenAPI specification](https://recoupable.dev/openapi.json).\n\n## Connect your account\n\nFor an AI host, start with [MCP OAuth](/mcp-oauth): sign in to your real account,\napprove the intended scope and verify access with a read. For REST integrations,\ncreate an API key in your [account settings](https://chat.recoupable.dev/keys), or\nfollow the [verified email/PIN flow](/agents). Keep credentials in a secret facility.\nAn empty roster can be valid; do not create a disposable account to recover access.\n\n## What is Recoup?\n\nRecoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.\n\nThis is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.\n\n## Platform base URL\n\nPlatform API requests should be made to:\n\n```bash\nhttps://api.recoupable.dev/api\n```\n\n## Authentication\n\nMost API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key.\n\n1. Navigate to the [API Keys Management Page](https://chat.recoupable.dev/keys)\n2. Sign in with your account\n3. Create a new API key and copy it immediately (it's only shown once)\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/artists?accountId=YOUR_ACCOUNT_ID\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n\nKeep your API key secure. Do not share it publicly or commit it to version control.\n\n\n## Get Started\n\n\n \n Verify your email and obtain a separate REST API key.\n \n \n Get your API key and make your first request in minutes.\n \n \n Install and use the Recoup CLI to interact with the platform from your terminal.\n \n \n Connect Claude to Recoup through MCP OAuth, then add optional workflow skills.\n \n \n Connect Recoup to AI assistants via the Model Context Protocol.\n \n\n\n## API Sections\n\nThe API includes these major sections. Use these links to jump to the right area.\n\n\n \n Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements.\n \n \n Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.\n \n \n Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.\n \n \n Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.\n \n \n Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.\n \n \n Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools.\n \n \n Hosted listening pages, embeddable players, event reporting and fan connections.\n \n\n\n## Agents\n\n\n \n Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.\n \n \n API key authentication, account-scoped access, and organization-level permissions.\n \n\n\n## Quick Reference for LLMs\n\nIf you are an LLM navigating these docs, here is a summary of the endpoint structure:\n\n- **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile)\n- **`/api/research/*`** — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits.\n- **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)\n- **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact)\n- **Songs and catalogs** — Read songs with `/api/songs`; import songs into an accessible catalog with `/api/catalogs/songs`. Analysis, catalog management and catalog-song reads/deletes have their own references. [Standalone song creation is not available](/api-reference/songs/create).\n- **`/api/tasks/*`** — Task automation (get, create, update, delete, runs)\n- **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album)\n- **`/api/instagram/*`** — Instagram (comments, profiles)\n- **`/api/x/*`** — X/Twitter (search, trends)\n- **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect)\n- **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist)\n- **`/api/organizations/*`** — Organizations (list, create, add-artist)\n- **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload)\n- **`/api/players/*`** — Release Players (list, create, update, activity and fans)\n- **`/api/content-agent/*`** — Content agent webhooks (webhook, callback)\n- **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required\n\nBase URL: `https://api.recoupable.dev/api`\n\n[OpenAPI Specification](https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi)\n\n## Need Help?\n\n\n Reach out to our team at agent@recoupable.dev for assistance with the Recoup API.\n\n","headings":[{"title":"Connect your account","id":"connect-your-account"},{"title":"What is Recoup?","id":"what-is-recoup"},{"title":"Platform base URL","id":"platform-base-url"},{"title":"Authentication","id":"authentication"},{"title":"Get Started","id":"get-started"},{"title":"API Sections","id":"api-sections"},{"title":"Agents","id":"agents"},{"title":"Quick Reference for LLMs","id":"quick-reference-for-llms"},{"title":"Need Help?","id":"need-help"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n }, {Card, CardGroup, Warning} = _components;\n if (!Card) _missingMdxReference(\"Card\", true);\n if (!CardGroup) _missingMdxReference(\"CardGroup\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"These guides cover the authenticated music-platform API. For anonymous search,\\nreading, and website tools, use the separate \", _jsx(_components.a, {\n href: \"/public-website-api\",\n children: \"public website API\"\n }), \"\\nand its \", _jsx(_components.a, {\n href: \"https://recoupable.dev/openapi.json\",\n children: \"OpenAPI specification\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"connect-your-account\",\n children: \"Connect your account\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For an AI host, start with \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \": sign in to your real account,\\napprove the intended scope and verify access with a read. For REST integrations,\\ncreate an API key in your \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"account settings\"\n }), \", or\\nfollow the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"verified email/PIN flow\"\n }), \". Keep credentials in a secret facility.\\nAn empty roster can be valid; do not create a disposable account to recover access.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-is-recoup\",\n children: \"What is Recoup?\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"platform-base-url\",\n children: \"Platform base URL\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Platform API requests should be made to:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"https://api.recoupable.dev/api\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication\",\n children: \"Authentication\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Most API endpoints are authenticated using an API key passed in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header. The only exceptions are the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"agent onboarding\"\n }), \" endpoints — \", _jsx(_components.a, {\n href: \"/api-reference/agents/signup\",\n children: _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/agents/verify\",\n children: _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n })\n }), \" — which are intentionally unauthenticated so agents can obtain their first API key.\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys Management Page\"\n })]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Sign in with your account\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Create a new API key and copy it immediately (it's only shown once)\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/artists?accountId=YOUR_ACCOUNT_ID\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Keep your API key secure. Do not share it publicly or commit it to version control.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"get-started\",\n children: \"Get Started\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Agent Signup\",\n icon: \"user-plus\",\n href: \"/agents\",\n children: _jsx(_components.p, {\n children: \"Verify your email and obtain a separate REST API key.\"\n })\n }), _jsx(Card, {\n title: \"Quickstart\",\n icon: \"rocket\",\n href: \"/quickstart\",\n children: _jsx(_components.p, {\n children: \"Get your API key and make your first request in minutes.\"\n })\n }), _jsx(Card, {\n title: \"CLI\",\n icon: \"terminal\",\n href: \"/cli\",\n children: _jsx(_components.p, {\n children: \"Install and use the Recoup CLI to interact with the platform from your terminal.\"\n })\n }), _jsx(Card, {\n title: \"Claude\",\n icon: \"sparkles\",\n href: \"/claude\",\n children: _jsx(_components.p, {\n children: \"Connect Claude to Recoup through MCP OAuth, then add optional workflow skills.\"\n })\n }), _jsx(Card, {\n title: \"MCP Server\",\n icon: \"plug\",\n href: \"/mcp\",\n children: _jsx(_components.p, {\n children: \"Connect Recoup to AI assistants via the Model Context Protocol.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"api-sections\",\n children: \"API Sections\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The API includes these major sections. Use these links to jump to the right area.\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Research\",\n icon: \"magnifying-glass-chart\",\n href: \"/api-reference/research/search\",\n children: _jsx(_components.p, {\n children: \"Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements.\"\n })\n }), _jsx(Card, {\n title: \"Content Creation\",\n icon: \"wand-magic-sparkles\",\n href: \"/api-reference/content/create\",\n children: _jsx(_components.p, {\n children: \"Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.\"\n })\n }), _jsx(Card, {\n title: \"Chat\",\n icon: \"comments\",\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.p, {\n children: \"Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.\"\n })\n }), _jsx(Card, {\n title: \"Social Media\",\n icon: \"share-nodes\",\n href: \"/api-reference/connectors/list\",\n children: _jsx(_components.p, {\n children: \"Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.\"\n })\n }), _jsx(Card, {\n title: \"Releases\",\n icon: \"music\",\n href: \"/api-reference/songs/songs\",\n children: _jsx(_components.p, {\n children: \"Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.\"\n })\n }), _jsx(Card, {\n title: \"Accounts\",\n icon: \"building\",\n href: \"/api-reference/pulses/update\",\n children: _jsx(_components.p, {\n children: \"Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools.\"\n })\n }), _jsx(Card, {\n title: \"Release Players\",\n icon: \"play\",\n href: \"/essentials/release-player\",\n children: _jsx(_components.p, {\n children: \"Hosted listening pages, embeddable players, event reporting and fan connections.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"agents\",\n children: \"Agents\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Content Agent\",\n icon: \"robot\",\n href: \"/content-agent\",\n children: _jsx(_components.p, {\n children: \"Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.\"\n })\n }), _jsx(Card, {\n title: \"Authentication\",\n icon: \"key\",\n href: \"/authentication\",\n children: _jsx(_components.p, {\n children: \"API key authentication, account-scoped access, and organization-level permissions.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"quick-reference-for-llms\",\n children: \"Quick Reference for LLMs\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you are an LLM navigating these docs, here is a summary of the endpoint structure:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/artists/*\"\n })\n }), \" — Artist management (list, create, socials, socials-scrape, profile)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/research/*\"\n })\n }), \" — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/content/*\"\n })\n }), \" — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/chat/*\"\n })\n }), \" — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Songs and catalogs\"\n }), \" — Read songs with \", _jsx(_components.code, {\n children: \"/api/songs\"\n }), \"; import songs into an accessible catalog with \", _jsx(_components.code, {\n children: \"/api/catalogs/songs\"\n }), \". Analysis, catalog management and catalog-song reads/deletes have their own references. \", _jsx(_components.a, {\n href: \"/api-reference/songs/create\",\n children: \"Standalone song creation is not available\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/tasks/*\"\n })\n }), \" — Task automation (get, create, update, delete, runs)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/spotify/*\"\n })\n }), \" — Spotify (search, artist, artist-albums, artist-top-tracks, album)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/instagram/*\"\n })\n }), \" — Instagram (comments, profiles)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/x/*\"\n })\n }), \" — X/Twitter (search, trends)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/connectors/*\"\n })\n }), \" — OAuth connectors (list, authorize, disconnect)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/accounts/*\"\n })\n }), \" — Accounts (get, id, create, update, add-artist)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/organizations/*\"\n })\n }), \" — Organizations (list, create, add-artist)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/sandboxes/*\"\n })\n }), \" — Sandboxes (list, create, snapshot, delete, setup, file, upload)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/players/*\"\n })\n }), \" — Release Players (list, create, update, activity and fans)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/content-agent/*\"\n })\n }), \" — Content agent webhooks (webhook, callback)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"/api/agents/*\"\n })\n }), \" — Agent onboarding (signup, verify) — no auth required\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Base URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/api\"\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi\",\n children: \"OpenAPI Specification\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"need-help\",\n children: \"Need Help?\"\n }), \"\\n\", _jsx(Card, {\n title: \"Contact Support\",\n icon: \"envelope\",\n href: \"mailto:agent@recoupable.dev\",\n children: _jsxs(_components.p, {\n children: [\"Reach out to our team at \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \" for assistance with the Recoup API.\"]\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Recoup API Documentation Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints. Quickstart Getting started These guides cover the authenticated music-platform API. For anonymous search, reading, and website tools, use the separate [public website API](/public-website-api) and its [OpenAPI specification](https://recoupable.dev/openapi.json). ## Connect your account For an AI host, start with [MCP OAuth](/mcp-oauth): sign in to your real account, approve the intended scope and verify access with a read. For REST integrations, create an API key in your [account settings](https://chat.recoupable.dev/keys), or follow the [verified email/PIN flow](/agents). Keep credentials in a secret facility. An empty roster can be valid; do not create a disposable account to recover access. ## What is Recoup? Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools. This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. ## Platform base URL Platform API requests should be made to: ## Authentication Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key. 1. Navigate to the [API Keys Management Page](https://chat.recoupable.dev/keys) 2. Sign in with your account 3. Create a new API key and copy it immediately (it's only shown once) Keep your API key secure. Do not share it publicly or commit it to version control. ## Get Started Verify your email and obtain a separate REST API key. Get your API key and make your first request in minutes. Install and use the Recoup CLI to interact with the platform from your terminal. Connect Claude to Recoup through MCP OAuth, then add optional workflow skills. Connect Recoup to AI assistants via the Model Context Protocol. ## API Sections The API includes these major sections. Use these links to jump to the right area. Recoup artist and track discovery, current metrics, activities and playlists; web research, upcoming events, and stored play-count measurements. Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs. Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history. Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors. Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation. Accounts, organizations, subscriptions, pulses, notifications, sandboxes, and admin tools. Hosted listening pages, embeddable players, event reporting and fan connections. ## Agents Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically. API key authentication, account-scoped access, and organization-level permissions. ## Quick Reference for LLMs If you are an LLM navigating these docs, here is a summary of the endpoint structure: - **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile) - **`/api/research/*`** — Artist and track search, lookup, profile, current metrics, audience, related artists, URLs, playlists, catalog entries and activities; track statistics and measurements; web, deep and people research, extraction, enrichment and events. See each operation's contract for provider mapping and coverage limits. - **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate) - **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact) - **Songs and catalogs** — Read songs with `/api/songs`; import songs into an accessible catalog with `/api/catalogs/songs`. Analysis, catalog management and catalog-song reads/deletes have their own references. [Standalone song creation is not available](/api-reference/songs/create). - **`/api/tasks/*`** — Task automation (get, create, update, delete, runs) - **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album) - **`/api/instagram/*`** — Instagram (comments, profiles) - **`/api/x/*`** — X/Twitter (search, trends) - **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect) - **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist) - **`/api/organizations/*`** — Organizations (list, create, add-artist) - **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload) - **`/api/players/*`** — Release Players (list, create, update, activity and fans) - **`/api/content-agent/*`** — Content agent webhooks (webhook, callback) - **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required Base URL: `https://api.recoupable.dev/api` [OpenAPI Specification](https://github.com/recoupable/marketing/tree/main/content/docs/source/api-reference/openapi) ## Need Help? Reach out to our team at agent@recoupable.dev for assistance with the Recoup API. "},{"slug":"quickstart","title":"Quickstart","description":"Connect your real account and make your first authenticated request.","category":"Quickstart","group":"Getting started","source":"quickstart.mdx","body":"## Connect first\n\nUse [MCP OAuth](/mcp-oauth) for a supported AI host. For the REST examples below,\ncreate a personal API key in [account settings](https://chat.recoupable.dev/keys)\nor follow the [Agents email verification guide](/agents). Store the key as\n`RECOUP_API_KEY` through your secret facility or an approved environment file.\nNever paste credentials into agent instructions or create a disposable account\nto access an existing customer's data.\n\nVerify the REST credential before continuing:\n\n```bash\ncurl --fail-with-body -sS -H \"x-api-key: $RECOUP_API_KEY\" \\\n https://api.recoupable.dev/api/accounts/id\n```\n\n## Base URL\n\nFor a language client, use the [Recoup SDK guide](/sdks). It includes the\npublished Go package, Python source installation, and the Node CLI.\n\nAll API requests should be made to:\n\n```bash\nhttps://api.recoupable.dev/api\n```\n\n## Your First Request\n\nOnce you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks:\n\n\n\n```bash cURL\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n```python Python\nimport requests\n\nheaders = {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\"\n}\n\nresponse = requests.get(\n \"https://api.recoupable.dev/api/tasks\",\n headers=headers\n)\nprint(response.json())\n```\n\n```javascript JavaScript\nconst response = await fetch(\"https://api.recoupable.dev/api/tasks\", {\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\",\n },\n});\nconst data = await response.json();\nconsole.log(data);\n```\n\n```typescript TypeScript\ninterface Task {\n id: string;\n title: string;\n prompt: string;\n schedule: string;\n account_id: string;\n artist_account_id: string;\n enabled: boolean;\n}\n\ninterface TasksResponse {\n status: \"success\" | \"error\";\n tasks: Task[];\n}\n\nconst response = await fetch(\"https://api.recoupable.dev/api/tasks\", {\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\",\n },\n});\nconst data: TasksResponse = await response.json();\nconsole.log(data.tasks);\n```\n\n\n\n**Example Response:**\n\n```json\n{\n \"status\": \"success\",\n \"tasks\": [\n {\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"title\": \"Daily Fan Report\",\n \"prompt\": \"Generate a summary of new fans from the past 24 hours\",\n \"schedule\": \"0 9 * * *\",\n \"account_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"artist_account_id\": \"987fcdeb-51a2-3b4c-d5e6-789012345678\",\n \"enabled\": true\n }\n ]\n}\n```\n\n\nFor full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get).\n\n\n## Prefer the dashboard?\n\nIf you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:\n\n1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.dev/keys)\n2. Sign in with your account\n3. Enter a descriptive name (e.g. \"Production Server\")\n4. Click **Create API Key**\n\n\nCopy and securely store your API key immediately — it will only be shown once.\n\n\n## Next Steps\n\nWith your API key ready, you can now:\n\n\n \n Fetch artists' social accounts and follower counts.\n \n \n Access fan data across all connected social platforms.\n \n \n Build AI-powered conversations with artist context.\n \n \n Schedule and automate recurring tasks.\n \n\n\n## Support\n\nIf you need help or have questions about the API, please contact our support team at [agent@recoupable.dev](mailto:agent@recoupable.dev).\n","headings":[{"title":"Connect first","id":"connect-first"},{"title":"Base URL","id":"base-url"},{"title":"Your First Request","id":"your-first-request"},{"title":"Prefer the dashboard?","id":"prefer-the-dashboard"},{"title":"Next Steps","id":"next-steps"},{"title":"Support","id":"support"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ...props.components\n }, {Card, CardGroup, CodeGroup, Info, Warning} = _components;\n if (!Card) _missingMdxReference(\"Card\", true);\n if (!CardGroup) _missingMdxReference(\"CardGroup\", true);\n if (!CodeGroup) _missingMdxReference(\"CodeGroup\", true);\n if (!Info) _missingMdxReference(\"Info\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"connect-first\",\n children: \"Connect first\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for a supported AI host. For the REST examples below,\\ncreate a personal API key in \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"account settings\"\n }), \"\\nor follow the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents email verification guide\"\n }), \". Store the key as\\n\", _jsx(_components.code, {\n children: \"RECOUP_API_KEY\"\n }), \" through your secret facility or an approved environment file.\\nNever paste credentials into agent instructions or create a disposable account\\nto access an existing customer's data.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Verify the REST credential before continuing:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl --fail-with-body -sS -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n https://api.recoupable.dev/api/accounts/id\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"base-url\",\n children: \"Base URL\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a language client, use the \", _jsx(_components.a, {\n href: \"/sdks\",\n children: \"Recoup SDK guide\"\n }), \". It includes the\\npublished Go package, Python source installation, and the Node CLI.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"All API requests should be made to:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"https://api.recoupable.dev/api\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"your-first-request\",\n children: \"Your First Request\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once you have an API key, include it in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header on every request. Here's a simple call that retrieves your scheduled tasks:\"]\n }), \"\\n\", _jsxs(CodeGroup, {\n children: [_jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-python\",\n children: \"import requests\\n\\nheaders = {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\"\\n}\\n\\nresponse = requests.get(\\n \\\"https://api.recoupable.dev/api/tasks\\\",\\n headers=headers\\n)\\nprint(response.json())\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-javascript\",\n children: \"const response = await fetch(\\\"https://api.recoupable.dev/api/tasks\\\", {\\n headers: {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\",\\n },\\n});\\nconst data = await response.json();\\nconsole.log(data);\\n\"\n })\n }), _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-typescript\",\n children: \"interface Task {\\n id: string;\\n title: string;\\n prompt: string;\\n schedule: string;\\n account_id: string;\\n artist_account_id: string;\\n enabled: boolean;\\n}\\n\\ninterface TasksResponse {\\n status: \\\"success\\\" | \\\"error\\\";\\n tasks: Task[];\\n}\\n\\nconst response = await fetch(\\\"https://api.recoupable.dev/api/tasks\\\", {\\n headers: {\\n \\\"Content-Type\\\": \\\"application/json\\\",\\n \\\"x-api-key\\\": \\\"YOUR_API_KEY\\\",\\n },\\n});\\nconst data: TasksResponse = await response.json();\\nconsole.log(data.tasks);\\n\"\n })\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"Example Response:\"\n })\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"status\\\": \\\"success\\\",\\n \\\"tasks\\\": [\\n {\\n \\\"id\\\": \\\"550e8400-e29b-41d4-a716-446655440000\\\",\\n \\\"title\\\": \\\"Daily Fan Report\\\",\\n \\\"prompt\\\": \\\"Generate a summary of new fans from the past 24 hours\\\",\\n \\\"schedule\\\": \\\"0 9 * * *\\\",\\n \\\"account_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\\n \\\"artist_account_id\\\": \\\"987fcdeb-51a2-3b4c-d5e6-789012345678\\\",\\n \\\"enabled\\\": true\\n }\\n ]\\n}\\n\"\n })\n }), \"\\n\", _jsx(Info, {\n children: _jsxs(_components.p, {\n children: [\"For full documentation on the Tasks API including filtering options, see the \", _jsx(_components.a, {\n href: \"/api-reference/tasks/get\",\n children: \"Tasks API Reference\"\n }), \".\"]\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"prefer-the-dashboard\",\n children: \"Prefer the dashboard?\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"Recoup API Keys Management Page\"\n })]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Sign in with your account\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Enter a descriptive name (e.g. \\\"Production Server\\\")\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Click \", _jsx(_components.strong, {\n children: \"Create API Key\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Copy and securely store your API key immediately — it will only be shown once.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"next-steps\",\n children: \"Next Steps\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"With your API key ready, you can now:\"\n }), \"\\n\", _jsxs(CardGroup, {\n cols: \"2\",\n children: [_jsx(Card, {\n title: \"Artist Data\",\n icon: \"user\",\n href: \"/api-reference/artists/socials\",\n children: _jsx(_components.p, {\n children: \"Fetch artists' social accounts and follower counts.\"\n })\n }), _jsx(Card, {\n title: \"Fan Analytics\",\n icon: \"users\",\n href: \"/api-reference/fans/get\",\n children: _jsx(_components.p, {\n children: \"Access fan data across all connected social platforms.\"\n })\n }), _jsx(Card, {\n title: \"Chat API\",\n icon: \"comments\",\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.p, {\n children: \"Build AI-powered conversations with artist context.\"\n })\n }), _jsx(Card, {\n title: \"Task Management\",\n icon: \"list-check\",\n href: \"/api-reference/tasks/get\",\n children: _jsx(_components.p, {\n children: \"Schedule and automate recurring tasks.\"\n })\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"support\",\n children: \"Support\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you need help or have questions about the API, please contact our support team at \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Quickstart Connect your real account and make your first authenticated request. Quickstart Getting started ## Connect first Use [MCP OAuth](/mcp-oauth) for a supported AI host. For the REST examples below, create a personal API key in [account settings](https://chat.recoupable.dev/keys) or follow the [Agents email verification guide](/agents). Store the key as `RECOUP_API_KEY` through your secret facility or an approved environment file. Never paste credentials into agent instructions or create a disposable account to access an existing customer's data. Verify the REST credential before continuing: ## Base URL For a language client, use the [Recoup SDK guide](/sdks). It includes the published Go package, Python source installation, and the Node CLI. All API requests should be made to: ## Your First Request Once you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks: **Example Response:** For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). ## Prefer the dashboard? If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint: 1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.dev/keys) 2. Sign in with your account 3. Enter a descriptive name (e.g. \"Production Server\") 4. Click **Create API Key** Copy and securely store your API key immediately — it will only be shown once. ## Next Steps With your API key ready, you can now: Fetch artists' social accounts and follower counts. Access fan data across all connected social platforms. Build AI-powered conversations with artist context. Schedule and automate recurring tasks. ## Support If you need help or have questions about the API, please contact our support team at [agent@recoupable.dev](mailto:agent@recoupable.dev). "},{"slug":"sdks","title":"Recoup SDKs: Go and Python clients for the music API","description":"Install the official Recoup Python SDK from PyPI, the Go SDK from its module registry, and the Node CLI from npm. Includes authentication, response handling, and package links.","category":"Quickstart","group":"Getting started","source":"sdks.mdx","body":"Use the official Recoup clients to call the platform's JSON API from your application.\nBoth SDKs support an API key or an existing Bearer token, bounded responses,\nstructured HTTP errors, and an account-identity helper. Their licenses are MIT.\n\n## Packages\n\n| Language | Package | Availability |\n| --- | --- | --- |\n| Go 1.23+ | [github.com/recoupable/marketing/sdk/go](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) | Version `v0.1.0` is published and indexed. |\n| Python 3.10+ | [recoupable on PyPI](https://pypi.org/project/recoupable/0.1.0/) | Version `0.1.0` is published. |\n| Node.js CLI | [@recoupable/cli on npm](https://www.npmjs.com/package/@recoupable/cli) | The terminal client is published. See the [CLI guide](/cli) for supported commands. |\n\nThe Go and Python SDKs handle JSON endpoints. They do not implement streaming,\nmultipart uploads, OAuth login, automatic pagination, or generated methods for\nevery endpoint. Use each endpoint's reference to check its availability, required\npermissions, request shape, and response type. A package installation does not\ngrant account access.\n\n## Go\n\nInstall the published version:\n\n```sh\ngo get github.com/recoupable/marketing/sdk/go@v0.1.0\n```\n\nRead an existing API key from your application's secret environment:\n\n```go\npackage main\n\nimport (\n \"context\"\n \"log\"\n \"os\"\n\n recoupable \"github.com/recoupable/marketing/sdk/go\"\n)\n\nfunc main() {\n client, err := recoupable.New(recoupable.Options{\n APIKey: os.Getenv(\"RECOUP_API_KEY\"),\n })\n if err != nil { log.Fatal(err) }\n account, err := client.GetAccountID(context.Background())\n if err != nil { log.Fatal(err) }\n log.Print(account.AccountID)\n}\n```\n\nUse `Options{AccessToken: ...}` for an existing Bearer token. The generic\n`Request(ctx, method, path, query, body, out)` method supports other documented\nJSON endpoints. Pass query parameters as `url.Values` and an unencoded `/api/` path.\nSee the [Go package reference](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0)\nfor method signatures and error types.\n\n## Python\n\nInstall the published version:\n\n```sh\npython -m pip install recoupable==0.1.0\n```\n\n```python\nimport os\nfrom recoupable import Client\n\nclient = Client(api_key=os.environ[\"RECOUP_API_KEY\"])\naccount = client.get_account_id()\nprint(account[\"accountId\"])\n```\n\nUse `Client(access_token=...)` for an existing Bearer token. The generic\n`request(method, path, query=..., body=...)` method returns decoded JSON or `None`\nfor an empty successful response. Read the [Python client reference](https://github.com/recoupable/marketing/tree/main/sdk/python)\nfor configuration and error handling.\n\n## Authentication and response handling\n\nSupply exactly one credential. Create a key in [Recoup account settings](https://chat.recoupable.dev/keys),\nor follow the [authentication guide](/authentication) for supported access methods.\nThe default API origin is `https://api.recoupable.dev`. A custom HTTPS origin is\nan explicit destination for your credential. Redirects are not followed.\n\nBoth clients cap responses at 16 MiB by default and accept empty successful\nresponses. Python uses a 30-second timeout per blocking socket operation; Go\nuses a 30-second total request deadline and supports earlier context deadlines.\nThese limits are configurable.\n\nHTTP errors retain their status and headers, including `Retry-After`; oversized\nerror bodies are truncated. Inspect the error's fields when deciding what to do.\nError messages omit credentials and response bodies. Treat a response body as\npotentially private if you log it.\n\nThe SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent\nrequest on a reused connection. A transport failure can occur after a write has\ncompleted; check the operation's outcome before repeating it.\n","headings":[{"title":"Packages","id":"packages"},{"title":"Go","id":"go"},{"title":"Python","id":"python"},{"title":"Authentication and response handling","id":"authentication-and-response-handling"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Use the official Recoup clients to call the platform's JSON API from your application.\\nBoth SDKs support an API key or an existing Bearer token, bounded responses,\\nstructured HTTP errors, and an account-identity helper. Their licenses are MIT.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"packages\",\n children: \"Packages\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Language\"\n }), _jsx(_components.th, {\n children: \"Package\"\n }), _jsx(_components.th, {\n children: \"Availability\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Go 1.23+\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0\",\n children: \"github.com/recoupable/marketing/sdk/go\"\n })\n }), _jsxs(_components.td, {\n children: [\"Version \", _jsx(_components.code, {\n children: \"v0.1.0\"\n }), \" is published and indexed.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Python 3.10+\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://pypi.org/project/recoupable/0.1.0/\",\n children: \"recoupable on PyPI\"\n })\n }), _jsxs(_components.td, {\n children: [\"Version \", _jsx(_components.code, {\n children: \"0.1.0\"\n }), \" is published.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Node.js CLI\"\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://www.npmjs.com/package/@recoupable/cli\",\n children: \"@recoupable/cli on npm\"\n })\n }), _jsxs(_components.td, {\n children: [\"The terminal client is published. See the \", _jsx(_components.a, {\n href: \"/cli\",\n children: \"CLI guide\"\n }), \" for supported commands.\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The Go and Python SDKs handle JSON endpoints. They do not implement streaming,\\nmultipart uploads, OAuth login, automatic pagination, or generated methods for\\nevery endpoint. Use each endpoint's reference to check its availability, required\\npermissions, request shape, and response type. A package installation does not\\ngrant account access.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"go\",\n children: \"Go\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Install the published version:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-sh\",\n children: \"go get github.com/recoupable/marketing/sdk/go@v0.1.0\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Read an existing API key from your application's secret environment:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-go\",\n children: \"package main\\n\\nimport (\\n \\\"context\\\"\\n \\\"log\\\"\\n \\\"os\\\"\\n\\n recoupable \\\"github.com/recoupable/marketing/sdk/go\\\"\\n)\\n\\nfunc main() {\\n client, err := recoupable.New(recoupable.Options{\\n APIKey: os.Getenv(\\\"RECOUP_API_KEY\\\"),\\n })\\n if err != nil { log.Fatal(err) }\\n account, err := client.GetAccountID(context.Background())\\n if err != nil { log.Fatal(err) }\\n log.Print(account.AccountID)\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"Options{AccessToken: ...}\"\n }), \" for an existing Bearer token. The generic\\n\", _jsx(_components.code, {\n children: \"Request(ctx, method, path, query, body, out)\"\n }), \" method supports other documented\\nJSON endpoints. Pass query parameters as \", _jsx(_components.code, {\n children: \"url.Values\"\n }), \" and an unencoded \", _jsx(_components.code, {\n children: \"/api/\"\n }), \" path.\\nSee the \", _jsx(_components.a, {\n href: \"https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0\",\n children: \"Go package reference\"\n }), \"\\nfor method signatures and error types.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"python\",\n children: \"Python\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Install the published version:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-sh\",\n children: \"python -m pip install recoupable==0.1.0\\n\"\n })\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-python\",\n children: \"import os\\nfrom recoupable import Client\\n\\nclient = Client(api_key=os.environ[\\\"RECOUP_API_KEY\\\"])\\naccount = client.get_account_id()\\nprint(account[\\\"accountId\\\"])\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"Client(access_token=...)\"\n }), \" for an existing Bearer token. The generic\\n\", _jsx(_components.code, {\n children: \"request(method, path, query=..., body=...)\"\n }), \" method returns decoded JSON or \", _jsx(_components.code, {\n children: \"None\"\n }), \"\\nfor an empty successful response. Read the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketing/tree/main/sdk/python\",\n children: \"Python client reference\"\n }), \"\\nfor configuration and error handling.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication-and-response-handling\",\n children: \"Authentication and response handling\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Supply exactly one credential. Create a key in \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"Recoup account settings\"\n }), \",\\nor follow the \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"authentication guide\"\n }), \" for supported access methods.\\nThe default API origin is \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \". A custom HTTPS origin is\\nan explicit destination for your credential. Redirects are not followed.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Both clients cap responses at 16 MiB by default and accept empty successful\\nresponses. Python uses a 30-second timeout per blocking socket operation; Go\\nuses a 30-second total request deadline and supports earlier context deadlines.\\nThese limits are configurable.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP errors retain their status and headers, including \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \"; oversized\\nerror bodies are truncated. Inspect the error's fields when deciding what to do.\\nError messages omit credentials and response bodies. Treat a response body as\\npotentially private if you log it.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent\\nrequest on a reused connection. A transport failure can occur after a write has\\ncompleted; check the operation's outcome before repeating it.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Recoup SDKs: Go and Python clients for the music API Install the official Recoup Python SDK from PyPI, the Go SDK from its module registry, and the Node CLI from npm. Includes authentication, response handling, and package links. Quickstart Getting started Use the official Recoup clients to call the platform's JSON API from your application. Both SDKs support an API key or an existing Bearer token, bounded responses, structured HTTP errors, and an account-identity helper. Their licenses are MIT. ## Packages | Language | Package | Availability | | --- | --- | --- | | Go 1.23+ | [github.com/recoupable/marketing/sdk/go](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) | Version `v0.1.0` is published and indexed. | | Python 3.10+ | [recoupable on PyPI](https://pypi.org/project/recoupable/0.1.0/) | Version `0.1.0` is published. | | Node.js CLI | [@recoupable/cli on npm](https://www.npmjs.com/package/@recoupable/cli) | The terminal client is published. See the [CLI guide](/cli) for supported commands. | The Go and Python SDKs handle JSON endpoints. They do not implement streaming, multipart uploads, OAuth login, automatic pagination, or generated methods for every endpoint. Use each endpoint's reference to check its availability, required permissions, request shape, and response type. A package installation does not grant account access. ## Go Install the published version: Read an existing API key from your application's secret environment: Use `Options{AccessToken: ...}` for an existing Bearer token. The generic `Request(ctx, method, path, query, body, out)` method supports other documented JSON endpoints. Pass query parameters as `url.Values` and an unencoded `/api/` path. See the [Go package reference](https://pkg.go.dev/github.com/recoupable/marketing/sdk/go@v0.1.0) for method signatures and error types. ## Python Install the published version: Use `Client(access_token=...)` for an existing Bearer token. The generic `request(method, path, query=..., body=...)` method returns decoded JSON or `None` for an empty successful response. Read the [Python client reference](https://github.com/recoupable/marketing/tree/main/sdk/python) for configuration and error handling. ## Authentication and response handling Supply exactly one credential. Create a key in [Recoup account settings](https://chat.recoupable.dev/keys), or follow the [authentication guide](/authentication) for supported access methods. The default API origin is `https://api.recoupable.dev`. A custom HTTPS origin is an explicit destination for your credential. Redirects are not followed. Both clients cap responses at 16 MiB by default and accept empty successful responses. Python uses a 30-second timeout per blocking socket operation; Go uses a 30-second total request deadline and supports earlier context deadlines. These limits are configurable. HTTP errors retain their status and headers, including `Retry-After`; oversized error bodies are truncated. Inspect the error's fields when deciding what to do. Error messages omit credentials and response bodies. Treat a response body as potentially private if you log it. The SDKs add no retry loop. Go's standard HTTP transport may retry an idempotent request on a reused connection. A transport failure can occur after a write has completed; check the operation's outcome before repeating it. "},{"slug":"public-website-api","title":"Recoup public website API","description":"Search and read public Recoup content, use bounded website tools, and batch independent operations without an account.","category":"Quickstart","group":"Getting started","source":"public-website-api.mdx","body":"The public website API searches and reads published Recoup pages, calculates\nworkflow scenarios from supplied inputs, and prepares unsubmitted project briefs.\nIt is free and requires no account, API key, or payment method.\n\nMusic-platform operations use the separate authenticated\n[platform API](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot\nread account data, manage artists, publish content, or send an inquiry.\n\n## Specification and first request\n\nThe [website OpenAPI specification](https://recoupable.dev/openapi.json) defines\nevery HTTP operation, its input and response schemas, and typed errors.\nThe [API catalog](https://recoupable.dev/.well-known/api-catalog) links this\nspecification alongside the platform specifications.\n\n```bash\ncurl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'\n```\n\nThe response contains `results`, `total`, and `nextCursor`. An empty result list\nis a successful search. Use a returned content ID with\n`GET /agent-api/v1/read?id=CONTENT_ID`; continue at the returned `nextOffset`\nuntil it is null. The reader accepts registry IDs, never arbitrary private URLs.\n\nUse `GET /agent-api/v1/markdown?path=/blog` for a complete public page as Markdown.\nThe [website agent guide](https://recoupable.dev/agents.md) explains all five tools,\npagination, draft behavior, and the browser interface.\n\n## Batch independent operations\n\n`POST https://recoupable.dev/agent-api/v1/batch` accepts one to ten operations.\n\n```bash\ncurl 'https://recoupable.dev/agent-api/v1/batch' \\\n -H 'Content-Type: application/json' \\\n --data '{\"operations\":[{\"name\":\"search_recoup\",\"arguments\":{\"query\":\"royalty\",\"limit\":1}},{\"name\":\"read_recoup_page\",\"arguments\":{\"id\":\"page:/services\",\"maxLength\":500}}]}'\n```\n\nThe `results` array preserves input order. Each entry has its own `status` and\n`result` or `error`. An individual failure does not cancel successful reads.\nThe batch is not a transaction. Its entire request body must fit within 16 KB.\nDraft operations return `submitted: false`; nothing is sent or saved as a lead.\n\n## Hosted quotas and errors\n\nHTTP and MCP website tools share a limit of 120 requests per 60-second fixed\nwindow, per IP address and serving region. A batch counts as one request.\n`RateLimit-Limit` and `RateLimit-Policy` describe that enforced policy on live\nresponses. Regional counters are not a global account allowance.\n\nOn HTTP 429, wait the `Retry-After` duration before retrying. HTTP 503 means the\nrequest could not be completed; retry later. JSON tool endpoints return structured\nerrors with a code, message, and recovery guidance for invalid arguments or missing content.\nLocal development does not enforce the hosted quota.\n\n## Versioning and deprecation\n\nWebsite HTTP operations use `/agent-api/v1`. Additive response fields are\ncompatible; clients should ignore fields they do not recognize. Incompatible\nchanges require a new major URL version.\n\nNo v1 deprecation or sunset is scheduled. A future retirement will be announced\nin the [agent guide](https://recoupable.dev/agents.md) with a migration guide and\n`Deprecation`, `Sunset`, and `Link` response headers when dates are known.\nThis policy applies to the public website API.\n\n## MCP connection\n\nConnect to `https://recoupable.dev/mcp` over Streamable HTTP without credentials.\nThe [public manifest](https://recoupable.dev/.well-known/mcp.json) identifies\nthe server. Its five tools share the website HTTP capabilities and hosted quota.\nTo use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead.\n","headings":[{"title":"Specification and first request","id":"specification-and-first-request"},{"title":"Batch independent operations","id":"batch-independent-operations"},{"title":"Hosted quotas and errors","id":"hosted-quotas-and-errors"},{"title":"Versioning and deprecation","id":"versioning-and-deprecation"},{"title":"MCP connection","id":"mcp-connection"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"The public website API searches and reads published Recoup pages, calculates\\nworkflow scenarios from supplied inputs, and prepares unsubmitted project briefs.\\nIt is free and requires no account, API key, or payment method.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Music-platform operations use the separate authenticated\\n\", _jsx(_components.a, {\n href: \"/quickstart\",\n children: \"platform API\"\n }), \" and \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"platform MCP\"\n }), \". Website tools cannot\\nread account data, manage artists, publish content, or send an inquiry.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"specification-and-first-request\",\n children: \"Specification and first request\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"https://recoupable.dev/openapi.json\",\n children: \"website OpenAPI specification\"\n }), \" defines\\nevery HTTP operation, its input and response schemas, and typed errors.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/.well-known/api-catalog\",\n children: \"API catalog\"\n }), \" links this\\nspecification alongside the platform specifications.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response contains \", _jsx(_components.code, {\n children: \"results\"\n }), \", \", _jsx(_components.code, {\n children: \"total\"\n }), \", and \", _jsx(_components.code, {\n children: \"nextCursor\"\n }), \". An empty result list\\nis a successful search. Use a returned content ID with\\n\", _jsx(_components.code, {\n children: \"GET /agent-api/v1/read?id=CONTENT_ID\"\n }), \"; continue at the returned \", _jsx(_components.code, {\n children: \"nextOffset\"\n }), \"\\nuntil it is null. The reader accepts registry IDs, never arbitrary private URLs.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"GET /agent-api/v1/markdown?path=/blog\"\n }), \" for a complete public page as Markdown.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/agents.md\",\n children: \"website agent guide\"\n }), \" explains all five tools,\\npagination, draft behavior, and the browser interface.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"batch-independent-operations\",\n children: \"Batch independent operations\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST https://recoupable.dev/agent-api/v1/batch\"\n }), \" accepts one to ten operations.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl 'https://recoupable.dev/agent-api/v1/batch' \\\\\\n -H 'Content-Type: application/json' \\\\\\n --data '{\\\"operations\\\":[{\\\"name\\\":\\\"search_recoup\\\",\\\"arguments\\\":{\\\"query\\\":\\\"royalty\\\",\\\"limit\\\":1}},{\\\"name\\\":\\\"read_recoup_page\\\",\\\"arguments\\\":{\\\"id\\\":\\\"page:/services\\\",\\\"maxLength\\\":500}}]}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.code, {\n children: \"results\"\n }), \" array preserves input order. Each entry has its own \", _jsx(_components.code, {\n children: \"status\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"result\"\n }), \" or \", _jsx(_components.code, {\n children: \"error\"\n }), \". An individual failure does not cancel successful reads.\\nThe batch is not a transaction. Its entire request body must fit within 16 KB.\\nDraft operations return \", _jsx(_components.code, {\n children: \"submitted: false\"\n }), \"; nothing is sent or saved as a lead.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hosted-quotas-and-errors\",\n children: \"Hosted quotas and errors\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP and MCP website tools share a limit of 120 requests per 60-second fixed\\nwindow, per IP address and serving region. A batch counts as one request.\\n\", _jsx(_components.code, {\n children: \"RateLimit-Limit\"\n }), \" and \", _jsx(_components.code, {\n children: \"RateLimit-Policy\"\n }), \" describe that enforced policy on live\\nresponses. Regional counters are not a global account allowance.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"On HTTP 429, wait the \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" duration before retrying. HTTP 503 means the\\nrequest could not be completed; retry later. JSON tool endpoints return structured\\nerrors with a code, message, and recovery guidance for invalid arguments or missing content.\\nLocal development does not enforce the hosted quota.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"versioning-and-deprecation\",\n children: \"Versioning and deprecation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Website HTTP operations use \", _jsx(_components.code, {\n children: \"/agent-api/v1\"\n }), \". Additive response fields are\\ncompatible; clients should ignore fields they do not recognize. Incompatible\\nchanges require a new major URL version.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"No v1 deprecation or sunset is scheduled. A future retirement will be announced\\nin the \", _jsx(_components.a, {\n href: \"https://recoupable.dev/agents.md\",\n children: \"agent guide\"\n }), \" with a migration guide and\\n\", _jsx(_components.code, {\n children: \"Deprecation\"\n }), \", \", _jsx(_components.code, {\n children: \"Sunset\"\n }), \", and \", _jsx(_components.code, {\n children: \"Link\"\n }), \" response headers when dates are known.\\nThis policy applies to the public website API.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"mcp-connection\",\n children: \"MCP connection\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connect to \", _jsx(_components.code, {\n children: \"https://recoupable.dev/mcp\"\n }), \" over Streamable HTTP without credentials.\\nThe \", _jsx(_components.a, {\n href: \"https://recoupable.dev/.well-known/mcp.json\",\n children: \"public manifest\"\n }), \" identifies\\nthe server. Its five tools share the website HTTP capabilities and hosted quota.\\nTo use your music-platform account, follow \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" instead.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Recoup public website API Search and read public Recoup content, use bounded website tools, and batch independent operations without an account. Quickstart Getting started The public website API searches and reads published Recoup pages, calculates workflow scenarios from supplied inputs, and prepares unsubmitted project briefs. It is free and requires no account, API key, or payment method. Music-platform operations use the separate authenticated [platform API](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot read account data, manage artists, publish content, or send an inquiry. ## Specification and first request The [website OpenAPI specification](https://recoupable.dev/openapi.json) defines every HTTP operation, its input and response schemas, and typed errors. The [API catalog](https://recoupable.dev/.well-known/api-catalog) links this specification alongside the platform specifications. The response contains `results`, `total`, and `nextCursor`. An empty result list is a successful search. Use a returned content ID with `GET /agent-api/v1/read?id=CONTENT_ID`; continue at the returned `nextOffset` until it is null. The reader accepts registry IDs, never arbitrary private URLs. Use `GET /agent-api/v1/markdown?path=/blog` for a complete public page as Markdown. The [website agent guide](https://recoupable.dev/agents.md) explains all five tools, pagination, draft behavior, and the browser interface. ## Batch independent operations `POST https://recoupable.dev/agent-api/v1/batch` accepts one to ten operations. The `results` array preserves input order. Each entry has its own `status` and `result` or `error`. An individual failure does not cancel successful reads. The batch is not a transaction. Its entire request body must fit within 16 KB. Draft operations return `submitted: false`; nothing is sent or saved as a lead. ## Hosted quotas and errors HTTP and MCP website tools share a limit of 120 requests per 60-second fixed window, per IP address and serving region. A batch counts as one request. `RateLimit-Limit` and `RateLimit-Policy` describe that enforced policy on live responses. Regional counters are not a global account allowance. On HTTP 429, wait the `Retry-After` duration before retrying. HTTP 503 means the request could not be completed; retry later. JSON tool endpoints return structured errors with a code, message, and recovery guidance for invalid arguments or missing content. Local development does not enforce the hosted quota. ## Versioning and deprecation Website HTTP operations use `/agent-api/v1`. Additive response fields are compatible; clients should ignore fields they do not recognize. Incompatible changes require a new major URL version. No v1 deprecation or sunset is scheduled. A future retirement will be announced in the [agent guide](https://recoupable.dev/agents.md) with a migration guide and `Deprecation`, `Sunset`, and `Link` response headers when dates are known. This policy applies to the public website API. ## MCP connection Connect to `https://recoupable.dev/mcp` over Streamable HTTP without credentials. The [public manifest](https://recoupable.dev/.well-known/mcp.json) identifies the server. Its five tools share the website HTTP capabilities and hosted quota. To use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead. "},{"slug":"cli","title":"CLI","description":"Install the Recoup CLI and interact with the platform from your terminal.","category":"Quickstart","group":"Getting started","source":"cli.mdx","body":"The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.\n\n\n**The CLI is in beta.** The reference below follows the v0.1.15 source command set. Check `recoup --version` and `--help` for the package installed in your environment. For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up.\n\n**Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.\n\n\n## Install\n\n```bash\nnpm install -g @recoupable/cli\n```\n\n## Authenticate\n\nSet your API key as an environment variable:\n\n```bash\nexport RECOUP_API_KEY=your-api-key\n```\n\nVerify it works:\n\n```bash\nrecoup whoami\n```\n\n\nGet an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) for instant key generation.\n\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `RECOUP_API_KEY` | Yes | — | Your Recoup API key |\n| `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override; set `https://api.recoupable.dev` to use the canonical API domain |\n\nAll commands support `--json` for machine-readable output and `--help` for usage info.\n\n---\n\n## Commands\n\n### whoami\n\nShow the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id).\n\n```bash\nrecoup whoami\nrecoup whoami --json\n```\n\n### orgs\n\nList organizations. See [`GET /api/organizations`](/api-reference/organizations/list).\n\n```bash\nrecoup orgs list\nrecoup orgs list --account \n```\n\n### artists\n\nList artists. See [`GET /api/artists`](/api-reference/artists/list).\n\n```bash\nrecoup artists list\nrecoup artists list --org \nrecoup artists list --account \n```\n\n### emails\n\nSend an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create).\n\n```bash\nrecoup emails --subject \"Pulse Report\" --text \"Here's your weekly summary.\"\nrecoup emails --subject \"Update\" --html \"

Report

Details here.

\"\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--subject ` | No | Email subject line; defaults from the body when omitted |\n| `--text ` | No | Plain text or Markdown body |\n| `--html ` | No | Raw HTML body (takes precedence over `--text`) |\n| `--cc ` | No | CC recipient (repeatable) |\n| `--chat-id ` | No | Chat ID for a chat link in the email footer |\n| `--account ` | No | Send to a specific account (org keys only) |\n\n### chats\n\nManage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create).\n\n```bash\nrecoup chats list\nrecoup chats create --name \"My Topic\"\nrecoup chats create --name \"My Topic\" --artist \n```\n\n### sandboxes\n\nManage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create).\n\n```bash\nrecoup sandboxes list\nrecoup sandboxes create\nrecoup sandboxes create --command \"ls -la\"\n```\n\n### tasks\n\nCheck background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs).\n\n```bash\nrecoup tasks status --run \n```\n\n### songs\n\nRun AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets).\n\n```bash\nrecoup songs presets\nrecoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3\nrecoup songs analyze --prompt \"Describe the production style\" --audio https://example.com/track.mp3\n```\n\nExactly one of `--preset` or `--prompt` is required, together with `--audio`. The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API.\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. |\n| `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. |\n| `--audio ` | Yes | Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported. |\n| `--max-tokens ` | No | Max tokens to generate (default 512). |\n\n---\n\n## content\n\nContent creation pipeline — generate AI-powered social videos for artists.\n\n### List templates\n\n```bash\nrecoup content templates\n```\n\n### Validate an artist\n\nCheck that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate).\n\n```bash\nrecoup content validate --artist \n```\n\n### Estimate cost\n\nPreview estimated cost and duration before kicking off the pipeline. See [`GET /api/content/estimate`](/api-reference/content/estimate).\n\n```bash\nrecoup content estimate\nrecoup content estimate --lipsync --batch 2 --compare\n```\n\n### Create content\n\nRun the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create).\n\n```bash\nrecoup content create --artist \nrecoup content create --artist --template --lipsync --upscale\n```\n\n| Flag | Required | Description |\n|------|----------|-------------|\n| `--artist ` | Yes | Artist account ID |\n| `--template ` | No | Template name (default: random) |\n| `--lipsync` | No | Enable lipsync mode |\n| `--upscale` | No | Enable upscaling |\n| `--caption-length ` | No | Max caption length in characters |\n\n\nFor finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands.\n\n","headings":[{"title":"Install","id":"install"},{"title":"Authenticate","id":"authenticate"},{"title":"Configuration","id":"configuration"},{"title":"Commands","id":"commands"},{"title":"content","id":"content"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n }, {Note, Tip} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Tip) _missingMdxReference(\"Tip\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"The Recoup CLI (\", _jsx(_components.code, {\n children: \"@recoupable/cli\"\n }), \") wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.\"]\n }), \"\\n\", _jsxs(Note, {\n children: [_jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"The CLI is in beta.\"\n }), \" The reference below follows the v0.1.15 source command set. Check \", _jsx(_components.code, {\n children: \"recoup --version\"\n }), \" and \", _jsx(_components.code, {\n children: \"--help\"\n }), \" for the package installed in your environment. For research workflows and most content operations, call the \", _jsx(_components.a, {\n href: \"/api-reference\",\n children: \"REST API\"\n }), \" directly — the CLI is gradually catching up.\"]\n }), _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Agents:\"\n }), \" if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.\"]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"install\",\n children: \"Install\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"npm install -g @recoupable/cli\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authenticate\",\n children: \"Authenticate\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Set your API key as an environment variable:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"export RECOUP_API_KEY=your-api-key\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Verify it works:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup whoami\\n\"\n })\n }), \"\\n\", _jsx(Tip, {\n children: _jsxs(_components.p, {\n children: [\"Get an API key from the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys page\"\n }), \" or use the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"agent signup\"\n }), \" for instant key generation.\"]\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"configuration\",\n children: \"Configuration\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Variable\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Default\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"RECOUP_API_KEY\"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"—\"\n }), _jsx(_components.td, {\n children: \"Your Recoup API key\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"RECOUP_API_URL\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"https://recoup-api.vercel.app\"\n })\n }), _jsxs(_components.td, {\n children: [\"API base URL override; set \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \" to use the canonical API domain\"]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"All commands support \", _jsx(_components.code, {\n children: \"--json\"\n }), \" for machine-readable output and \", _jsx(_components.code, {\n children: \"--help\"\n }), \" for usage info.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"commands\",\n children: \"Commands\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"whoami\",\n children: \"whoami\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Show the authenticated account. See \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup whoami\\nrecoup whoami --json\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"orgs\",\n children: \"orgs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"List organizations. See \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/organizations\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup orgs list\\nrecoup orgs list --account \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"artists\",\n children: \"artists\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"List artists. See \", _jsx(_components.a, {\n href: \"/api-reference/artists/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/artists\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup artists list\\nrecoup artists list --org \\nrecoup artists list --account \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"emails\",\n children: \"emails\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send an email to the authenticated account. See \", _jsx(_components.a, {\n href: \"/api-reference/emails/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/emails\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup emails --subject \\\"Pulse Report\\\" --text \\\"Here's your weekly summary.\\\"\\nrecoup emails --subject \\\"Update\\\" --html \\\"

Report

Details here.

\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--subject \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Email subject line; defaults from the body when omitted\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--text \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Plain text or Markdown body\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--html \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsxs(_components.td, {\n children: [\"Raw HTML body (takes precedence over \", _jsx(_components.code, {\n children: \"--text\"\n }), \")\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--cc \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"CC recipient (repeatable)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--chat-id \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Chat ID for a chat link in the email footer\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--account \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Send to a specific account (org keys only)\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"chats\",\n children: \"chats\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Manage chats. See \", _jsx(_components.a, {\n href: \"/api-reference/chat/chats\",\n children: _jsx(_components.code, {\n children: \"GET /api/chats\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/chat/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/chats\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup chats list\\nrecoup chats create --name \\\"My Topic\\\"\\nrecoup chats create --name \\\"My Topic\\\" --artist \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"sandboxes\",\n children: \"sandboxes\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Manage sandboxes. See \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/sandboxes\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup sandboxes list\\nrecoup sandboxes create\\nrecoup sandboxes create --command \\\"ls -la\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"tasks\",\n children: \"tasks\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Check background task status. See \", _jsx(_components.a, {\n href: \"/api-reference/tasks/runs\",\n children: _jsx(_components.code, {\n children: \"GET /api/tasks/runs\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup tasks status --run \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"songs\",\n children: \"songs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Run AI music analysis. See \", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze-presets\",\n children: _jsx(_components.code, {\n children: \"GET /api/songs/analyze/presets\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup songs presets\\nrecoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3\\nrecoup songs analyze --prompt \\\"Describe the production style\\\" --audio https://example.com/track.mp3\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Exactly one of \", _jsx(_components.code, {\n children: \"--preset\"\n }), \" or \", _jsx(_components.code, {\n children: \"--prompt\"\n }), \" is required, together with \", _jsx(_components.code, {\n children: \"--audio\"\n }), \". The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--preset \"\n })\n }), _jsx(_components.td, {\n children: \"Conditional\"\n }), _jsxs(_components.td, {\n children: [\"Curated analysis preset. Required when \", _jsx(_components.code, {\n children: \"--prompt\"\n }), \" is omitted.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--prompt \"\n })\n }), _jsx(_components.td, {\n children: \"Conditional\"\n }), _jsxs(_components.td, {\n children: [\"Custom text prompt. Required when \", _jsx(_components.code, {\n children: \"--preset\"\n }), \" is omitted.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--audio \"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--max-tokens \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Max tokens to generate (default 512).\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"content\",\n children: \"content\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Content creation pipeline — generate AI-powered social videos for artists.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"list-templates\",\n children: \"List templates\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content templates\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"validate-an-artist\",\n children: \"Validate an artist\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Check that an artist has the required assets before creating content. See \", _jsx(_components.a, {\n href: \"/api-reference/content/validate\",\n children: _jsx(_components.code, {\n children: \"GET /api/content/validate\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content validate --artist \\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"estimate-cost\",\n children: \"Estimate cost\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Preview estimated cost and duration before kicking off the pipeline. See \", _jsx(_components.a, {\n href: \"/api-reference/content/estimate\",\n children: _jsx(_components.code, {\n children: \"GET /api/content/estimate\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content estimate\\nrecoup content estimate --lipsync --batch 2 --compare\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"create-content\",\n children: \"Create content\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Run the full content-creation pipeline for an artist. See \", _jsx(_components.a, {\n href: \"/api-reference/content/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/content/create\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"recoup content create --artist \\nrecoup content create --artist --template --lipsync --upscale\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Flag\"\n }), _jsx(_components.th, {\n children: \"Required\"\n }), _jsx(_components.th, {\n children: \"Description\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--artist \"\n })\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Artist account ID\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--template \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Template name (default: random)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--lipsync\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Enable lipsync mode\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--upscale\"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Enable upscaling\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"--caption-length \"\n })\n }), _jsx(_components.td, {\n children: \"No\"\n }), _jsx(_components.td, {\n children: \"Max caption length in characters\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(Tip, {\n children: _jsxs(_components.p, {\n children: [\"For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the \", _jsx(_components.a, {\n href: \"/api-reference/content/generate-image\",\n children: \"content REST endpoints\"\n }), \" directly. Those primitives aren't yet exposed as individual CLI subcommands.\"]\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"CLI Install the Recoup CLI and interact with the platform from your terminal. Quickstart Getting started The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments. **The CLI is in beta.** The reference below follows the v0.1.15 source command set. Check `recoup --version` and `--help` for the package installed in your environment. For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up. **Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command. ## Install ## Authenticate Set your API key as an environment variable: Verify it works: Get an API key from the [API Keys page](https://chat.recoupable.dev/keys) or use the [agent signup](/agents) for instant key generation. ## Configuration | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `RECOUP_API_KEY` | Yes | — | Your Recoup API key | | `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override; set `https://api.recoupable.dev` to use the canonical API domain | All commands support `--json` for machine-readable output and `--help` for usage info. --- ## Commands ### whoami Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id). ### orgs List organizations. See [`GET /api/organizations`](/api-reference/organizations/list). ### artists List artists. See [`GET /api/artists`](/api-reference/artists/list). ### emails Send an email to the authenticated account. See [`POST /api/emails`](/api-reference/emails/create). | Flag | Required | Description | |------|----------|-------------| | `--subject ` | No | Email subject line; defaults from the body when omitted | | `--text ` | No | Plain text or Markdown body | | `--html ` | No | Raw HTML body (takes precedence over `--text`) | | `--cc ` | No | CC recipient (repeatable) | | `--chat-id ` | No | Chat ID for a chat link in the email footer | | `--account ` | No | Send to a specific account (org keys only) | ### chats Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create). ### sandboxes Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create). ### tasks Check background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs). ### songs Run AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets). Exactly one of `--preset` or `--prompt` is required, together with `--audio`. The API rejects both selectors together and verifies the audio URL before inference. The coordinated CLI validation fix reports these errors before sending a request; older installed packages may send them to the API. | Flag | Required | Description | |------|----------|-------------| | `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. | | `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. | | `--audio ` | Yes | Public URL to an audio file (MP3, WAV, FLAC), required for every preset and custom prompt. Metadata-only analysis is not supported. | | `--max-tokens ` | No | Max tokens to generate (default 512). | --- ## content Content creation pipeline — generate AI-powered social videos for artists. ### List templates ### Validate an artist Check that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate). ### Estimate cost Preview estimated cost and duration before kicking off the pipeline. See [`GET /api/content/estimate`](/api-reference/content/estimate). ### Create content Run the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create). | Flag | Required | Description | |------|----------|-------------| | `--artist ` | Yes | Artist account ID | | `--template ` | No | Template name (default: random) | | `--lipsync` | No | Enable lipsync mode | | `--upscale` | No | Enable upscaling | | `--caption-length ` | No | Max caption length in characters | For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands. "},{"slug":"claude","title":"Claude","description":"Connect Claude to Recoup and install optional workflow instructions.","category":"Quickstart","group":"Getting started","source":"claude.mdx","body":"Add `https://api.recoupable.dev/mcp` in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See [MCP OAuth](/mcp-oauth) for the dated client verification record and troubleshooting.\n\nAfter connecting, refresh tools and call the discovered `list_artists` tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account.\n\nFor workflow instructions, install the consolidated Recoup package from the [Recoup marketplace](https://github.com/recoupable/marketplace), using the manifest/package name shown there. Skills-only installation with `npx skills add recoupable/skills` does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed.\n\nMCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access.\n\nStart a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow.\n","headings":[],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Add \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for the dated client verification record and troubleshooting.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"After connecting, refresh tools and call the discovered \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For workflow instructions, install the consolidated Recoup package from the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/marketplace\",\n children: \"Recoup marketplace\"\n }), \", using the manifest/package name shown there. Skills-only installation with \", _jsx(_components.code, {\n children: \"npx skills add recoupable/skills\"\n }), \" does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"MCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Start a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Claude Connect Claude to Recoup and install optional workflow instructions. Quickstart Getting started Add `https://api.recoupable.dev/mcp` in Claude's remote connector controls and complete browser OAuth using your real Recoup account. See [MCP OAuth](/mcp-oauth) for the dated client verification record and troubleshooting. After connecting, refresh tools and call the discovered `list_artists` tool. Report success after that read succeeds; a legitimate empty roster does not require creating another account. For workflow instructions, install the consolidated Recoup package from the [Recoup marketplace](https://github.com/recoupable/marketplace), using the manifest/package name shown there. Skills-only installation with `npx skills add recoupable/skills` does not configure MCP or create credentials. Standalone platform/content/research packages remain separate distributions; their installed versions may contain older instructions until their reconciliation release is installed. MCP OAuth credentials stay in Claude. A REST-only script needs a separately configured API key or application-provided access token. Use a supported secret facility or a user-approved environment file; never paste keys into Profile or Global instructions. Do not register a disposable account to recover customer access. Start a fresh conversation and verify tool discovery and artist access again. Browser sign-in, plugin installation and token refresh are separate checks; none alone proves the complete workflow. "},{"slug":"mcp","title":"MCP","description":"Connect an agent to Recoup through OAuth and discover its authorized tools.","category":"Quickstart","group":"Getting started","source":"mcp.mdx","body":"Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](/mcp-oauth).\n\nUse `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result.\n\n`mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.\n\nSandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](/api-reference/sandboxes/create) with a separate authorized credential when required.\n\nFor an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.\n\n## Context results\n\nThe [Context reference](/api-reference/context/operate) pairs each supported action\nwith its success status, response model and synthetic request/result examples.\nUse the status declared for that action: `ingest` returns 202, while the specific\ncatalog, artist, release and text ingestion actions return 200. A 202 verification\nreceipt means queued after existing readiness checks, not completed work.\nHTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt;\ndelegated OAuth omits it. The examples do not verify hosted access or enable collection.\n\n## Plan a catalog lookup\n\nA catalog manager with an existing catalog Context request can plan a lookup for\nits current expanded recording members. Standard MCP uses `context` with\n`action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research`\nwith the same input fields and no `action`. Discover the tool in the connected\nclient before use; this source mapping does not prove hosted availability.\n\nChoose `recording_candidates`, `recording_work_candidates` or `platform_metadata`.\nThese plan possible recording matches, linked works or platform track information.\nThe response preserves the existing module values and node IDs, returns each node\nblocked and has `collectionPermitted: false`. It does not fetch data, verify rights,\nstart collection or grant spending permission. The [Context reference](/api-reference/context/operate)\nlists all accepted compatibility values, required IDs, page cursors and the complete response.\n\n## Continue a catalog case\n\nThe source contract adds `save_catalog_case`, `read_catalog_case` and\n`list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the\ntools in the connected host before using them. They also use the `context` tool\nwith the corresponding `action`. The catalog-case database and API release must\nbe deployed before this source contract is available.\n\nA case keeps versioned sources, assessments, findings, proposed actions, attempts\nand outcomes for the authorized workspace. No artist or ingestion request is\nrequired. The stored snapshot is `customer_assertion` evidence and always returns\n`external_actions: unsupported`: saving a record does not submit a registration,\nsend a claim, confirm a provider decision or verify a bank receipt.\n\nFor a new case, save with `expected_revision: 0` and `snapshot.revision: 0`.\nFor subsequent saves, use the current revision. Supply a unique idempotency key\nfor each new save. After an uncertain response, retry the unchanged payload with\nthe same key and expected revision.\nReads can withhold withdrawn evidence and its dependent records; explicitly\nreassemble a partial snapshot before another save. The [Context reference](/api-reference/context/operate)\ndefines the complete bounded schema, historical-source rules, revision conflicts,\nresponse fields and list pagination.\n\n## Check an application proposal\n\nThe pending standard MCP tool `validate_application_registration` checks an\nauthorized workspace's proposed name, environment, exact origins and return URLs.\nIt returns `persisted: false` and `origins_verified: false`; it does not register\nan application, prove domain ownership or issue application credentials.\nDelegated OAuth excludes this tool, including grants with `mcp:tools`. Discover\nit in a standard connection before use. See the [proposal preflight reference](/api-reference/applications/validate-registration)\nfor inputs, normal authentication effects and the limits of a successful result.\n\n## Release Packs\n\nWhen deployed and exposed by the current grant, the pack catalog includes\n`prepare_release_pack`, `get_release_pack`, `estimate_release_pack`,\n`generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and\n`export_release_pack`. These use the same account ownership, brief revisions,\ncomplete quotes and budget limits as REST. No existing artist or GitHub workspace\nis required. Use returned schemas and identifiers; preparation does not authorize\npaid generation. See [Release Packs](/release-packs) for first use and upload limits.\n","headings":[{"title":"Context results","id":"context-results"},{"title":"Plan a catalog lookup","id":"plan-a-catalog-lookup"},{"title":"Continue a catalog case","id":"continue-a-catalog-case"},{"title":"Check an application proposal","id":"check-an-application-proposal"},{"title":"Release Packs","id":"release-packs"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Connect your host to \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"OAuth setup guide\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"tools/list\"\n }), \" after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" and call it with its returned schema to verify access. An empty roster is a valid result.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sandbox command tools previously shown on this page are absent from the current registry. Do not call \", _jsx(_components.code, {\n children: \"prompt_sandbox\"\n }), \", \", _jsx(_components.code, {\n children: \"run_sandbox_command\"\n }), \", or infer that every REST endpoint is exposed as MCP. Use documented \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/create\",\n children: \"REST sandbox operations\"\n }), \" with a separate authorized credential when required.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For an API-key MCP connection, configure \", _jsx(_components.code, {\n children: \"Authorization: Bearer YOUR_RECOUP_API_KEY\"\n }), \" in the client's secret settings. The \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header is for \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"REST requests\"\n }), \". Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"context-results\",\n children: \"Context results\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \" pairs each supported action\\nwith its success status, response model and synthetic request/result examples.\\nUse the status declared for that action: \", _jsx(_components.code, {\n children: \"ingest\"\n }), \" returns 202, while the specific\\ncatalog, artist, release and text ingestion actions return 200. A 202 verification\\nreceipt means queued after existing readiness checks, not completed work.\\nHTTP/standard MCP \", _jsx(_components.code, {\n children: \"read\"\n }), \" may include a metadata-only \", _jsx(_components.code, {\n children: \"material_evidence\"\n }), \" receipt;\\ndelegated OAuth omits it. The examples do not verify hosted access or enable collection.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"plan-a-catalog-lookup\",\n children: \"Plan a catalog lookup\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A catalog manager with an existing catalog Context request can plan a lookup for\\nits current expanded recording members. Standard MCP uses \", _jsx(_components.code, {\n children: \"context\"\n }), \" with\\n\", _jsx(_components.code, {\n children: \"action: plan_catalog_members\"\n }), \"; delegated OAuth uses \", _jsx(_components.code, {\n children: \"plan_music_catalog_research\"\n }), \"\\nwith the same input fields and no \", _jsx(_components.code, {\n children: \"action\"\n }), \". Discover the tool in the connected\\nclient before use; this source mapping does not prove hosted availability.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Choose \", _jsx(_components.code, {\n children: \"recording_candidates\"\n }), \", \", _jsx(_components.code, {\n children: \"recording_work_candidates\"\n }), \" or \", _jsx(_components.code, {\n children: \"platform_metadata\"\n }), \".\\nThese plan possible recording matches, linked works or platform track information.\\nThe response preserves the existing module values and node IDs, returns each node\\nblocked and has \", _jsx(_components.code, {\n children: \"collectionPermitted: false\"\n }), \". It does not fetch data, verify rights,\\nstart collection or grant spending permission. The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \"\\nlists all accepted compatibility values, required IDs, page cursors and the complete response.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"continue-a-catalog-case\",\n children: \"Continue a catalog case\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The source contract adds \", _jsx(_components.code, {\n children: \"save_catalog_case\"\n }), \", \", _jsx(_components.code, {\n children: \"read_catalog_case\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"list_catalog_cases\"\n }), \" to standard MCP; delegated OAuth excludes them. Discover the\\ntools in the connected host before using them. They also use the \", _jsx(_components.code, {\n children: \"context\"\n }), \" tool\\nwith the corresponding \", _jsx(_components.code, {\n children: \"action\"\n }), \". The catalog-case database and API release must\\nbe deployed before this source contract is available.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A case keeps versioned sources, assessments, findings, proposed actions, attempts\\nand outcomes for the authorized workspace. No artist or ingestion request is\\nrequired. The stored snapshot is \", _jsx(_components.code, {\n children: \"customer_assertion\"\n }), \" evidence and always returns\\n\", _jsx(_components.code, {\n children: \"external_actions: unsupported\"\n }), \": saving a record does not submit a registration,\\nsend a claim, confirm a provider decision or verify a bank receipt.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a new case, save with \", _jsx(_components.code, {\n children: \"expected_revision: 0\"\n }), \" and \", _jsx(_components.code, {\n children: \"snapshot.revision: 0\"\n }), \".\\nFor subsequent saves, use the current revision. Supply a unique idempotency key\\nfor each new save. After an uncertain response, retry the unchanged payload with\\nthe same key and expected revision.\\nReads can withhold withdrawn evidence and its dependent records; explicitly\\nreassemble a partial snapshot before another save. The \", _jsx(_components.a, {\n href: \"/api-reference/context/operate\",\n children: \"Context reference\"\n }), \"\\ndefines the complete bounded schema, historical-source rules, revision conflicts,\\nresponse fields and list pagination.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"check-an-application-proposal\",\n children: \"Check an application proposal\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The pending standard MCP tool \", _jsx(_components.code, {\n children: \"validate_application_registration\"\n }), \" checks an\\nauthorized workspace's proposed name, environment, exact origins and return URLs.\\nIt returns \", _jsx(_components.code, {\n children: \"persisted: false\"\n }), \" and \", _jsx(_components.code, {\n children: \"origins_verified: false\"\n }), \"; it does not register\\nan application, prove domain ownership or issue application credentials.\\nDelegated OAuth excludes this tool, including grants with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \". Discover\\nit in a standard connection before use. See the \", _jsx(_components.a, {\n href: \"/api-reference/applications/validate-registration\",\n children: \"proposal preflight reference\"\n }), \"\\nfor inputs, normal authentication effects and the limits of a successful result.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"release-packs\",\n children: \"Release Packs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"When deployed and exposed by the current grant, the pack catalog includes\\n\", _jsx(_components.code, {\n children: \"prepare_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"get_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"estimate_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"generate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"retry_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"upload_release_pack_asset\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"export_release_pack\"\n }), \". These use the same account ownership, brief revisions,\\ncomplete quotes and budget limits as REST. No existing artist or GitHub workspace\\nis required. Use returned schemas and identifiers; preparation does not authorize\\npaid generation. See \", _jsx(_components.a, {\n href: \"/release-packs\",\n children: \"Release Packs\"\n }), \" for first use and upload limits.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"MCP Connect an agent to Recoup through OAuth and discover its authorized tools. Quickstart Getting started Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](/mcp-oauth). Use `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result. `mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access. Sandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](/api-reference/sandboxes/create) with a separate authorized credential when required. For an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST. ## Context results The [Context reference](/api-reference/context/operate) pairs each supported action with its success status, response model and synthetic request/result examples. Use the status declared for that action: `ingest` returns 202, while the specific catalog, artist, release and text ingestion actions return 200. A 202 verification receipt means queued after existing readiness checks, not completed work. HTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt; delegated OAuth omits it. The examples do not verify hosted access or enable collection. ## Plan a catalog lookup A catalog manager with an existing catalog Context request can plan a lookup for its current expanded recording members. Standard MCP uses `context` with `action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research` with the same input fields and no `action`. Discover the tool in the connected client before use; this source mapping does not prove hosted availability. Choose `recording_candidates`, `recording_work_candidates` or `platform_metadata`. These plan possible recording matches, linked works or platform track information. The response preserves the existing module values and node IDs, returns each node blocked and has `collectionPermitted: false`. It does not fetch data, verify rights, start collection or grant spending permission. The [Context reference](/api-reference/context/operate) lists all accepted compatibility values, required IDs, page cursors and the complete response. ## Continue a catalog case The source contract adds `save_catalog_case`, `read_catalog_case` and `list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the tools in the connected host before using them. They also use the `context` tool with the corresponding `action`. The catalog-case database and API release must be deployed before this source contract is available. A case keeps versioned sources, assessments, findings, proposed actions, attempts and outcomes for the authorized workspace. No artist or ingestion request is required. The stored snapshot is `customer_assertion` evidence and always returns `external_actions: unsupported`: saving a record does not submit a registration, send a claim, confirm a provider decision or verify a bank receipt. For a new case, save with `expected_revision: 0` and `snapshot.revision: 0`. For subsequent saves, use the current revision. Supply a unique idempotency key for each new save. After an uncertain response, retry the unchanged payload with the same key and expected revision. Reads can withhold withdrawn evidence and its dependent records; explicitly reassemble a partial snapshot before another save. The [Context reference](/api-reference/context/operate) defines the complete bounded schema, historical-source rules, revision conflicts, response fields and list pagination. ## Check an application proposal The pending standard MCP tool `validate_application_registration` checks an authorized workspace's proposed name, environment, exact origins and return URLs. It returns `persisted: false` and `origins_verified: false`; it does not register an application, prove domain ownership or issue application credentials. Delegated OAuth excludes this tool, including grants with `mcp:tools`. Discover it in a standard connection before use. See the [proposal preflight reference](/api-reference/applications/validate-registration) for inputs, normal authentication effects and the limits of a successful result. ## Release Packs When deployed and exposed by the current grant, the pack catalog includes `prepare_release_pack`, `get_release_pack`, `estimate_release_pack`, `generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and `export_release_pack`. These use the same account ownership, brief revisions, complete quotes and budget limits as REST. No existing artist or GitHub workspace is required. Use returned schemas and identifiers; preparation does not authorize paid generation. See [Release Packs](/release-packs) for first use and upload limits. "},{"slug":"mcp-oauth","title":"Connect an agent","description":"Connect an MCP client to Recoup with OAuth and account-authorized tools.","category":"Quickstart","group":"Getting started","source":"mcp-oauth.mdx","body":"Use this URL in your agent's remote MCP settings:\n\n```text\nhttps://api.recoupable.dev/mcp\n```\n\nSelect **OAuth**. Recoup supports [published client metadata (CIMD)](/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.\n\n## What your agent can do\n\nRequest **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.\n\nThe consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.\n\n| Permission | Access |\n| --- | --- |\n| `mcp:tools` | Full business-tool catalog across accessible workspaces |\n| `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` |\n| `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` |\n\nExisting limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience.\n\nOAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.\n\nEmail uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.\n\nThe platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.\n\nNew connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately.\n\nConnections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.\n\n## Claude\n\n1. Open **Customize → Connectors → Add custom connector**.\n2. Name it **Recoup** and enter the MCP URL above.\n3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR.\n4. Connect, sign in to Recoup, and select **Allow access**.\n5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.\n\nClaude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.\n\nClaude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).\n\n## ChatGPT\n\nIn the interface tested on October 7, 2026:\n\n1. Open **Plugins → Add → Add custom MCP server**.\n2. Enter **Recoup**, the MCP URL, and **OAuth**.\n3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access.\n4. Create the plugin, connect it, and complete Recoup consent.\n5. Start a chat with Recoup enabled and request an artist list.\n\nChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).\n\n## Codex\n\n```bash\ncodex mcp add recoup --url https://api.recoupable.dev/mcp\ncodex mcp login recoup --scopes mcp:tools\n```\n\nComplete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp).\n\n## Cursor\n\nAdd a remote server to your project's `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"recoup\": {\n \"url\": \"https://api.recoupable.dev/mcp\"\n }\n }\n}\n```\n\nOpen Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions.\n\n## Other agents and callbacks\n\nUse a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:\n\n- Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp`\n- Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth`\n- Resource: `https://api.recoupable.dev/mcp`\n\nRegister the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration.\n\nA generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.\n\n### Additional client setup paths\n\nThe following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.\n\n| Client | Setup and callback guidance |\n| --- | --- |\n| [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. |\n| [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. |\n| [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. |\n| [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost:/oauth/callback` unless configured otherwise. |\n| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. |\n| [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. |\n| [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. |\n| [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. |\n\nDocumented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.\n\n## Disconnect\n\nOpen [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.\n\n## Troubleshooting\n\n| Symptom | What to do |\n| --- | --- |\n| Custom connector option missing | Check your client's plan and workspace-admin permissions. |\n| Published identity / CIMD unavailable or fails | Check the [metadata requirements](/mcp-cimd), or choose automatic registration / DCR if your client offers it. |\n| Connection request expired | Restart Connect from the client; do not reuse an old consent URL. |\n| Wrong Recoup account | Use Switch before approving. |\n| Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. |\n| Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. |\n| Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. |\n| `401` after disconnect | Expected: reconnect and approve a new grant. |\n| `429` | Respect `Retry-After`; avoid repeated registration attempts. |\n| `503` | Retry later; do not weaken authentication or callback checks. |\n| Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. |\n\nFor clients without OAuth, [API-key authentication](/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.\n\nFor help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys.\n\nFull OAuth MCP calls currently share account-level limits of 120 calls per minute\nand 30 calls per tool per minute across connected clients. See the\n[pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts).\nThe `compact_chats` MCP tool accepts up to 50 chats per call under the\n[pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts);\nthis is an MCP limit, not a claimed REST request limit.\n","headings":[{"title":"What your agent can do","id":"what-your-agent-can-do"},{"title":"Claude","id":"claude"},{"title":"ChatGPT","id":"chatgpt"},{"title":"Codex","id":"codex"},{"title":"Cursor","id":"cursor"},{"title":"Other agents and callbacks","id":"other-agents-and-callbacks"},{"title":"Disconnect","id":"disconnect"},{"title":"Troubleshooting","id":"troubleshooting"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Use this URL in your agent's remote MCP settings:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-text\",\n children: \"https://api.recoupable.dev/mcp\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Select \", _jsx(_components.strong, {\n children: \"OAuth\"\n }), \". Recoup supports \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"published client metadata (CIMD)\"\n }), \" and \", _jsx(_components.strong, {\n children: \"automatic registration\"\n }), \" (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-your-agent-can-do\",\n children: \"What your agent can do\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Request \", _jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"mcp:tools\"\n })\n }), \" for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Permission\"\n }), _jsx(_components.th, {\n children: \"Access\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:tools\"\n })\n }), _jsx(_components.td, {\n children: \"Full business-tool catalog across accessible workspaces\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:read\"\n })\n }), _jsxs(_components.td, {\n children: [\"Original personal-only \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \", \", _jsx(_components.code, {\n children: \"get_artist_socials\"\n }), \", \", _jsx(_components.code, {\n children: \"get_chats\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"mcp:write\"\n })\n }), _jsxs(_components.td, {\n children: [\"Original personal-only \", _jsx(_components.code, {\n children: \"create_new_artist\"\n }), \", \", _jsx(_components.code, {\n children: \"update_account_info\"\n })]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Existing limited grants do \", _jsx(_components.strong, {\n children: \"not\"\n }), \" expand automatically. Reconnect with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \", review the broader permission, and refresh your client's tool catalog. Clients requesting the \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" + \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" pair keep the five-tool experience.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"OAuth never exposes \", _jsx(_components.code, {\n children: \"get_api_key\"\n }), \": it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. \", _jsx(_components.code, {\n children: \"create_knowledge_base\"\n }), \" and \", _jsx(_components.code, {\n children: \"generate_txt_file\"\n }), \" publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound \", _jsx(_components.code, {\n children: \"id\"\n }), \"; pass that entire value as \", _jsx(_components.code, {\n children: \"video_id\"\n }), \" to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/oauth/connections\",\n children: \"Connected agents\"\n }), \" to revoke its access and refresh tokens immediately.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"claude\",\n children: \"Claude\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Open \", _jsx(_components.strong, {\n children: \"Customize → Connectors → Add custom connector\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Name it \", _jsx(_components.strong, {\n children: \"Recoup\"\n }), \" and enter the MCP URL above.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Choose \", _jsx(_components.strong, {\n children: \"Sign in now\"\n }), \". \", _jsx(_components.strong, {\n children: \"Register automatically\"\n }), \" uses DCR; \", _jsx(_components.strong, {\n children: \"published identity\"\n }), \" uses CIMD. The production client tests below used DCR.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Connect, sign in to Recoup, and select \", _jsx(_components.strong, {\n children: \"Allow access\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See \", _jsx(_components.a, {\n href: \"https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp\",\n children: \"Claude's remote connector guide\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"chatgpt\",\n children: \"ChatGPT\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"In the interface tested on October 7, 2026:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Open \", _jsx(_components.strong, {\n children: \"Plugins → Add → Add custom MCP server\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Enter \", _jsx(_components.strong, {\n children: \"Recoup\"\n }), \", the MCP URL, and \", _jsx(_components.strong, {\n children: \"OAuth\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Under advanced OAuth settings, confirm \", _jsx(_components.strong, {\n children: \"Dynamic Client Registration (DCR)\"\n }), \" and request \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for full access.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Create the plugin, connect it, and complete Recoup consent.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Start a chat with Recoup enabled and request an artist list.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see \", _jsx(_components.a, {\n href: \"https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt\",\n children: \"OpenAI's MCP setup documentation\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"codex\",\n children: \"Codex\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"codex mcp add recoup --url https://api.recoupable.dev/mcp\\ncodex mcp login recoup --scopes mcp:tools\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See \", _jsx(_components.a, {\n href: \"https://developers.openai.com/codex/mcp\",\n children: \"Codex MCP configuration\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"cursor\",\n children: \"Cursor\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Add a remote server to your project's \", _jsx(_components.code, {\n children: \".cursor/mcp.json\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"mcpServers\\\": {\\n \\\"recoup\\\": {\\n \\\"url\\\": \\\"https://api.recoupable.dev/mcp\\\"\\n }\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual \", _jsx(_components.code, {\n children: \"list_artists\"\n }), \" call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See \", _jsx(_components.a, {\n href: \"https://cursor.com/docs/mcp\",\n children: \"Cursor's MCP guide\"\n }), \" for the current setup and workspace restrictions.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"other-agents-and-callbacks\",\n children: \"Other agents and callbacks\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Resource metadata: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Authorization-server metadata: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Resource: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute \", _jsx(_components.code, {\n children: \"localhost\"\n }), \" for \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \" or edit a callback after registration.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"CIMD requirements and verification status\"\n }), \". Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"additional-client-setup-paths\",\n children: \"Additional client setup paths\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The following paths were reviewed in official client documentation on October 7, 2026. \", _jsx(_components.strong, {\n children: \"They have not been tested end to end against Recoup.\"\n }), \" Use automatic registration and request \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for full access, or \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" / \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Client\"\n }), _jsx(_components.th, {\n children: \"Setup and callback guidance\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors\",\n children: \"Perplexity\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are \", _jsx(_components.code, {\n children: \"https://www.perplexity.ai/rest/connections/oauth_callback\"\n }), \" and, for enterprise, \", _jsx(_components.code, {\n children: \"https://enterprise.perplexity.ai/rest/connections/oauth_callback\"\n }), \".\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://code.claude.com/docs/en/mcp\",\n children: \"Claude Code\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add Recoup as an HTTP server and authenticate through \", _jsx(_components.code, {\n children: \"/mcp\"\n }), \" inside Claude Code. Automatic registration uses a localhost callback; \", _jsx(_components.code, {\n children: \"--callback-port\"\n }), \" can fix its port when required.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization\",\n children: \"VS Code\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add an HTTP server in \", _jsx(_components.code, {\n children: \".vscode/mcp.json\"\n }), \". OAuth supports DCR; documented callbacks include \", _jsx(_components.code, {\n children: \"http://127.0.0.1:33418\"\n }), \" and \", _jsx(_components.code, {\n children: \"https://vscode.dev/redirect\"\n }), \". Preserve the callback supplied by your VS Code surface.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://geminicli.com/docs/tools/mcp-server/\",\n children: \"Gemini CLI\"\n })\n }), _jsxs(_components.td, {\n children: [\"Configure the MCP URL as \", _jsx(_components.code, {\n children: \"httpUrl\"\n }), \" and authenticate with \", _jsx(_components.code, {\n children: \"/mcp auth recoup\"\n }), \" inside the Gemini CLI chat. DCR uses \", _jsx(_components.code, {\n children: \"http://localhost:/oauth/callback\"\n }), \" unless configured otherwise.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://opencode.ai/docs/mcp-servers/\",\n children: \"OpenCode\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add a remote MCP server and run \", _jsx(_components.code, {\n children: \"opencode mcp auth recoup\"\n }), \". OAuth supports automatic registration. Let the client supply its callback.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://kiro.dev/docs/mcp/configuration/\",\n children: \"Kiro\"\n })\n }), _jsxs(_components.td, {\n children: [\"Add the remote MCP URL and use DCR. Set \", _jsx(_components.code, {\n children: \"oauth.oauthScopes\"\n }), \" to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://docs.n8n.io/integrations/builtin/credentials/mcp/\",\n children: \"n8n\"\n })\n }), _jsxs(_components.td, {\n children: [\"Create an MCP OAuth credential with \", _jsx(_components.strong, {\n children: \"Use Dynamic Client Registration\"\n }), \" enabled. Use the exact callback shown by your n8n instance.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent\",\n children: \"Copilot Studio\"\n })\n }), _jsx(_components.td, {\n children: \"Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio.\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"disconnect\",\n children: \"Disconnect\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Open \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/oauth/connections\",\n children: \"Connected agents\"\n }), \" and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"troubleshooting\",\n children: \"Troubleshooting\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Symptom\"\n }), _jsx(_components.th, {\n children: \"What to do\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Custom connector option missing\"\n }), _jsx(_components.td, {\n children: \"Check your client's plan and workspace-admin permissions.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Published identity / CIMD unavailable or fails\"\n }), _jsxs(_components.td, {\n children: [\"Check the \", _jsx(_components.a, {\n href: \"/mcp-cimd\",\n children: \"metadata requirements\"\n }), \", or choose automatic registration / DCR if your client offers it.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Connection request expired\"\n }), _jsx(_components.td, {\n children: \"Restart Connect from the client; do not reuse an old consent URL.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Wrong Recoup account\"\n }), _jsx(_components.td, {\n children: \"Use Switch before approving.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Still seeing only five tools\"\n }), _jsxs(_components.td, {\n children: [\"Reconnect requesting \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \", approve full access, then refresh the client tool catalog.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Connected but no tool access\"\n }), _jsx(_components.td, {\n children: \"Check selected scopes, individual tool approvals, and whether the grant expired or was revoked.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Organization artist missing\"\n }), _jsxs(_components.td, {\n children: [\"Reconnect with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" and verify your organization membership.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"401\"\n }), \" after disconnect\"]\n }), _jsx(_components.td, {\n children: \"Expected: reconnect and approve a new grant.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"429\"\n })\n }), _jsxs(_components.td, {\n children: [\"Respect \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \"; avoid repeated registration attempts.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"503\"\n })\n }), _jsx(_components.td, {\n children: \"Retry later; do not weaken authentication or callback checks.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Write timed out\"\n }), _jsx(_components.td, {\n children: \"Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate.\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For clients without OAuth, \", _jsx(_components.a, {\n href: \"/mcp\",\n children: \"API-key authentication\"\n }), \" remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For help, contact \", _jsx(_components.a, {\n href: \"mailto:agent@recoupable.dev\",\n children: \"agent@recoupable.dev\"\n }), \". Include the client name, time, and error text; never include tokens, passwords, or API keys.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Full OAuth MCP calls currently share account-level limits of 120 calls per minute\\nand 30 calls per tool per minute across connected clients. See the\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts\",\n children: \"pinned rate-limit implementation\"\n }), \".\\nThe \", _jsx(_components.code, {\n children: \"compact_chats\"\n }), \" MCP tool accepts up to 50 chats per call under the\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts\",\n children: \"pinned MCP guard\"\n }), \";\\nthis is an MCP limit, not a claimed REST request limit.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Connect an agent Connect an MCP client to Recoup with OAuth and account-authorized tools. Quickstart Getting started Use this URL in your agent's remote MCP settings: Select **OAuth**. Recoup supports [published client metadata (CIMD)](/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied. ## What your agent can do Request **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support. The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound. | Permission | Access | | --- | --- | | `mcp:tools` | Full business-tool catalog across accessible workspaces | | `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` | | `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` | Existing limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience. OAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog. Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs. The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification. New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately. Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected. ## Claude 1. Open **Customize → Connectors → Add custom connector**. 2. Name it **Recoup** and enter the MCP URL above. 3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR. 4. Connect, sign in to Recoup, and select **Allow access**. 5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted. Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward. Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). ## ChatGPT In the interface tested on October 7, 2026: 1. Open **Plugins → Add → Add custom MCP server**. 2. Enter **Recoup**, the MCP URL, and **OAuth**. 3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access. 4. Create the plugin, connect it, and complete Recoup consent. 5. Start a chat with Recoup enabled and request an artist list. ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt). ## Codex Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp). ## Cursor Add a remote server to your project's `.cursor/mcp.json`: Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions. ## Other agents and callbacks Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes: - Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp` - Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth` - Resource: `https://api.recoupable.dev/mcp` Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration. A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only. ### Additional client setup paths The following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist. | Client | Setup and callback guidance | | --- | --- | | [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. | | [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. | | [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. | | [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost: /oauth/callback` unless configured otherwise. | | [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. | | [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. | | [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. | | [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. | Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access. ## Disconnect Open [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again. ## Troubleshooting | Symptom | What to do | | --- | --- | | Custom connector option missing | Check your client's plan and workspace-admin permissions. | | Published identity / CIMD unavailable or fails | Check the [metadata requirements](/mcp-cimd), or choose automatic registration / DCR if your client offers it. | | Connection request expired | Restart Connect from the client; do not reuse an old consent URL. | | Wrong Recoup account | Use Switch before approving. | | Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. | | Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. | | Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. | | `401` after disconnect | Expected: reconnect and approve a new grant. | | `429` | Respect `Retry-After`; avoid repeated registration attempts. | | `503` | Retry later; do not weaken authentication or callback checks. | | Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. | For clients without OAuth, [API-key authentication](/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command. For help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys. Full OAuth MCP calls currently share account-level limits of 120 calls per minute and 30 calls per tool per minute across connected clients. See the [pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts). The `compact_chats` MCP tool accepts up to 50 chats per call under the [pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts); this is an MCP limit, not a claimed REST request limit. "},{"slug":"mcp-cimd","title":"Published client metadata (CIMD)","description":"Connect using an HTTPS client identity without dynamic registration.","category":"Quickstart","group":"Getting started","source":"mcp-cimd.mdx","body":"Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth `client_id`. Recoup retrieves that document and validates the client's callbacks before asking you to approve access.\n\nUse the same MCP server URL: `https://api.recoupable.dev/mcp`. A compatible client can discover CIMD through `client_id_metadata_document_supported: true` in Recoup's [authorization-server metadata](https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth). No vendor-specific registration or callback allowlist is needed.\n\n## Access and trust\n\nCIMD uses the same [permissions and consent](/mcp-oauth) as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work.\n\nA client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account.\n\n## Client requirements\n\n- Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected.\n- Set `client_id` to the exact document URL and include `client_name` and `redirect_uris`.\n- Use a document URL with an explicit path and without credentials, fragments, or dot path segments.\n- Use authorization code flow with PKCE S256 and `mcp:tools` for the full Recoup catalog, or `mcp:read` / `mcp:write` for the original limited personal tools.\n- Public clients should set `token_endpoint_auth_method` to `none`. Never publish client secrets or private keys.\n- Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. `localhost` and `127.0.0.1` remain different hosts.\n\nRecoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy.\n\nMetadata caching respects freshness headers up to five minutes. `no-store`, `no-cache`, absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata.\n\n## Verification status\n\nThe implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits.\n\nA local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on [Connect an agent](/mcp-oauth) were obtained using DCR.\n\nProduction verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified.\n\nIf a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored.\n\nSee the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and [CIMD draft 02](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html). CIMD remains a draft specification; Recoup's provider currently implements draft 02.\n","headings":[{"title":"Access and trust","id":"access-and-trust"},{"title":"Client requirements","id":"client-requirements"},{"title":"Verification status","id":"verification-status"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth \", _jsx(_components.code, {\n children: \"client_id\"\n }), \". Recoup retrieves that document and validates the client's callbacks before asking you to approve access.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the same MCP server URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \". A compatible client can discover CIMD through \", _jsx(_components.code, {\n children: \"client_id_metadata_document_supported: true\"\n }), \" in Recoup's \", _jsx(_components.a, {\n href: \"https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth\",\n children: \"authorization-server metadata\"\n }), \". No vendor-specific registration or callback allowlist is needed.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"access-and-trust\",\n children: \"Access and trust\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"CIMD uses the same \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"permissions and consent\"\n }), \" as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"client-requirements\",\n children: \"Client requirements\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Set \", _jsx(_components.code, {\n children: \"client_id\"\n }), \" to the exact document URL and include \", _jsx(_components.code, {\n children: \"client_name\"\n }), \" and \", _jsx(_components.code, {\n children: \"redirect_uris\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Use a document URL with an explicit path and without credentials, fragments, or dot path segments.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use authorization code flow with PKCE S256 and \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \" for the full Recoup catalog, or \", _jsx(_components.code, {\n children: \"mcp:read\"\n }), \" / \", _jsx(_components.code, {\n children: \"mcp:write\"\n }), \" for the original limited personal tools.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Public clients should set \", _jsx(_components.code, {\n children: \"token_endpoint_auth_method\"\n }), \" to \", _jsx(_components.code, {\n children: \"none\"\n }), \". Never publish client secrets or private keys.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. \", _jsx(_components.code, {\n children: \"localhost\"\n }), \" and \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \" remain different hosts.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Recoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Metadata caching respects freshness headers up to five minutes. \", _jsx(_components.code, {\n children: \"no-store\"\n }), \", \", _jsx(_components.code, {\n children: \"no-cache\"\n }), \", absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"verification-status\",\n children: \"Verification status\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"Connect an agent\"\n }), \" were obtained using DCR.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Production verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See the \", _jsx(_components.a, {\n href: \"https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization\",\n children: \"MCP authorization specification\"\n }), \" and \", _jsx(_components.a, {\n href: \"https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html\",\n children: \"CIMD draft 02\"\n }), \". CIMD remains a draft specification; Recoup's provider currently implements draft 02.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Published client metadata (CIMD) Connect using an HTTPS client identity without dynamic registration. Quickstart Getting started Recoup supports Client ID Metadata Documents (CIMD) alongside Dynamic Client Registration (DCR). A CIMD client uses the HTTPS URL of its public metadata document as its OAuth `client_id`. Recoup retrieves that document and validates the client's callbacks before asking you to approve access. Use the same MCP server URL: `https://api.recoupable.dev/mcp`. A compatible client can discover CIMD through `client_id_metadata_document_supported: true` in Recoup's [authorization-server metadata](https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth). No vendor-specific registration or callback allowlist is needed. ## Access and trust CIMD uses the same [permissions and consent](/mcp-oauth) as DCR. It does not bypass sign-in, PKCE, tool scope checks, grant expiry, or disconnection. Existing DCR connections continue to work. A client name or logo is self-declared metadata, not proof of vendor endorsement. Check the client identity and requested permissions before allowing access. Publishing a document does not authorize its client to access your account. ## Client requirements - Serve JSON with HTTP 200 over public HTTPS on port 443. Redirects are rejected. - Set `client_id` to the exact document URL and include `client_name` and `redirect_uris`. - Use a document URL with an explicit path and without credentials, fragments, or dot path segments. - Use authorization code flow with PKCE S256 and `mcp:tools` for the full Recoup catalog, or `mcp:read` / `mcp:write` for the original limited personal tools. - Public clients should set `token_endpoint_auth_method` to `none`. Never publish client secrets or private keys. - Register exact callbacks. Hosted HTTP callbacks are rejected; native loopback callbacks support dynamic ports. `localhost` and `127.0.0.1` remain different hosts. Recoup limits each metadata/JWKS response to 16 KiB and each fetch to 2.5 seconds, including DNS resolution and body transfer. It rejects private, loopback, reserved, and mixed public/private DNS results and pins connections to a validated address. Remote JWKS retrieval follows the same network policy. Metadata caching respects freshness headers up to five minutes. `no-store`, `no-cache`, absent freshness information, or expired freshness causes a new fetch. A failed refresh does not reuse expired metadata. ## Verification status The implementation has passed local production-provider tests for CIMD discovery, consent, token exchange, MCP access, refresh rotation, and revoked access. Network tests cover unsafe destinations, redirects, timeouts, response sizes, and concurrency limits. A local smoke test also retrieved the official Claude and Claude Code documents over real DNS/TLS, resolved them using the production provider, and checked Claude Code's dynamic loopback ports. This is metadata compatibility evidence, not a completed production user login through CIMD. The client-specific production results on [Connect an agent](/mcp-oauth) were obtained using DCR. Production verification on October 7, 2026 confirmed CIMD discovery with DCR still available and successfully started OAuth authorization interactions using the official Claude and Claude Code client IDs, including a dynamic localhost callback port. Completing user sign-in and a tool call through CIMD in production remains unverified. If a metadata host is unavailable or blocks server requests, CIMD fails closed. Use DCR if the client offers that choice, or retry after its metadata endpoint is restored. See the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) and [CIMD draft 02](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html). CIMD remains a draft specification; Recoup's provider currently implements draft 02. "},{"slug":"authentication","title":"Authentication","description":"How authentication works in the Recoup API — API keys, access tokens, and organization access control.","category":"Quickstart","group":"Getting started","source":"authentication.mdx","body":"## Overview\n\nEvery request to the Recoup API must be authenticated using exactly one of two mechanisms:\n\n| Method | Header | Use case |\n|--------|--------|----------|\n| API Key | `x-api-key` | Server-to-server integrations |\n| Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy |\n\nProviding both headers in the same request will result in a `401` error.\n\n\nAgent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details.\n\n\n---\n\n## API Keys\n\nAPI 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.\n\n### Creating an API Key\n\n1. Navigate to [chat.recoupable.dev/keys](https://chat.recoupable.dev/keys)\n2. Enter a descriptive name (e.g. `\"Production Server\"`)\n3. Click **Create API Key**\n\n\nCopy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation.\n\n\n### Using an API Key\n\nPass your key in the `x-api-key` header:\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n### Access to Organizations\n\nIf 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.\n\n- **No org membership** — the key can only access its own account's data\n- **Org member** — the key can pass `account_id` to filter to any account within that organization\n\n\nOrg 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.\n\n\n---\n\n## Access Tokens (Privy)\n\nIf 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.\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"Authorization: Bearer YOUR_PRIVY_JWT\"\n```\n\nThe 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.\n\n---\n\n## How We Verify Access on API Calls\n\nEvery authenticated request goes through `validateAuthContext`, which enforces the following access rules:\n\n### API Key or Bearer Token\n\nBy default, requests access the key owner's own account. When `account_id` is provided:\n\n```\nRequest includes account_id override?\n ├── Same as key owner → Allowed (self-access)\n ├── Key owner is a member of an org that contains account_id → Allowed\n └── No matching org membership → 403 Forbidden\n```\n\nMembership 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.\n\n\nThe Recoup internal admin organization has universal access to all accounts.\n\n\n### Organization Access via `organization_id`\n\nSome endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either:\n\n- A **member** of the organization, or\n- The **organization account itself**\n\n---\n\n## Error Responses\n\n| Status | Cause |\n|--------|-------|\n| `401` | Missing or invalid credentials, or both `x-api-key` and `Authorization` headers provided |\n| `403` | Valid credentials but insufficient access to the requested `account_id` or `organization_id` |\n\n---\n\n## Security Notes\n\n- API keys are **never stored in plaintext** — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database\n- **Never include `account_id` in your API key creation request** — the account is always derived from your authenticated credentials\n- Rotate keys immediately if compromised via the [API Keys Management Page](https://chat.recoupable.dev/keys)\n\n## MCP OAuth and REST credentials\n\nRemote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See [MCP OAuth](/mcp-oauth).\n","headings":[{"title":"Overview","id":"overview"},{"title":"API Keys","id":"api-keys"},{"title":"Access Tokens (Privy)","id":"access-tokens-privy"},{"title":"How We Verify Access on API Calls","id":"how-we-verify-access-on-api-calls"},{"title":"Error Responses","id":"error-responses"},{"title":"Security Notes","id":"security-notes"},{"title":"MCP OAuth and REST credentials","id":"mcp-oauth-and-rest-credentials"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n }, {Info, Note, Warning} = _components;\n if (!Info) _missingMdxReference(\"Info\", true);\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"overview\",\n children: \"Overview\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Every request to the Recoup API must be authenticated using exactly one of two mechanisms:\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Method\"\n }), _jsx(_components.th, {\n children: \"Header\"\n }), _jsx(_components.th, {\n children: \"Use case\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"API Key\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"x-api-key\"\n })\n }), _jsx(_components.td, {\n children: \"Server-to-server integrations\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Access Token\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"Authorization: Bearer \"\n })\n }), _jsx(_components.td, {\n children: \"Frontend apps authenticated via Privy\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Providing both headers in the same request will result in a \", _jsx(_components.code, {\n children: \"401\"\n }), \" error.\"]\n }), \"\\n\", _jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"Agent onboarding endpoints (\", _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" and \", _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \") are \", _jsx(_components.strong, {\n children: \"unauthenticated\"\n }), \" — they exist so agents can obtain their first API key. See the \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents guide\"\n }), \" for details.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"api-keys\",\n children: \"API Keys\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are \", _jsx(_components.strong, {\n children: \"personal keys\"\n }), \" — they are always tied to the account that created them.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"creating-an-api-key\",\n children: \"Creating an API Key\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Navigate to \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"chat.recoupable.dev/keys\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Enter a descriptive name (e.g. \", _jsx(_components.code, {\n children: \"\\\"Production Server\\\"\"\n }), \")\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Click \", _jsx(_components.strong, {\n children: \"Create API Key\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"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.\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"using-an-api-key\",\n children: \"Using an API Key\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass your key in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"access-to-organizations\",\n children: \"Access to Organizations\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If your account belongs to one or more organizations, your API key can access data across those organizations by passing an \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" parameter on supported endpoints. This lets you filter to any account within an organization your key has access to.\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"No org membership\"\n }), \" — the key can only access its own account's data\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Org member\"\n }), \" — the key can pass \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" to filter to any account within that organization\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(Info, {\n children: _jsxs(_components.p, {\n children: [\"Org membership is determined by the account's \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: \"organizations\"\n }), \". An account gains access to an org when it is added as a member.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"access-tokens-privy\",\n children: \"Access Tokens (Privy)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you're building a frontend application that authenticates users via \", _jsx(_components.a, {\n href: \"https://privy.io\",\n children: \"Privy\"\n }), \", you can pass the user's Privy JWT as a Bearer token instead of an API key.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"Authorization: Bearer YOUR_PRIVY_JWT\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"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.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"how-we-verify-access-on-api-calls\",\n children: \"How We Verify Access on API Calls\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Every authenticated request goes through \", _jsx(_components.code, {\n children: \"validateAuthContext\"\n }), \", which enforces the following access rules:\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"api-key-or-bearer-token\",\n children: \"API Key or Bearer Token\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"By default, requests access the key owner's own account. When \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" is provided:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"Request includes account_id override?\\n ├── Same as key owner → Allowed (self-access)\\n ├── Key owner is a member of an org that contains account_id → Allowed\\n └── No matching org membership → 403 Forbidden\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Membership is verified by checking the key owner's \", _jsx(_components.a, {\n href: \"/api-reference/organizations/list\",\n children: \"organizations\"\n }), \" for a record linking the account to the target account's organization.\"]\n }), \"\\n\", _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"The Recoup internal admin organization has universal access to all accounts.\"\n })\n }), \"\\n\", _jsxs(_components.h3, {\n id: \"organization-access-via-organizationid\",\n children: [\"Organization Access via \", _jsx(_components.code, {\n children: \"organization_id\"\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Some endpoints accept an \", _jsx(_components.code, {\n children: \"organization_id\"\n }), \" parameter. When provided, the API additionally validates that the authenticated account is either:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"A \", _jsx(_components.strong, {\n children: \"member\"\n }), \" of the organization, or\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The \", _jsx(_components.strong, {\n children: \"organization account itself\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"error-responses\",\n children: \"Error Responses\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Status\"\n }), _jsx(_components.th, {\n children: \"Cause\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"401\"\n })\n }), _jsxs(_components.td, {\n children: [\"Missing or invalid credentials, or both \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" and \", _jsx(_components.code, {\n children: \"Authorization\"\n }), \" headers provided\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"403\"\n })\n }), _jsxs(_components.td, {\n children: [\"Valid credentials but insufficient access to the requested \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" or \", _jsx(_components.code, {\n children: \"organization_id\"\n })]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"security-notes\",\n children: \"Security Notes\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"API keys are \", _jsx(_components.strong, {\n children: \"never stored in plaintext\"\n }), \" — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsxs(_components.strong, {\n children: [\"Never include \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" in your API key creation request\"]\n }), \" — the account is always derived from your authenticated credentials\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Rotate keys immediately if compromised via the \", _jsx(_components.a, {\n href: \"https://chat.recoupable.dev/keys\",\n children: \"API Keys Management Page\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"mcp-oauth-and-rest-credentials\",\n children: \"MCP OAuth and REST credentials\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Remote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Authentication How authentication works in the Recoup API — API keys, access tokens, and organization access control. Quickstart Getting started ## Overview Every request to the Recoup API must be authenticated using exactly one of two mechanisms: | Method | Header | Use case | |--------|--------|----------| | API Key | `x-api-key` | Server-to-server integrations | | Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy | Providing both headers in the same request will result in a `401` error. Agent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details. --- ## 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.dev/keys](https://chat.recoupable.dev/keys) 2. Enter a descriptive name (e.g. `\"Production Server\"`) 3. Click **Create API Key** Copy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation. ### Using an API Key Pass your key in the `x-api-key` header: ### 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 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. --- ## Access Tokens (Privy) If you're building a frontend application that authenticates users via [Privy](https://privy.io), you can pass the user's Privy JWT as a Bearer token instead of an API key. 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. --- ## How We Verify Access on API Calls Every authenticated request goes through `validateAuthContext`, which enforces the following access rules: ### API Key or Bearer Token By default, requests access the key owner's own account. When `account_id` is provided: Membership is verified by checking the key owner's [organizations](/api-reference/organizations/list) for a record linking the account to the target account's organization. The Recoup internal admin organization has universal access to all accounts. ### Organization Access via `organization_id` Some endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either: - A **member** of the organization, or - The **organization account itself** --- ## Error Responses | 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.dev/keys) ## MCP OAuth and REST credentials Remote MCP uses host-managed OAuth. Its tokens remain in the host and are not REST credentials to extract. Use a separate personal API key or application-provided Privy JWT (Bearer token) for REST-only operations. Never put a key in global instructions or use a disposable account to gain access to customer data. The authorized account and organization membership still control every request. See [MCP OAuth](/mcp-oauth). "},{"slug":"credits","title":"Credits","description":"How Recoup credits work — what's billed, how to check your balance, and how to upgrade.","category":"Quickstart","group":"Getting started","source":"credits.mdx","body":"Some Recoup endpoints are billed in **credits** — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates.\n\n---\n\n## What's billed\n\n| Family | Billed? | Notes |\n|--------|---------|-------|\n| **Research** ([`/api/research/*`](/api-reference/research/web)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). |\n| **Content generation** ([`/api/content/image`](/api-reference/content/generate-image), [`video`](/api-reference/content/generate-video), upscale, transcribe and analyze) | Yes | Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory. |\n| **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. |\n| **Music analysis** ([`POST /api/songs/analyze`](/api-reference/songs/analyze)) | Yes | \\$0.05 per model call plus \\$0.001166 per second of inference time; `full_report` is the sum of its 13 calls. |\n| **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | \\$0.05, plus \\$0.01 per post requested via `posts` — per social profile scraped. |\n| **Other operations** | Consult the endpoint contract | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. |\n\nUpstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient.\n\n---\n\n## What a credit is worth\n\n**Balances and prices are US dollars.** The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: `1,000,000 = $1.00`, so it can carry sub-cent charges (a \\$0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get).\n\n---\n\n## Check your balance\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/credits \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nResponse shape:\n\n```json\n{\n \"account_id\": \"11111111-1111-4111-8111-111111111111\",\n \"remaining_credits\": 292450000,\n \"total_credits\": 300000000,\n \"used_credits\": 7550000,\n \"is_pro\": true,\n \"plan\": \"pro\",\n \"task_limit\": null,\n \"min_cadence_minutes\": 60,\n \"timestamp\": \"2026-10-01T12:00:00Z\"\n}\n```\n\n`plan`, `task_limit`, and `min_cadence_minutes` describe the [plan](#subscription) the balance belongs to. `total_credits` is your plan-derived monthly allotment. `remaining_credits` can exceed `total_credits` after a top-up or an admin grant, and `used_credits` clamps to 0 in that case. Full schema at [Get Account Credits](/api-reference/accounts/credits-get).\n\n### Plan response examples\n\n`is_pro` on credits and `isPro` on subscriptions mean effective Pro, so both are\nfalse for paid Starter. Use `plan` to distinguish Starter from Free. The credits\nresponse reports the effective allowance; the [subscription response](/api-reference/accounts/subscription-get)\nseparately identifies whether it comes from the account or an organization.\n\n| Situation | Credits `plan` / `is_pro` | Subscription `source` | Task limit / minimum cadence |\n| --- | --- | --- | --- |\n| Free | `free` / `false` | `null` | 1 / weekly |\n| Paid Starter | `starter` / `false` | `account` | 3 / daily |\n| Direct Pro | `pro` / `true` | `account` | `null` (unlimited) / hourly |\n| Starter account with organization Pro | `pro` / `true` | `organization` | `null` (unlimited) / hourly |\n| Inactive subscription without another paid entitlement | `free` / `false` | `null` | 1 / weekly |\n\nFor example, a Pro balance of 325,000,000 against an allowance of 300,000,000\nreturns `used_credits: 0`. The API preserves a signed balance: a negative balance\ncan make this display exceed the allowance. This is not a ledger of charges.\nA null timestamp means the timestamp is unavailable, not proof of no prior activity.\nAn inactive subscription resolves to `status: \"none\"` and null subscription/billing\nfields; this endpoint does not return the canceled subscription's history. Billing\ndetails may also be unavailable on an active response. Named reference examples\nillustrate these states without quoting an available offer or a live payment.\n\nTo see what consumed the balance, list the charges line by line with [`GET /api/accounts/{id}/usage`](/api-reference/accounts/usage-get): one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in `model_id` (for example `POST /api/artist/socials/scrape`), so a list of charges reads as a list of calls.\n\n---\n\n## Subscription\n\nFor Platform, Advisory, Build + Partner, and Enterprise options, see [Recoup pricing](https://recoupable.dev/pricing). API and MCP usage is billed separately through credits.\n\nYour account's current credit allowance and scheduled-task limits are returned by [Get Account Credits](/api-reference/accounts/credits-get). Use `total_credits`, `task_limit`, and `min_cadence_minutes` from that response rather than inferring limits from a public plan name.\n\nThe API may return account identifiers such as `free`, `starter`, or `pro`. These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint.\n\n### Task limits\n\n[`POST /api/tasks`](/api-reference/tasks/create) and [`PATCH /api/tasks`](/api-reference/tasks/update) [check the plan](/api-reference/accounts/credits-get) before writing. Creating a task past `task_limit`, re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than `min_cadence_minutes` returns **HTTP 402** with `error: \"plan_limit\"`:\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"plan_limit\",\n \"limit\": \"task_count\",\n \"message\": \"Free includes 1 task. Starter includes 3, Pro is unlimited.\",\n \"plan\": \"free\",\n \"task_limit\": 1,\n \"min_cadence_minutes\": 10080,\n \"current_task_count\": 1,\n \"billingUrl\": \"https://app.recoupable.dev/plan\"\n}\n```\n\n`limit` is `task_count` or `min_cadence`; `current_task_count` excludes the task being created or updated. Edits that only touch `title`, `prompt`, or `model` never hit the gate.\n\n### Monthly refill\n\nThe refill is a **floor, not an assignment.** It raises `remaining_credits` up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a [top-up](#one-time-top-ups) or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar.\n\nThe refill is lazy rather than scheduled: it applies on the next read of [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get) once your credits row is more than a month old. The balance you read is always the refilled one.\n\n### Manage your subscription\n\nSign in to your [account billing page](https://app.recoupable.dev/plan) to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in [Create Subscription Session](/api-reference/subscriptions/sessions-create) and open its returned checkout URL. Review the price and billing terms before completing checkout.\n\nAdvisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment.\n\n### Check your tier\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/subscription \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nGet `$ACCOUNT_ID` from [`GET /api/accounts/id`](/api-reference/accounts/id) if you don't already have it. Response includes `isPro` (boolean), `status`, `plan`, and `source` (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at [Get Subscription](/api-reference/accounts/subscription-get).\n\n### One-time top-ups\n\nYou can purchase credits any time via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create). The endpoint adapts to what's on the account:\n\n- **Card on file → silent auto-charge.** Recoup charges your saved Stripe card off-session and returns `paymentIntentId`, `creditsPurchased`, and `totalCents`. Credits land within seconds.\n- **No card, or Stripe declines the saved card → Stripe Checkout fallback.** The response contains a Checkout `url` you open in the browser. When Stripe specifically declined a saved card, the response also includes a `declineReason` (e.g. `insufficient_funds`, `expired_card`) so you can explain *why* before sending the customer to update billing.\n\n```bash\ncurl -sS -X POST https://api.recoupable.dev/api/credits/sessions \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"credits\": 1000000, \"successUrl\": \"https://chat.recoupable.dev/credits/success\"}'\n```\n\nFull request/response schema at [Create Credits Top-Up Session](/api-reference/credits/sessions-create).\n\n### Check which card will be charged\n\nBefore triggering a silent off-session charge, inspect the default payment method on file:\n\n```bash\ncurl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/payment-method \\\n -H \"x-api-key: $RECOUP_API_KEY\"\n```\n\nResponse shape:\n\n```json\n{\n \"account_id\": \"11111111-1111-4111-8111-111111111111\",\n \"card\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"exp_month\": 12,\n \"exp_year\": 2026,\n \"funding\": \"credit\"\n }\n}\n```\n\n`card` is `null` when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original `exp_month` / `exp_year`); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at [Get Default Payment Method](/api-reference/accounts/payment-method-get).\n\n---\n\n## Running out of credits\n\nEvery billed API request runs a credit gate before it executes. If `remaining_credits` doesn't cover the request's cost, the request stops there and returns **HTTP 402**. Nothing is charged and no Stripe object is created.\n\nThe decision tree:\n\n1. **Enough credits?** → Request proceeds, credits deducted on success.\n2. **Short?** → Request returns **HTTP 402** with the balance, the cost, and a link to billing.\n\nA card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through [`POST /api/credits/sessions`](/api-reference/credits/sessions-create), or when the account has turned on auto top-up. Saving a card ahead of time via [`POST /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-create) makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on [`/api/accounts/{id}/subscription`](/api-reference/accounts/subscription-get), [`/api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-get), and [`/api/accounts/{id}/payments`](/api-reference/accounts/payments-get); pass an organization id as `{id}` to read the organization's billing.\n\n### Auto top-up (opt-in)\n\nAuto top-up is off for every account until it is turned on with [`PUT /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-update), which needs three things chosen by the account: `enabled`, the `amountCents` to buy each time (5.00 to 1,000.00 USD), and the `thresholdCents` balance that triggers it. Both are USD cents; the `remaining_credits` balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file.\n\nOnce on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as `lastError` (returned by [`GET /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-get)), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself.\n\n### Remove a saved card\n\n[`DELETE /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-delete) turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again.\n\nSuccess returns **204** with no body. If no customer or selected card exists, **404** leaves settings and cards unchanged. A **500** can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card.\n\nThis operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently.\n\n---\n\n## 402 Payment Required\n\nWhen the gate comes up short, billed endpoints return **HTTP 402** with a unified body:\n\n```json\n{\n \"error\": \"insufficient_credits\",\n \"remaining_credits\": 120000,\n \"required_credits\": 1000000,\n \"billingUrl\": \"https://app.recoupable.dev\"\n}\n```\n\n| Field | When it appears | Meaning |\n|-------|-----------------|---------|\n| `error` | Always | Literally `\"insufficient_credits\"` |\n| `remaining_credits` | Always | Account balance at the moment of the failed request |\n| `required_credits` | Always | What this endpoint needed |\n| `billingUrl` | Always | Static link to the Recoup app, where a human can save a card and buy credits |\n\n`billingUrl` is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running.\n\n**How to react:**\n\n- **Browser-driven UI** (e.g., the Recoup chat app): send the customer to `billingUrl`, or call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create) inline and open the `url` it returns.\n- **Programmatic / LLM-driven client**: report `remaining_credits` and `required_credits`, and surface `billingUrl` as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands.\n\n---\n\n## Cost per endpoint\n\nCurrent as of this revision of the page. The authoritative source is the per-endpoint reference docs and the `required_credits` field on any 402 response.\n\n| Endpoint | Cost |\n|----------|------|\n| [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | Variable, priced from the model's token usage; see `required_credits` on a 402 |\n| [Recoup artist and track research](/api-reference/research/search) | \\$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups |\n| [`POST /api/research/people`](/api-reference/research/people) | \\$0.05 per call |\n| [`POST /api/research/web`](/api-reference/research/web) | \\$0.01 per call |\n| [`POST /api/research/extract`](/api-reference/research/extract) | \\$0.05 × number of URLs |\n| [`POST /api/research/enrich`](/api-reference/research/enrich) | \\$0.05 / \\$0.10 / \\$0.25 (base / core / ultra processor) |\n| [`POST /api/research/deep`](/api-reference/research/deep) | \\$0.25 per call |\n| [`POST /api/image/generate`](/api-reference/image/generation) | Per-call price; see endpoint reference |\n| [`POST /api/songs/analyze`](/api-reference/songs/analyze) | `$0.05 + $0.001166 × elapsed_seconds` per model call; `full_report` = 13 calls |\n\n## Billing recovery and units\n\n`insufficient_credits` returns `billingUrl`, a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns `checkoutUrl`; subscription Checkout returns `url`. Inspect the endpoint-specific error type.\n\nTop-ups require `successUrl` on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; `totalCents` is 289 for that example. It is not a credit count. `isPro` means effective Pro only, and is false for paid Starter; use `plan` for paid-plan decisions.\n\nScheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names.\n","headings":[{"title":"What's billed","id":"whats-billed"},{"title":"What a credit is worth","id":"what-a-credit-is-worth"},{"title":"Check your balance","id":"check-your-balance"},{"title":"Subscription","id":"subscription"},{"title":"Running out of credits","id":"running-out-of-credits"},{"title":"402 Payment Required","id":"402-payment-required"},{"title":"Cost per endpoint","id":"cost-per-endpoint"},{"title":"Billing recovery and units","id":"billing-recovery-and-units"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Some Recoup endpoints are billed in \", _jsx(_components.strong, {\n children: \"credits\"\n }), \" — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"whats-billed\",\n children: \"What's billed\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Family\"\n }), _jsx(_components.th, {\n children: \"Billed?\"\n }), _jsx(_components.th, {\n children: \"Notes\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Research\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: _jsx(_components.code, {\n children: \"/api/research/*\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. \", _jsx(_components.a, {\n href: \"/api-reference/research/enrich\",\n children: _jsx(_components.code, {\n children: \"enrich\"\n })\n }), \" charges by processor tier; \", _jsx(_components.a, {\n href: \"/api-reference/research/extract\",\n children: _jsx(_components.code, {\n children: \"extract\"\n })\n }), \" charges by URL count).\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Content generation\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/content/generate-image\",\n children: _jsx(_components.code, {\n children: \"/api/content/image\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/content/generate-video\",\n children: _jsx(_components.code, {\n children: \"video\"\n })\n }), \", upscale, transcribe and analyze)\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"AI Chat — streaming\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/chat/workflow\",\n children: _jsx(_components.code, {\n children: \"POST /api/chat\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsx(_components.td, {\n children: \"Variable cost based on model token usage, with a per-request minimum.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Music analysis\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"$0.05 per model call plus $0.001166 per second of inference time; \", _jsx(_components.code, {\n children: \"full_report\"\n }), \" is the sum of its 13 calls.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.strong, {\n children: \"Social scrape\"\n }), \" (\", _jsx(_components.a, {\n href: \"/api-reference/social/scrape\",\n children: _jsx(_components.code, {\n children: \"/api/socials/{id}/scrape\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/artist/socials-scrape\",\n children: _jsx(_components.code, {\n children: \"/api/artist/socials/scrape\"\n })\n }), \")\"]\n }), _jsx(_components.td, {\n children: \"Yes\"\n }), _jsxs(_components.td, {\n children: [\"$0.05, plus $0.01 per post requested via \", _jsx(_components.code, {\n children: \"posts\"\n }), \" — per social profile scraped.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.strong, {\n children: \"Other operations\"\n })\n }), _jsx(_components.td, {\n children: \"Consult the endpoint contract\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/artists/list\",\n children: \"Artist CRUD\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: \"sandboxes\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/sessions/get\",\n children: \"sessions\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/tasks/get\",\n children: \"scheduled tasks\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: \"account/org management\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/agents/signup\",\n children: \"agent signup\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/spotify/search\",\n children: \"Spotify proxies\"\n }), \", etc. Subscription gating may still apply.\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Upstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"what-a-credit-is-worth\",\n children: \"What a credit is worth\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Balances and prices are US dollars.\"\n }), \" The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: \", _jsx(_components.code, {\n children: \"1,000,000 = $1.00\"\n }), \", so it can carry sub-cent charges (a $0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/credits\"\n })\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"check-your-balance\",\n children: \"Check your balance\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/credits \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response shape:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"11111111-1111-4111-8111-111111111111\\\",\\n \\\"remaining_credits\\\": 292450000,\\n \\\"total_credits\\\": 300000000,\\n \\\"used_credits\\\": 7550000,\\n \\\"is_pro\\\": true,\\n \\\"plan\\\": \\\"pro\\\",\\n \\\"task_limit\\\": null,\\n \\\"min_cadence_minutes\\\": 60,\\n \\\"timestamp\\\": \\\"2026-10-01T12:00:00Z\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"plan\"\n }), \", \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", and \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" describe the \", _jsx(_components.a, {\n href: \"#subscription\",\n children: \"plan\"\n }), \" the balance belongs to. \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \" is your plan-derived monthly allotment. \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" can exceed \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \" after a top-up or an admin grant, and \", _jsx(_components.code, {\n children: \"used_credits\"\n }), \" clamps to 0 in that case. Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"Get Account Credits\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"plan-response-examples\",\n children: \"Plan response examples\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"is_pro\"\n }), \" on credits and \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" on subscriptions mean effective Pro, so both are\\nfalse for paid Starter. Use \", _jsx(_components.code, {\n children: \"plan\"\n }), \" to distinguish Starter from Free. The credits\\nresponse reports the effective allowance; the \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: \"subscription response\"\n }), \"\\nseparately identifies whether it comes from the account or an organization.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Situation\"\n }), _jsxs(_components.th, {\n children: [\"Credits \", _jsx(_components.code, {\n children: \"plan\"\n }), \" / \", _jsx(_components.code, {\n children: \"is_pro\"\n })]\n }), _jsxs(_components.th, {\n children: [\"Subscription \", _jsx(_components.code, {\n children: \"source\"\n })]\n }), _jsx(_components.th, {\n children: \"Task limit / minimum cadence\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Free\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"free\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"null\"\n })\n }), _jsx(_components.td, {\n children: \"1 / weekly\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Paid Starter\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"starter\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"account\"\n })\n }), _jsx(_components.td, {\n children: \"3 / daily\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Direct Pro\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"pro\"\n }), \" / \", _jsx(_components.code, {\n children: \"true\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"account\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"null\"\n }), \" (unlimited) / hourly\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Starter account with organization Pro\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"pro\"\n }), \" / \", _jsx(_components.code, {\n children: \"true\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"organization\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"null\"\n }), \" (unlimited) / hourly\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Inactive subscription without another paid entitlement\"\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"free\"\n }), \" / \", _jsx(_components.code, {\n children: \"false\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"null\"\n })\n }), _jsx(_components.td, {\n children: \"1 / weekly\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For example, a Pro balance of 325,000,000 against an allowance of 300,000,000\\nreturns \", _jsx(_components.code, {\n children: \"used_credits: 0\"\n }), \". The API preserves a signed balance: a negative balance\\ncan make this display exceed the allowance. This is not a ledger of charges.\\nA null timestamp means the timestamp is unavailable, not proof of no prior activity.\\nAn inactive subscription resolves to \", _jsx(_components.code, {\n children: \"status: \\\"none\\\"\"\n }), \" and null subscription/billing\\nfields; this endpoint does not return the canceled subscription's history. Billing\\ndetails may also be unavailable on an active response. Named reference examples\\nillustrate these states without quoting an available offer or a live payment.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To see what consumed the balance, list the charges line by line with \", _jsx(_components.a, {\n href: \"/api-reference/accounts/usage-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/usage\"\n })\n }), \": one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in \", _jsx(_components.code, {\n children: \"model_id\"\n }), \" (for example \", _jsx(_components.code, {\n children: \"POST /api/artist/socials/scrape\"\n }), \"), so a list of charges reads as a list of calls.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"subscription\",\n children: \"Subscription\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For Platform, Advisory, Build + Partner, and Enterprise options, see \", _jsx(_components.a, {\n href: \"https://recoupable.dev/pricing\",\n children: \"Recoup pricing\"\n }), \". API and MCP usage is billed separately through credits.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Your account's current credit allowance and scheduled-task limits are returned by \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"Get Account Credits\"\n }), \". Use \", _jsx(_components.code, {\n children: \"total_credits\"\n }), \", \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", and \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" from that response rather than inferring limits from a public plan name.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The API may return account identifiers such as \", _jsx(_components.code, {\n children: \"free\"\n }), \", \", _jsx(_components.code, {\n children: \"starter\"\n }), \", or \", _jsx(_components.code, {\n children: \"pro\"\n }), \". These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"task-limits\",\n children: \"Task limits\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/tasks/create\",\n children: _jsx(_components.code, {\n children: \"POST /api/tasks\"\n })\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/tasks/update\",\n children: _jsx(_components.code, {\n children: \"PATCH /api/tasks\"\n })\n }), \" \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: \"check the plan\"\n }), \" before writing. Creating a task past \", _jsx(_components.code, {\n children: \"task_limit\"\n }), \", re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than \", _jsx(_components.code, {\n children: \"min_cadence_minutes\"\n }), \" returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with \", _jsx(_components.code, {\n children: \"error: \\\"plan_limit\\\"\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"status\\\": \\\"error\\\",\\n \\\"error\\\": \\\"plan_limit\\\",\\n \\\"limit\\\": \\\"task_count\\\",\\n \\\"message\\\": \\\"Free includes 1 task. Starter includes 3, Pro is unlimited.\\\",\\n \\\"plan\\\": \\\"free\\\",\\n \\\"task_limit\\\": 1,\\n \\\"min_cadence_minutes\\\": 10080,\\n \\\"current_task_count\\\": 1,\\n \\\"billingUrl\\\": \\\"https://app.recoupable.dev/plan\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"limit\"\n }), \" is \", _jsx(_components.code, {\n children: \"task_count\"\n }), \" or \", _jsx(_components.code, {\n children: \"min_cadence\"\n }), \"; \", _jsx(_components.code, {\n children: \"current_task_count\"\n }), \" excludes the task being created or updated. Edits that only touch \", _jsx(_components.code, {\n children: \"title\"\n }), \", \", _jsx(_components.code, {\n children: \"prompt\"\n }), \", or \", _jsx(_components.code, {\n children: \"model\"\n }), \" never hit the gate.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"monthly-refill\",\n children: \"Monthly refill\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The refill is a \", _jsx(_components.strong, {\n children: \"floor, not an assignment.\"\n }), \" It raises \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a \", _jsx(_components.a, {\n href: \"#one-time-top-ups\",\n children: \"top-up\"\n }), \" or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The refill is lazy rather than scheduled: it applies on the next read of \", _jsx(_components.a, {\n href: \"/api-reference/accounts/credits-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/credits\"\n })\n }), \" once your credits row is more than a month old. The balance you read is always the refilled one.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"manage-your-subscription\",\n children: \"Manage your subscription\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sign in to your \", _jsx(_components.a, {\n href: \"https://app.recoupable.dev/plan\",\n children: \"account billing page\"\n }), \" to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in \", _jsx(_components.a, {\n href: \"/api-reference/subscriptions/sessions-create\",\n children: \"Create Subscription Session\"\n }), \" and open its returned checkout URL. Review the price and billing terms before completing checkout.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Advisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"check-your-tier\",\n children: \"Check your tier\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/subscription \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Get \", _jsx(_components.code, {\n children: \"$ACCOUNT_ID\"\n }), \" from \", _jsx(_components.a, {\n href: \"/api-reference/accounts/id\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n })\n }), \" if you don't already have it. Response includes \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" (boolean), \", _jsx(_components.code, {\n children: \"status\"\n }), \", \", _jsx(_components.code, {\n children: \"plan\"\n }), \", and \", _jsx(_components.code, {\n children: \"source\"\n }), \" (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: \"Get Subscription\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"one-time-top-ups\",\n children: \"One-time top-ups\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"You can purchase credits any time via \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \". The endpoint adapts to what's on the account:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Card on file → silent auto-charge.\"\n }), \" Recoup charges your saved Stripe card off-session and returns \", _jsx(_components.code, {\n children: \"paymentIntentId\"\n }), \", \", _jsx(_components.code, {\n children: \"creditsPurchased\"\n }), \", and \", _jsx(_components.code, {\n children: \"totalCents\"\n }), \". Credits land within seconds.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"No card, or Stripe declines the saved card → Stripe Checkout fallback.\"\n }), \" The response contains a Checkout \", _jsx(_components.code, {\n children: \"url\"\n }), \" you open in the browser. When Stripe specifically declined a saved card, the response also includes a \", _jsx(_components.code, {\n children: \"declineReason\"\n }), \" (e.g. \", _jsx(_components.code, {\n children: \"insufficient_funds\"\n }), \", \", _jsx(_components.code, {\n children: \"expired_card\"\n }), \") so you can explain \", _jsx(_components.em, {\n children: \"why\"\n }), \" before sending the customer to update billing.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS -X POST https://api.recoupable.dev/api/credits/sessions \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"credits\\\": 1000000, \\\"successUrl\\\": \\\"https://chat.recoupable.dev/credits/success\\\"}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Full request/response schema at \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: \"Create Credits Top-Up Session\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"check-which-card-will-be-charged\",\n children: \"Check which card will be charged\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before triggering a silent off-session charge, inspect the default payment method on file:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS https://api.recoupable.dev/api/accounts/$ACCOUNT_ID/payment-method \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response shape:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"11111111-1111-4111-8111-111111111111\\\",\\n \\\"card\\\": {\\n \\\"brand\\\": \\\"visa\\\",\\n \\\"last4\\\": \\\"4242\\\",\\n \\\"exp_month\\\": 12,\\n \\\"exp_year\\\": 2026,\\n \\\"funding\\\": \\\"credit\\\"\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"card\"\n }), \" is \", _jsx(_components.code, {\n children: \"null\"\n }), \" when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original \", _jsx(_components.code, {\n children: \"exp_month\"\n }), \" / \", _jsx(_components.code, {\n children: \"exp_year\"\n }), \"); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-get\",\n children: \"Get Default Payment Method\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"running-out-of-credits\",\n children: \"Running out of credits\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Every billed API request runs a credit gate before it executes. If \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" doesn't cover the request's cost, the request stops there and returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \". Nothing is charged and no Stripe object is created.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The decision tree:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Enough credits?\"\n }), \" → Request proceeds, credits deducted on success.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Short?\"\n }), \" → Request returns \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with the balance, the cost, and a link to billing.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \", or when the account has turned on auto top-up. Saving a card ahead of time via \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/accounts/{id}/payment-method\"\n })\n }), \" makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on \", _jsx(_components.a, {\n href: \"/api-reference/accounts/subscription-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/subscription\"\n })\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/payment-method\"\n })\n }), \", and \", _jsx(_components.a, {\n href: \"/api-reference/accounts/payments-get\",\n children: _jsx(_components.code, {\n children: \"/api/accounts/{id}/payments\"\n })\n }), \"; pass an organization id as \", _jsx(_components.code, {\n children: \"{id}\"\n }), \" to read the organization's billing.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"auto-top-up-opt-in\",\n children: \"Auto top-up (opt-in)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Auto top-up is off for every account until it is turned on with \", _jsx(_components.a, {\n href: \"/api-reference/accounts/auto-top-up-update\",\n children: _jsx(_components.code, {\n children: \"PUT /api/accounts/{id}/auto-top-up\"\n })\n }), \", which needs three things chosen by the account: \", _jsx(_components.code, {\n children: \"enabled\"\n }), \", the \", _jsx(_components.code, {\n children: \"amountCents\"\n }), \" to buy each time (5.00 to 1,000.00 USD), and the \", _jsx(_components.code, {\n children: \"thresholdCents\"\n }), \" balance that triggers it. Both are USD cents; the \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as \", _jsx(_components.code, {\n children: \"lastError\"\n }), \" (returned by \", _jsx(_components.a, {\n href: \"/api-reference/accounts/auto-top-up-get\",\n children: _jsx(_components.code, {\n children: \"GET /api/accounts/{id}/auto-top-up\"\n })\n }), \"), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"remove-a-saved-card\",\n children: \"Remove a saved card\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/accounts/payment-method-delete\",\n children: _jsx(_components.code, {\n children: \"DELETE /api/accounts/{id}/payment-method\"\n })\n }), \" turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Success returns \", _jsx(_components.strong, {\n children: \"204\"\n }), \" with no body. If no customer or selected card exists, \", _jsx(_components.strong, {\n children: \"404\"\n }), \" leaves settings and cards unchanged. A \", _jsx(_components.strong, {\n children: \"500\"\n }), \" can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently.\"\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"402-payment-required\",\n children: \"402 Payment Required\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"When the gate comes up short, billed endpoints return \", _jsx(_components.strong, {\n children: \"HTTP 402\"\n }), \" with a unified body:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"error\\\": \\\"insufficient_credits\\\",\\n \\\"remaining_credits\\\": 120000,\\n \\\"required_credits\\\": 1000000,\\n \\\"billingUrl\\\": \\\"https://app.recoupable.dev\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Field\"\n }), _jsx(_components.th, {\n children: \"When it appears\"\n }), _jsx(_components.th, {\n children: \"Meaning\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"error\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsxs(_components.td, {\n children: [\"Literally \", _jsx(_components.code, {\n children: \"\\\"insufficient_credits\\\"\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"remaining_credits\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"Account balance at the moment of the failed request\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"required_credits\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"What this endpoint needed\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"billingUrl\"\n })\n }), _jsx(_components.td, {\n children: \"Always\"\n }), _jsx(_components.td, {\n children: \"Static link to the Recoup app, where a human can save a card and buy credits\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"billingUrl\"\n }), \" is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"How to react:\"\n })\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Browser-driven UI\"\n }), \" (e.g., the Recoup chat app): send the customer to \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \", or call \", _jsx(_components.a, {\n href: \"/api-reference/credits/sessions-create\",\n children: _jsx(_components.code, {\n children: \"POST /api/credits/sessions\"\n })\n }), \" inline and open the \", _jsx(_components.code, {\n children: \"url\"\n }), \" it returns.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Programmatic / LLM-driven client\"\n }), \": report \", _jsx(_components.code, {\n children: \"remaining_credits\"\n }), \" and \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \", and surface \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \" as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"cost-per-endpoint\",\n children: \"Cost per endpoint\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Current as of this revision of the page. The authoritative source is the per-endpoint reference docs and the \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \" field on any 402 response.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Endpoint\"\n }), _jsx(_components.th, {\n children: \"Cost\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.a, {\n href: \"/api-reference/chat/workflow\",\n children: _jsx(_components.code, {\n children: \"POST /api/chat\"\n })\n }), \" (streaming)\"]\n }), _jsxs(_components.td, {\n children: [\"Variable, priced from the model's token usage; see \", _jsx(_components.code, {\n children: \"required_credits\"\n }), \" on a 402\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/search\",\n children: \"Recoup artist and track research\"\n })\n }), _jsx(_components.td, {\n children: \"$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/people\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/people\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/web\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.01 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/extract\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/extract\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 × number of URLs\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/enrich\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/enrich\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.05 / $0.10 / $0.25 (base / core / ultra processor)\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/deep\",\n children: _jsx(_components.code, {\n children: \"POST /api/research/deep\"\n })\n })\n }), _jsx(_components.td, {\n children: \"$0.25 per call\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/image/generation\",\n children: _jsx(_components.code, {\n children: \"POST /api/image/generate\"\n })\n })\n }), _jsx(_components.td, {\n children: \"Per-call price; see endpoint reference\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/songs/analyze\",\n children: _jsx(_components.code, {\n children: \"POST /api/songs/analyze\"\n })\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"$0.05 + $0.001166 × elapsed_seconds\"\n }), \" per model call; \", _jsx(_components.code, {\n children: \"full_report\"\n }), \" = 13 calls\"]\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"billing-recovery-and-units\",\n children: \"Billing recovery and units\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"insufficient_credits\"\n }), \" returns \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \", a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns \", _jsx(_components.code, {\n children: \"checkoutUrl\"\n }), \"; subscription Checkout returns \", _jsx(_components.code, {\n children: \"url\"\n }), \". Inspect the endpoint-specific error type.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Top-ups require \", _jsx(_components.code, {\n children: \"successUrl\"\n }), \" on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; \", _jsx(_components.code, {\n children: \"totalCents\"\n }), \" is 289 for that example. It is not a credit count. \", _jsx(_components.code, {\n children: \"isPro\"\n }), \" means effective Pro only, and is false for paid Starter; use \", _jsx(_components.code, {\n children: \"plan\"\n }), \" for paid-plan decisions.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Scheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Credits How Recoup credits work — what's billed, how to check your balance, and how to upgrade. Quickstart Getting started Some Recoup endpoints are billed in **credits** — primarily endpoints that hit external data providers, run AI inference, or generate content. Check the specific endpoint contract for other charges and subscription gates. --- ## What's billed | Family | Billed? | Notes | |--------|---------|-------| | **Research** ([`/api/research/*`](/api-reference/research/web)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). | | **Content generation** ([`/api/content/image`](/api-reference/content/generate-image), [`video`](/api-reference/content/generate-video), upscale, transcribe and analyze) | Yes | Model-specific generation and inference charges apply. Hosted pipelines charge their component operations; estimates are advisory. | | **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. | | **Music analysis** ([`POST /api/songs/analyze`](/api-reference/songs/analyze)) | Yes | \\$0.05 per model call plus \\$0.001166 per second of inference time; `full_report` is the sum of its 13 calls. | | **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | \\$0.05, plus \\$0.01 per post requested via `posts` — per social profile scraped. | | **Other operations** | Consult the endpoint contract | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. | Upstream generation or inference may incur cost even if a later composition or delivery step fails. Do not infer zero spend from the final pipeline status; inspect usage events. Credit gates reject before provider work when the balance is insufficient. --- ## What a credit is worth **Balances and prices are US dollars.** The ledger stores amounts as integer micro-dollars, the same 6-decimal unit as USDC: `1,000,000 = $1.00`, so it can carry sub-cent charges (a \\$0.002/s provider rate prices exactly). Every credit field the API returns is that integer; divide by 1,000,000 to display it as currency. Example: [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get). --- ## Check your balance Response shape: `plan`, `task_limit`, and `min_cadence_minutes` describe the [plan](#subscription) the balance belongs to. `total_credits` is your plan-derived monthly allotment. `remaining_credits` can exceed `total_credits` after a top-up or an admin grant, and `used_credits` clamps to 0 in that case. Full schema at [Get Account Credits](/api-reference/accounts/credits-get). ### Plan response examples `is_pro` on credits and `isPro` on subscriptions mean effective Pro, so both are false for paid Starter. Use `plan` to distinguish Starter from Free. The credits response reports the effective allowance; the [subscription response](/api-reference/accounts/subscription-get) separately identifies whether it comes from the account or an organization. | Situation | Credits `plan` / `is_pro` | Subscription `source` | Task limit / minimum cadence | | --- | --- | --- | --- | | Free | `free` / `false` | `null` | 1 / weekly | | Paid Starter | `starter` / `false` | `account` | 3 / daily | | Direct Pro | `pro` / `true` | `account` | `null` (unlimited) / hourly | | Starter account with organization Pro | `pro` / `true` | `organization` | `null` (unlimited) / hourly | | Inactive subscription without another paid entitlement | `free` / `false` | `null` | 1 / weekly | For example, a Pro balance of 325,000,000 against an allowance of 300,000,000 returns `used_credits: 0`. The API preserves a signed balance: a negative balance can make this display exceed the allowance. This is not a ledger of charges. A null timestamp means the timestamp is unavailable, not proof of no prior activity. An inactive subscription resolves to `status: \"none\"` and null subscription/billing fields; this endpoint does not return the canceled subscription's history. Billing details may also be unavailable on an active response. Named reference examples illustrate these states without quoting an available offer or a live payment. To see what consumed the balance, list the charges line by line with [`GET /api/accounts/{id}/usage`](/api-reference/accounts/usage-get): one item per deduction, newest first, each with the amount in micro-dollars and as a dollar string, plus the total for the period. API charges name the endpoint that billed them in `model_id` (for example `POST /api/artist/socials/scrape`), so a list of charges reads as a list of calls. --- ## Subscription For Platform, Advisory, Build + Partner, and Enterprise options, see [Recoup pricing](https://recoupable.dev/pricing). API and MCP usage is billed separately through credits. Your account's current credit allowance and scheduled-task limits are returned by [Get Account Credits](/api-reference/accounts/credits-get). Use `total_credits`, `task_limit`, and `min_cadence_minutes` from that response rather than inferring limits from a public plan name. The API may return account identifiers such as `free`, `starter`, or `pro`. These are documented API values; they are not the names of consulting engagements. The request and response schemas define the values accepted by each endpoint. ### Task limits [`POST /api/tasks`](/api-reference/tasks/create) and [`PATCH /api/tasks`](/api-reference/tasks/update) [check the plan](/api-reference/accounts/credits-get) before writing. Creating a task past `task_limit`, re-enabling a disabled task past it, or saving a cron whose consecutive runs are closer together than `min_cadence_minutes` returns **HTTP 402** with `error: \"plan_limit\"`: `limit` is `task_count` or `min_cadence`; `current_task_count` excludes the task being created or updated. Edits that only touch `title`, `prompt`, or `model` never hit the gate. ### Monthly refill The refill is a **floor, not an assignment.** It raises `remaining_credits` up to your plan's monthly total and never lowers it. A balance already above the plan total, whether from a [top-up](#one-time-top-ups) or an admin grant, is left exactly as it is, so credits you bought or were granted are never taken away by the calendar. The refill is lazy rather than scheduled: it applies on the next read of [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get) once your credits row is more than a month old. The balance you read is always the refilled one. ### Manage your subscription Sign in to your [account billing page](https://app.recoupable.dev/plan) to review your subscription, price, and current terms. For programmatic checkout, use the accepted request values in [Create Subscription Session](/api-reference/subscriptions/sessions-create) and open its returned checkout URL. Review the price and billing terms before completing checkout. Advisory and custom-build engagements begin with a conversation about scope. Their website plan selection does not create an API subscription or complete a payment. ### Check your tier Get `$ACCOUNT_ID` from [`GET /api/accounts/id`](/api-reference/accounts/id) if you don't already have it. Response includes `isPro` (boolean), `status`, `plan`, and `source` (whether the subscription comes from the account itself or an organization the account belongs to). Full schema at [Get Subscription](/api-reference/accounts/subscription-get). ### One-time top-ups You can purchase credits any time via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create). The endpoint adapts to what's on the account: - **Card on file → silent auto-charge.** Recoup charges your saved Stripe card off-session and returns `paymentIntentId`, `creditsPurchased`, and `totalCents`. Credits land within seconds. - **No card, or Stripe declines the saved card → Stripe Checkout fallback.** The response contains a Checkout `url` you open in the browser. When Stripe specifically declined a saved card, the response also includes a `declineReason` (e.g. `insufficient_funds`, `expired_card`) so you can explain *why* before sending the customer to update billing. Full request/response schema at [Create Credits Top-Up Session](/api-reference/credits/sessions-create). ### Check which card will be charged Before triggering a silent off-session charge, inspect the default payment method on file: Response shape: `card` is `null` when this lookup finds no supported default card, including when no tagged Stripe customer exists. It does not establish whether a card was saved previously or whether other saved cards remain. Removing one selected card can leave others available; read the current card and auto-top-up settings before deciding how to proceed. Expired cards are still returned (with their original `exp_month` / `exp_year`); callers should compare against the current date and warn the customer, since an off-session charge against an expired card will decline. Full schema at [Get Default Payment Method](/api-reference/accounts/payment-method-get). --- ## Running out of credits Every billed API request runs a credit gate before it executes. If `remaining_credits` doesn't cover the request's cost, the request stops there and returns **HTTP 402**. Nothing is charged and no Stripe object is created. The decision tree: 1. **Enough credits?** → Request proceeds, credits deducted on success. 2. **Short?** → Request returns **HTTP 402** with the balance, the cost, and a link to billing. A card on the account is never charged on its own. Charging happens only when the account asks to buy credits, through [`POST /api/credits/sessions`](/api-reference/credits/sessions-create), or when the account has turned on auto top-up. Saving a card ahead of time via [`POST /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-create) makes a one-time purchase a single call instead of a browser round-trip; it does not authorize a charge by itself. Your plan, card, and every payment are on [`/api/accounts/{id}/subscription`](/api-reference/accounts/subscription-get), [`/api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-get), and [`/api/accounts/{id}/payments`](/api-reference/accounts/payments-get); pass an organization id as `{id}` to read the organization's billing. ### Auto top-up (opt-in) Auto top-up is off for every account until it is turned on with [`PUT /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-update), which needs three things chosen by the account: `enabled`, the `amountCents` to buy each time (5.00 to 1,000.00 USD), and the `thresholdCents` balance that triggers it. Both are USD cents; the `remaining_credits` balance above is in credit micro-dollars, so divide it by 10,000 to compare. Turning it on requires a card on file. Once on, the first credit deduction that leaves the balance below the threshold charges the card for the amount, grants the credits, records a usage event, and emails a receipt. Guardrails: at most one top-up per account per 10 minutes; a card decline turns auto top-up off, records the decline message as `lastError` (returned by [`GET /api/accounts/{id}/auto-top-up`](/api-reference/accounts/auto-top-up-get)), and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other cards remain. Auto top-up never creates a checkout session and never touches an invoiced (enterprise) plan. Saving a card does not turn auto top-up on by itself. ### Remove a saved card [`DELETE /api/accounts/{id}/payment-method`](/api-reference/accounts/payment-method-delete) turns off automatic credit purchases, then removes the selected saved card. It removes one card, preserving other cards, balances, and configured amounts and thresholds. It does not cancel subscriptions or invoices. Other saved cards can still appear in a later card read and fund a purchase you explicitly request; removal does not silently enable automatic purchases again. Success returns **204** with no body. If no customer or selected card exists, **404** leaves settings and cards unchanged. A **500** can mean the settings save failed before card removal, or that settings were saved but detachment failed; in the latter case automatic purchases stay off. Read the current card and auto-top-up settings before retrying an error or uncertain response. Repeating DELETE after a completed removal may select and remove another card. This operation does not cancel a charge already in progress or prevent someone from explicitly changing the settings concurrently. --- ## 402 Payment Required When the gate comes up short, billed endpoints return **HTTP 402** with a unified body: | Field | When it appears | Meaning | |-------|-----------------|---------| | `error` | Always | Literally `\"insufficient_credits\"` | | `remaining_credits` | Always | Account balance at the moment of the failed request | | `required_credits` | Always | What this endpoint needed | | `billingUrl` | Always | Static link to the Recoup app, where a human can save a card and buy credits | `billingUrl` is a constant, not a freshly minted Stripe Checkout Session. Retrying a credit-gated endpoint returns the same URL every time and creates nothing, so an unattended client that keeps hitting the gate is safe to leave running. **How to react:** - **Browser-driven UI** (e.g., the Recoup chat app): send the customer to `billingUrl`, or call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create) inline and open the `url` it returns. - **Programmatic / LLM-driven client**: report `remaining_credits` and `required_credits`, and surface `billingUrl` as the link a human needs to visit. Do not treat a 402 as retryable; the balance will not change on its own until someone buys credits or the monthly refill lands. --- ## Cost per endpoint Current as of this revision of the page. The authoritative source is the per-endpoint reference docs and the `required_credits` field on any 402 response. | Endpoint | Cost | |----------|------| | [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | Variable, priced from the model's token usage; see `required_credits` on a 402 | | [Recoup artist and track research](/api-reference/research/search) | \\$0.05 per successful research call (50,000 credits); track-name resolution can add separately charged provider lookups | | [`POST /api/research/people`](/api-reference/research/people) | \\$0.05 per call | | [`POST /api/research/web`](/api-reference/research/web) | \\$0.01 per call | | [`POST /api/research/extract`](/api-reference/research/extract) | \\$0.05 × number of URLs | | [`POST /api/research/enrich`](/api-reference/research/enrich) | \\$0.05 / \\$0.10 / \\$0.25 (base / core / ultra processor) | | [`POST /api/research/deep`](/api-reference/research/deep) | \\$0.25 per call | | [`POST /api/image/generate`](/api-reference/image/generation) | Per-call price; see endpoint reference | | [`POST /api/songs/analyze`](/api-reference/songs/analyze) | `$0.05 + $0.001166 × elapsed_seconds` per model call; `full_report` = 13 calls | ## Billing recovery and units `insufficient_credits` returns `billingUrl`, a static app link, not a Stripe Checkout session. Stop and surface it; do not silently retry or initiate a charge. The separate historical measurement card-setup gate returns `checkoutUrl`; subscription Checkout returns `url`. Inspect the endpoint-specific error type. Top-ups require `successUrl` on every request and a positive whole-cent multiple of 10,000 micro-dollar credits. For example, 2,500,000 credits buys $2.50 before fees; `totalCents` is 289 for that example. It is not a credit count. `isPro` means effective Pro only, and is false for paid Starter; use `plan` for paid-plan decisions. Scheduled task creation and updates can return a plan-limit 402; task reads do not run that gate. Free/Starter/Pro are technical entitlement values. Platform/Advisory/Build/Enterprise marketing offers describe commercial services; they are not interchangeable names. "},{"slug":"research-availability","title":"Research availability","description":"Explore Recoup research, choose the right identifiers, and handle incomplete data.","category":"Quickstart","group":"Getting started","source":"research-availability.mdx","body":"Recoup Research lets you discover artists and tracks, read current metrics,\nexplore audience and playlist activity, and capture recording measurements.\nAuthenticate with your Recoup API key or supported bearer credential. Recoup\nmanages the data connections; you do not need a separate data-service key.\n\nCoverage varies by artist, recording, platform and metric. An empty result means\nno matching data was returned; it does not prove an artist has no activity or audience.\n\n## Choose an identifier\n\nSearch by name, inspect the matches, and pass the selected result's `id` to the\ndetail endpoints. Treat research IDs as opaque strings: do not parse them or\nsubstitute a Recoup account UUID. Artist-name shortcuts use the first match;\nselect an explicit ID when names are ambiguous.\n\nFor portable recording references, store the ISRC and available Spotify or\nApple Music identifiers. Additional response fields and provenance labels may\nvary as Recoup's data connections change. Preserve returned provenance for\ntraceability without using it to choose a data vendor.\n\n## Current track statistics\n\nSupply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus\nthe required `source` (the platform, such as `spotify`). Recoup uses stored\nSpotify measurements when available for an ISRC, and otherwise requests current\nresearch data. Preserve `data_source` and capture timestamps when returned;\nmissing provenance remains unknown. A displayed play count is not a verified\nroyalty-bearing stream count.\n\n## Research endpoints\n\n| Method | Path | Reference |\n| --- | --- | --- |\n| GET | `/api/research` | [Search](/api-reference/research/search) |\n| GET | `/api/research/albums` | [Albums](/api-reference/research/albums) |\n| GET | `/api/research/audience` | [Audience](/api-reference/research/audience) |\n| GET | `/api/research/career` | [Career activities](/api-reference/research/career) |\n| GET | `/api/research/insights` | [Insights activities](/api-reference/research/insights) |\n| GET | `/api/research/lookup` | [Spotify artist lookup](/api-reference/research/lookup) |\n| GET | `/api/research/metrics` | [Current artist metrics](/api-reference/research/metrics) |\n| GET | `/api/research/milestones` | [Milestones](/api-reference/research/milestones) |\n| GET | `/api/research/playlists` | [Artist playlists](/api-reference/research/playlists) |\n| GET | `/api/research/profile` | [Artist profile](/api-reference/research/profile) |\n| GET | `/api/research/similar` | [Related artists](/api-reference/research/similar) |\n| GET | `/api/research/track` | [Track details](/api-reference/research/track) |\n| GET | `/api/research/track/playlists` | [Track playlists](/api-reference/research/track-playlists) |\n| GET | `/api/research/tracks` | [Artist tracks](/api-reference/research/tracks) |\n| GET | `/api/research/urls` | [Platform URLs](/api-reference/research/urls) |\n\n## Understand the results\n\n- Artist metrics are current snapshots. Save dated results to compare them over time.\n- Related artists are unweighted; the accepted similarity axes do not change the ranking.\n- Artist playlist `status=past` uses all-time scope and can include current placements.\n- Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.\n- Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.\n- Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.\n\n## Historical measurement jobs\n\n`POST /api/research/measurement-jobs` supports `source: \"historical\"`\nfor Spotify backfill. It requires a card on file and returns queue counts with\n`id: null`; enqueueing does not confirm capture completion. Recordings with an\nexisting historical research measurement can be skipped even when their history\nis partial. Inspect the available dates before claiming complete coverage.\nCurrent capture jobs return a snapshot ID.\n\n## Costs and unavailable data\n\nSuccessful research calls cost $0.05 (50,000 micro-dollar credits). Track-name\nresolution can add separately charged lookup calls; reuse a selected research\nID when available. Historical enqueue itself does not deduct research credits;\ncapture work has its own balance and budget checks.\n\nFor `402 insufficient_credits`, show the returned `billingUrl`. Surface `429`\nand unavailable-data errors; use bounded retries for transient failures and stop\nwhen the request cannot be served. Recoup does not promise a `Retry-After` header\non these routes. Never fill a missing metric with an invented number or zero.\n","headings":[{"title":"Choose an identifier","id":"choose-an-identifier"},{"title":"Current track statistics","id":"current-track-statistics"},{"title":"Research endpoints","id":"research-endpoints"},{"title":"Understand the results","id":"understand-the-results"},{"title":"Historical measurement jobs","id":"historical-measurement-jobs"},{"title":"Costs and unavailable data","id":"costs-and-unavailable-data"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Recoup Research lets you discover artists and tracks, read current metrics,\\nexplore audience and playlist activity, and capture recording measurements.\\nAuthenticate with your Recoup API key or supported bearer credential. Recoup\\nmanages the data connections; you do not need a separate data-service key.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Coverage varies by artist, recording, platform and metric. An empty result means\\nno matching data was returned; it does not prove an artist has no activity or audience.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"choose-an-identifier\",\n children: \"Choose an identifier\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Search by name, inspect the matches, and pass the selected result's \", _jsx(_components.code, {\n children: \"id\"\n }), \" to the\\ndetail endpoints. Treat research IDs as opaque strings: do not parse them or\\nsubstitute a Recoup account UUID. Artist-name shortcuts use the first match;\\nselect an explicit ID when names are ambiguous.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For portable recording references, store the ISRC and available Spotify or\\nApple Music identifiers. Additional response fields and provenance labels may\\nvary as Recoup's data connections change. Preserve returned provenance for\\ntraceability without using it to choose a data vendor.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"current-track-statistics\",\n children: \"Current track statistics\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Supply exactly one of \", _jsx(_components.code, {\n children: \"isrc\"\n }), \", \", _jsx(_components.code, {\n children: \"spotify_track_id\"\n }), \", or \", _jsx(_components.code, {\n children: \"apple_music_track_id\"\n }), \", plus\\nthe required \", _jsx(_components.code, {\n children: \"source\"\n }), \" (the platform, such as \", _jsx(_components.code, {\n children: \"spotify\"\n }), \"). Recoup uses stored\\nSpotify measurements when available for an ISRC, and otherwise requests current\\nresearch data. Preserve \", _jsx(_components.code, {\n children: \"data_source\"\n }), \" and capture timestamps when returned;\\nmissing provenance remains unknown. A displayed play count is not a verified\\nroyalty-bearing stream count.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"research-endpoints\",\n children: \"Research endpoints\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Method\"\n }), _jsx(_components.th, {\n children: \"Path\"\n }), _jsx(_components.th, {\n children: \"Reference\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/search\",\n children: \"Search\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/albums\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/albums\",\n children: \"Albums\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/audience\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/audience\",\n children: \"Audience\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/career\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/career\",\n children: \"Career activities\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/insights\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/insights\",\n children: \"Insights activities\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/lookup\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/lookup\",\n children: \"Spotify artist lookup\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/metrics\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/metrics\",\n children: \"Current artist metrics\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/milestones\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/milestones\",\n children: \"Milestones\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/playlists\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/playlists\",\n children: \"Artist playlists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/profile\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/profile\",\n children: \"Artist profile\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/similar\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/similar\",\n children: \"Related artists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/track\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/track\",\n children: \"Track details\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/track/playlists\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/track-playlists\",\n children: \"Track playlists\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/tracks\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/tracks\",\n children: \"Artist tracks\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"GET\"\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/research/urls\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.a, {\n href: \"/api-reference/research/urls\",\n children: \"Platform URLs\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"understand-the-results\",\n children: \"Understand the results\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Artist metrics are current snapshots. Save dated results to compare them over time.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Related artists are unweighted; the accepted similarity axes do not change the ranking.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Artist playlist \", _jsx(_components.code, {\n children: \"status=past\"\n }), \" uses all-time scope and can include current placements.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"historical-measurement-jobs\",\n children: \"Historical measurement jobs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/research/measurement-jobs\"\n }), \" supports \", _jsx(_components.code, {\n children: \"source: \\\"historical\\\"\"\n }), \"\\nfor Spotify backfill. It requires a card on file and returns queue counts with\\n\", _jsx(_components.code, {\n children: \"id: null\"\n }), \"; enqueueing does not confirm capture completion. Recordings with an\\nexisting historical research measurement can be skipped even when their history\\nis partial. Inspect the available dates before claiming complete coverage.\\nCurrent capture jobs return a snapshot ID.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"costs-and-unavailable-data\",\n children: \"Costs and unavailable data\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name\\nresolution can add separately charged lookup calls; reuse a selected research\\nID when available. Historical enqueue itself does not deduct research credits;\\ncapture work has its own balance and budget checks.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For \", _jsx(_components.code, {\n children: \"402 insufficient_credits\"\n }), \", show the returned \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \". Surface \", _jsx(_components.code, {\n children: \"429\"\n }), \"\\nand unavailable-data errors; use bounded retries for transient failures and stop\\nwhen the request cannot be served. Recoup does not promise a \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" header\\non these routes. Never fill a missing metric with an invented number or zero.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Research availability Explore Recoup research, choose the right identifiers, and handle incomplete data. Quickstart Getting started Recoup Research lets you discover artists and tracks, read current metrics, explore audience and playlist activity, and capture recording measurements. Authenticate with your Recoup API key or supported bearer credential. Recoup manages the data connections; you do not need a separate data-service key. Coverage varies by artist, recording, platform and metric. An empty result means no matching data was returned; it does not prove an artist has no activity or audience. ## Choose an identifier Search by name, inspect the matches, and pass the selected result's `id` to the detail endpoints. Treat research IDs as opaque strings: do not parse them or substitute a Recoup account UUID. Artist-name shortcuts use the first match; select an explicit ID when names are ambiguous. For portable recording references, store the ISRC and available Spotify or Apple Music identifiers. Additional response fields and provenance labels may vary as Recoup's data connections change. Preserve returned provenance for traceability without using it to choose a data vendor. ## Current track statistics Supply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus the required `source` (the platform, such as `spotify`). Recoup uses stored Spotify measurements when available for an ISRC, and otherwise requests current research data. Preserve `data_source` and capture timestamps when returned; missing provenance remains unknown. A displayed play count is not a verified royalty-bearing stream count. ## Research endpoints | Method | Path | Reference | | --- | --- | --- | | GET | `/api/research` | [Search](/api-reference/research/search) | | GET | `/api/research/albums` | [Albums](/api-reference/research/albums) | | GET | `/api/research/audience` | [Audience](/api-reference/research/audience) | | GET | `/api/research/career` | [Career activities](/api-reference/research/career) | | GET | `/api/research/insights` | [Insights activities](/api-reference/research/insights) | | GET | `/api/research/lookup` | [Spotify artist lookup](/api-reference/research/lookup) | | GET | `/api/research/metrics` | [Current artist metrics](/api-reference/research/metrics) | | GET | `/api/research/milestones` | [Milestones](/api-reference/research/milestones) | | GET | `/api/research/playlists` | [Artist playlists](/api-reference/research/playlists) | | GET | `/api/research/profile` | [Artist profile](/api-reference/research/profile) | | GET | `/api/research/similar` | [Related artists](/api-reference/research/similar) | | GET | `/api/research/track` | [Track details](/api-reference/research/track) | | GET | `/api/research/track/playlists` | [Track playlists](/api-reference/research/track-playlists) | | GET | `/api/research/tracks` | [Artist tracks](/api-reference/research/tracks) | | GET | `/api/research/urls` | [Platform URLs](/api-reference/research/urls) | ## Understand the results - Artist metrics are current snapshots. Save dated results to compare them over time. - Related artists are unweighted; the accepted similarity axes do not change the ranking. - Artist playlist `status=past` uses all-time scope and can include current placements. - Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline. - Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album. - Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied. ## Historical measurement jobs `POST /api/research/measurement-jobs` supports `source: \"historical\"` for Spotify backfill. It requires a card on file and returns queue counts with `id: null`; enqueueing does not confirm capture completion. Recordings with an existing historical research measurement can be skipped even when their history is partial. Inspect the available dates before claiming complete coverage. Current capture jobs return a snapshot ID. ## Costs and unavailable data Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name resolution can add separately charged lookup calls; reuse a selected research ID when available. Historical enqueue itself does not deduct research credits; capture work has its own balance and budget checks. For `402 insufficient_credits`, show the returned `billingUrl`. Surface `429` and unavailable-data errors; use bounded retries for transient failures and stop when the request cannot be served. Recoup does not promise a `Retry-After` header on these routes. Never fill a missing metric with an invented number or zero. "},{"slug":"workflows/create-artist","title":"Create a New Artist","description":"End-to-end workflow to create, research and enrich a new artist account in a single session.","category":"Artists","group":"Workflows","source":"workflows/create-artist.mdx","body":"This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \"researched + enriched\" parity from a sandbox or any external agent.\n\nThe chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.\n\n## Prerequisites\n\n- `$RECOUP_API_KEY` (`x-api-key`) or `$RECOUP_ACCESS_TOKEN` (Privy Bearer JWT) for `api.recoupable.dev`\n- `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes)\n- An artist name to create (e.g. `ARTIST_NAME=\"The Weeknd\"`)\n\nSelect one credential obtained through the approved real-account REST setup:\n\n```bash\nif [ -n \"$RECOUP_API_KEY\" ]; then\n AUTH=(-H \"x-api-key: $RECOUP_API_KEY\")\nelif [ -n \"$RECOUP_ACCESS_TOKEN\" ]; then\n AUTH=(-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\")\nelse\n echo \"Authenticate REST through the approved real-account setup flow.\" >&2\n exit 1\nfi\n```\n\nUse your real account and selected organization. Do not create a disposable\n`agent+` identity or paste credentials into the workspace file.\n\nThe flow has three phases, run from a single checklist file:\n\n1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match\n2. **Enrich** — `PATCH` the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials\n3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array\n\n## Step 0: Scaffold the workspace BEFORE any API call\n\nPick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:\n\n```bash\nARTIST_SLUG=$(echo \"$ARTIST_NAME\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\\+/-/g; s/^-//; s/-$//')\nARTIST_DIR=\"artists/$ARTIST_SLUG\"\nmkdir -p \"$ARTIST_DIR\"\n\ncat > \"$ARTIST_DIR/RECOUP.md\" <&2\n return 1 ;;\n 429)\n retry_after=$(awk 'tolower($1)==\"retry-after:\" {sub(/^[^:]*:[[:space:]]*/, \"\"); sub(/\\r$/, \"\"); print}' \"$headers\")\n rm -f \"$headers\"\n printf 'Research step stopped. Retry-After: %s. Resume manually when allowed.\\n' \"${retry_after:-not provided}\" >&2\n return 1 ;;\n 5??) ;;\n *) rm -f \"$headers\"; printf 'Research HTTP %s; resolve before resuming.\\n' \"$status\" >&2; return 1 ;;\n esac\n fi\n if [ \"$attempt\" -lt 3 ]; then sleep \"$((attempt * 2))\"; fi\n done\n rm -f \"$headers\"\n echo 'Research unavailable after three attempts.' >&2\n return 1\n}\n```\n\n### 4a: Resolve the research artist ID\n\n```bash\nLOOKUP=$(research_request lookup --get \\\n --data-urlencode \"spotifyId=$SPOTIFY_ARTIST_ID\") || exit 1\n\nRESEARCH_ARTIST_ID=$(printf '%s' \"$LOOKUP\" | jq -r \\\n '[.id, .artist_info.id] | map(select(type == \"string\") | select(test(\"\\\\S\"))) | first // empty')\n```\n\nSave this value as `researchArtistId`. It is separate from the Recoup artist\naccount UUID and Spotify ID. Do not coerce it to a number or copy an older\nsaved research ID into it; re-resolve and verify older workspaces. If a successful\nlookup has no usable `id`, record that gap and skip 4b–4d, then run 4e.\n\nSee [Artist Lookup](/api-reference/research/lookup) for the response contract.\n\n### 4b–4d: Read available structured signals\n\n```bash\nif [ -n \"$RESEARCH_ARTIST_ID\" ]; then\n PROFILE=$(research_request profile --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\n CAREER=$(research_request career --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\n PLAYLISTS=$(research_request playlists --get \\\n --data-urlencode \"id=$RESEARCH_ARTIST_ID\") || exit 1\nfi\n```\n\nInspect the fields actually returned. Profile data may be partial; `career` is\nan available activity feed, not a guaranteed complete career timeline.\n`playlists` returns `placements`, which may be empty. Do not turn missing data\ninto zero or infer a label, achievement or placement that is absent.\n\nSee [Artist Profile](/api-reference/research/profile),\n[Artist Activity](/api-reference/research/career) and\n[Playlist Placements](/api-reference/research/playlists).\n\n### 4e: Search for narrative, press and collaborations\n\n```bash\nRESEARCH_WEB=$(research_request web -X POST \\\n -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg name \"$ARTIST_NAME\" \\\n '{query: ($name + \" biography press recent collaborations\")}')\") || exit 1\n```\n\nVerify source links before asserting a fact. See [Web Search](/api-reference/research/web).\n\n**After this step:** persist `researchArtistId` when available. Save the returned\npayloads, source links and coverage gaps under `## Research` in `RECOUP.md`, with\none subsection per request. Tick step 4 only after the successful reads and any\nintentional structured-data skip have been recorded.\n\n## Step 5: Pull the Spotify catalog\n\n```bash\nTOP_TRACKS=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/artist/topTracks\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$SPOTIFY_ARTIST_ID\")\n\nALBUMS=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/artist/albums\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$SPOTIFY_ARTIST_ID\")\n\n# For each notable album, drill in (ALBUM_ID from $ALBUMS):\nALBUM_DETAIL=$(curl -sS -G \"https://api.recoupable.dev/api/spotify/album\" \\\n \"${AUTH[@]}\" \\\n --data-urlencode \"id=$ALBUM_ID\")\n```\n\n`$SPOTIFY_ARTIST_ID` is the value you exported in step 2.\n\nSee [Spotify Top Tracks](/api-reference/spotify/artist-top-tracks), [Spotify Artist Albums](/api-reference/spotify/artist-albums), and [Spotify Album](/api-reference/spotify/album) for full schemas.\n\n**After this step:** populate the artist's `releases/` folder — write one `releases/{release-slug}/RELEASE.md` per album (album slugs are bare, `-ep` / `-single` / `-compilation` suffixes for other types) using the per-album `GET /api/spotify/album?id=$ALBUM_ID` response, and write the top tracks snapshot to `releases/top-tracks.md`. `RELEASE.md` is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as `⚠️ TBD`. The full template + the field-by-field Spotify mapping live in the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill at `references/release-template.md`. Tick `- [ ] 5.` → `- [x] 5.`.\n\n## Step 6: Search the web for additional socials\n\n```bash\nSOCIALS_SEARCH=$(curl -sS -X POST \"https://api.recoupable.dev/api/research/web\" \\\n \"${AUTH[@]}\" \\\n -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg name \"$ARTIST_NAME\" \\\n '{query: ($name + \" official instagram tiktok twitter youtube\")}')\")\n```\n\nParse the results to extract any new social URLs whose host matches the platform reference table below.\n\nSee [Web Search](/api-reference/research/web) for the request/response schema.\n\n**After this step:** save the discovered URLs (one per platform) into the `## Notes` section so step 7 can read them without re-querying. Tick `- [ ] 6.` → `- [x] 6.`.\n\n## Step 7: PATCH the artist with the discovered socials\n\n```bash\ncurl -sS -X PATCH \"https://api.recoupable.dev/api/artists/$ARTIST_ID\" \\\n \"${AUTH[@]}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"profileUrls\": {\n \"INSTAGRAM\": \"https://instagram.com/...\",\n \"TIKTOK\": \"https://tiktok.com/@...\",\n \"TWITTER\": \"https://x.com/...\",\n \"YOUTUBE\": \"https://youtube.com/@...\"\n }\n }'\n```\n\nOnly include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally.\n\nSee [Update Artist](/api-reference/artists/update) for the full body schema.\n\n**After this step:** tick `- [ ] 7.` → `- [x] 7.`.\n\n## Step 8: Synthesize the knowledge base\n\nCombine the available structured and web research (`## Research` section), the Spotify catalog (`releases/`), and the discovered socials into a comprehensive markdown report. Recommended sections:\n\n- Artist biography and origin\n- Discography highlights (top tracks + key albums)\n- Spotify presence (genres, listener count, notable playlists)\n- Social media footprint\n- Recent activity / press\n- Notable collaborations and achievements\n\nAppend the report to the same `RECOUP.md` you scaffolded in Step 0 — add it as a `## Knowledge base` section below the checklist. The path is:\n\n```\nartists/$ARTIST_SLUG/RECOUP.md\n```\n\nThis dovetails with the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL.\n\n**After this step:** tick `- [ ] 8.` → `- [x] 8.`. With every box ticked, the artist is fully set up.\n\n## Platform key reference\n\n`profileUrls` keys are **uppercase** platform identifiers, inferred from the URL host. Recognized platforms:\n\n| URL contains | `profileUrls` key |\n| ---------------------------- | ----------------- |\n| `spotify.com` | `SPOTIFY` |\n| `instagram.com` | `INSTAGRAM` |\n| `tiktok.com` | `TIKTOK` |\n| `x.com`, `twitter.com` | `TWITTER` |\n| `youtube.` | `YOUTUBE` |\n| `apple.com` | `APPLE` |\n| `facebook.com` | `FACEBOOK` |\n| `threads.net`, `threads.com` | `THREADS` |\n\nURLs that don't match any of these are silently skipped — they won't be saved.\n\n## What this workflow doesn't enforce\n\nThere's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The `RECOUP.md` checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't.\n\nA few constraints to honor:\n\n- **Run steps in order.** The frontmatter values written at one step are the inputs for later steps.\n- **Don't continue past a 4xx/5xx without recovery.** Leave the box unchecked, write the error to `## Notes`, and resolve before resuming.\n- **Treat the file as the source of truth.** If something isn't on disk, don't assume it ran.\n","headings":[{"title":"Prerequisites","id":"prerequisites"},{"title":"Step 0: Scaffold the workspace BEFORE any API call","id":"step-0-scaffold-the-workspace-before-any-api-call"},{"title":"Resuming a partial setup","id":"resuming-a-partial-setup"},{"title":"Step 1: Create the artist","id":"step-1-create-the-artist"},{"title":"Step 2: Find the canonical Spotify match","id":"step-2-find-the-canonical-spotify-match"},{"title":"Step 3: Set basic profile + Spotify URL","id":"step-3-set-basic-profile-spotify-url"},{"title":"Step 4: Run Recoup research","id":"step-4-run-recoup-research"},{"title":"Step 5: Pull the Spotify catalog","id":"step-5-pull-the-spotify-catalog"},{"title":"Step 6: Search the web for additional socials","id":"step-6-search-the-web-for-additional-socials"},{"title":"Step 7: PATCH the artist with the discovered socials","id":"step-7-patch-the-artist-with-the-discovered-socials"},{"title":"Step 8: Synthesize the knowledge base","id":"step-8-synthesize-the-knowledge-base"},{"title":"Platform key reference","id":"platform-key-reference"},{"title":"What this workflow doesn't enforce","id":"what-this-workflow-doesnt-enforce"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \\\"researched + enriched\\\" parity from a sandbox or any external agent.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, \", _jsx(_components.strong, {\n children: \"drive the work from a checklist file\"\n }), \": scaffold the artist's \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"prerequisites\",\n children: \"Prerequisites\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$RECOUP_API_KEY\"\n }), \" (\", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \") or \", _jsx(_components.code, {\n children: \"$RECOUP_ACCESS_TOKEN\"\n }), \" (Privy Bearer JWT) for \", _jsx(_components.code, {\n children: \"api.recoupable.dev\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$RECOUP_ORG_ID\"\n }), \" — the org the artist should belong to (recommended in sandboxes)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"An artist name to create (e.g. \", _jsx(_components.code, {\n children: \"ARTIST_NAME=\\\"The Weeknd\\\"\"\n }), \")\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Select one credential obtained through the approved real-account REST setup:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"if [ -n \\\"$RECOUP_API_KEY\\\" ]; then\\n AUTH=(-H \\\"x-api-key: $RECOUP_API_KEY\\\")\\nelif [ -n \\\"$RECOUP_ACCESS_TOKEN\\\" ]; then\\n AUTH=(-H \\\"Authorization: Bearer $RECOUP_ACCESS_TOKEN\\\")\\nelse\\n echo \\\"Authenticate REST through the approved real-account setup flow.\\\" >&2\\n exit 1\\nfi\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use your real account and selected organization. Do not create a disposable\\n\", _jsx(_components.code, {\n children: \"agent+\"\n }), \" identity or paste credentials into the workspace file.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The flow has three phases, run from a single checklist file:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Create + identify\"\n }), \" — \", _jsx(_components.code, {\n children: \"POST /api/artists\"\n }), \", then find the canonical Spotify match\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Enrich\"\n }), \" — \", _jsx(_components.code, {\n children: \"PATCH\"\n }), \" the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Synthesize + persist\"\n }), \" — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally \", _jsx(_components.code, {\n children: \"PATCH\"\n }), \" the \", _jsx(_components.code, {\n children: \"knowledges\"\n }), \" array\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-0-scaffold-the-workspace-before-any-api-call\",\n children: \"Step 0: Scaffold the workspace BEFORE any API call\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pick a slug, make the directory, and write the initial \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"ARTIST_SLUG=$(echo \\\"$ARTIST_NAME\\\" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\\\\+/-/g; s/^-//; s/-$//')\\nARTIST_DIR=\\\"artists/$ARTIST_SLUG\\\"\\nmkdir -p \\\"$ARTIST_DIR\\\"\\n\\ncat > \\\"$ARTIST_DIR/RECOUP.md\\\" <&2\\n return 1 ;;\\n 429)\\n retry_after=$(awk 'tolower($1)==\\\"retry-after:\\\" {sub(/^[^:]*:[[:space:]]*/, \\\"\\\"); sub(/\\\\r$/, \\\"\\\"); print}' \\\"$headers\\\")\\n rm -f \\\"$headers\\\"\\n printf 'Research step stopped. Retry-After: %s. Resume manually when allowed.\\\\n' \\\"${retry_after:-not provided}\\\" >&2\\n return 1 ;;\\n 5??) ;;\\n *) rm -f \\\"$headers\\\"; printf 'Research HTTP %s; resolve before resuming.\\\\n' \\\"$status\\\" >&2; return 1 ;;\\n esac\\n fi\\n if [ \\\"$attempt\\\" -lt 3 ]; then sleep \\\"$((attempt * 2))\\\"; fi\\n done\\n rm -f \\\"$headers\\\"\\n echo 'Research unavailable after three attempts.' >&2\\n return 1\\n}\\n\"\n })\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4a-resolve-the-research-artist-id\",\n children: \"4a: Resolve the research artist ID\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"LOOKUP=$(research_request lookup --get \\\\\\n --data-urlencode \\\"spotifyId=$SPOTIFY_ARTIST_ID\\\") || exit 1\\n\\nRESEARCH_ARTIST_ID=$(printf '%s' \\\"$LOOKUP\\\" | jq -r \\\\\\n '[.id, .artist_info.id] | map(select(type == \\\"string\\\") | select(test(\\\"\\\\\\\\S\\\"))) | first // empty')\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save this value as \", _jsx(_components.code, {\n children: \"researchArtistId\"\n }), \". It is separate from the Recoup artist\\naccount UUID and Spotify ID. Do not coerce it to a number or copy an older\\nsaved research ID into it; re-resolve and verify older workspaces. If a successful\\nlookup has no usable \", _jsx(_components.code, {\n children: \"id\"\n }), \", record that gap and skip 4b–4d, then run 4e.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/lookup\",\n children: \"Artist Lookup\"\n }), \" for the response contract.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4b4d-read-available-structured-signals\",\n children: \"4b–4d: Read available structured signals\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"if [ -n \\\"$RESEARCH_ARTIST_ID\\\" ]; then\\n PROFILE=$(research_request profile --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\n CAREER=$(research_request career --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\n PLAYLISTS=$(research_request playlists --get \\\\\\n --data-urlencode \\\"id=$RESEARCH_ARTIST_ID\\\") || exit 1\\nfi\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Inspect the fields actually returned. Profile data may be partial; \", _jsx(_components.code, {\n children: \"career\"\n }), \" is\\nan available activity feed, not a guaranteed complete career timeline.\\n\", _jsx(_components.code, {\n children: \"playlists\"\n }), \" returns \", _jsx(_components.code, {\n children: \"placements\"\n }), \", which may be empty. Do not turn missing data\\ninto zero or infer a label, achievement or placement that is absent.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/profile\",\n children: \"Artist Profile\"\n }), \",\\n\", _jsx(_components.a, {\n href: \"/api-reference/research/career\",\n children: \"Artist Activity\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"/api-reference/research/playlists\",\n children: \"Playlist Placements\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"4e-search-for-narrative-press-and-collaborations\",\n children: \"4e: Search for narrative, press and collaborations\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"RESEARCH_WEB=$(research_request web -X POST \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg name \\\"$ARTIST_NAME\\\" \\\\\\n '{query: ($name + \\\" biography press recent collaborations\\\")}')\\\") || exit 1\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Verify source links before asserting a fact. See \", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: \"Web Search\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" persist \", _jsx(_components.code, {\n children: \"researchArtistId\"\n }), \" when available. Save the returned\\npayloads, source links and coverage gaps under \", _jsx(_components.code, {\n children: \"## Research\"\n }), \" in \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \", with\\none subsection per request. Tick step 4 only after the successful reads and any\\nintentional structured-data skip have been recorded.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-5-pull-the-spotify-catalog\",\n children: \"Step 5: Pull the Spotify catalog\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"TOP_TRACKS=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/artist/topTracks\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$SPOTIFY_ARTIST_ID\\\")\\n\\nALBUMS=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/artist/albums\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$SPOTIFY_ARTIST_ID\\\")\\n\\n# For each notable album, drill in (ALBUM_ID from $ALBUMS):\\nALBUM_DETAIL=$(curl -sS -G \\\"https://api.recoupable.dev/api/spotify/album\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n --data-urlencode \\\"id=$ALBUM_ID\\\")\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"$SPOTIFY_ARTIST_ID\"\n }), \" is the value you exported in step 2.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/spotify/artist-top-tracks\",\n children: \"Spotify Top Tracks\"\n }), \", \", _jsx(_components.a, {\n href: \"/api-reference/spotify/artist-albums\",\n children: \"Spotify Artist Albums\"\n }), \", and \", _jsx(_components.a, {\n href: \"/api-reference/spotify/album\",\n children: \"Spotify Album\"\n }), \" for full schemas.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" populate the artist's \", _jsx(_components.code, {\n children: \"releases/\"\n }), \" folder — write one \", _jsx(_components.code, {\n children: \"releases/{release-slug}/RELEASE.md\"\n }), \" per album (album slugs are bare, \", _jsx(_components.code, {\n children: \"-ep\"\n }), \" / \", _jsx(_components.code, {\n children: \"-single\"\n }), \" / \", _jsx(_components.code, {\n children: \"-compilation\"\n }), \" suffixes for other types) using the per-album \", _jsx(_components.code, {\n children: \"GET /api/spotify/album?id=$ALBUM_ID\"\n }), \" response, and write the top tracks snapshot to \", _jsx(_components.code, {\n children: \"releases/top-tracks.md\"\n }), \". \", _jsx(_components.code, {\n children: \"RELEASE.md\"\n }), \" is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as \", _jsx(_components.code, {\n children: \"⚠️ TBD\"\n }), \". The full template + the field-by-field Spotify mapping live in the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace\",\n children: _jsx(_components.code, {\n children: \"artist-workspace\"\n })\n }), \" skill at \", _jsx(_components.code, {\n children: \"references/release-template.md\"\n }), \". Tick \", _jsx(_components.code, {\n children: \"- [ ] 5.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 5.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-6-search-the-web-for-additional-socials\",\n children: \"Step 6: Search the web for additional socials\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"SOCIALS_SEARCH=$(curl -sS -X POST \\\"https://api.recoupable.dev/api/research/web\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg name \\\"$ARTIST_NAME\\\" \\\\\\n '{query: ($name + \\\" official instagram tiktok twitter youtube\\\")}')\\\")\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Parse the results to extract any new social URLs whose host matches the platform reference table below.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/research/web\",\n children: \"Web Search\"\n }), \" for the request/response schema.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" save the discovered URLs (one per platform) into the \", _jsx(_components.code, {\n children: \"## Notes\"\n }), \" section so step 7 can read them without re-querying. Tick \", _jsx(_components.code, {\n children: \"- [ ] 6.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 6.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-7-patch-the-artist-with-the-discovered-socials\",\n children: \"Step 7: PATCH the artist with the discovered socials\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -sS -X PATCH \\\"https://api.recoupable.dev/api/artists/$ARTIST_ID\\\" \\\\\\n \\\"${AUTH[@]}\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\n \\\"profileUrls\\\": {\\n \\\"INSTAGRAM\\\": \\\"https://instagram.com/...\\\",\\n \\\"TIKTOK\\\": \\\"https://tiktok.com/@...\\\",\\n \\\"TWITTER\\\": \\\"https://x.com/...\\\",\\n \\\"YOUTUBE\\\": \\\"https://youtube.com/@...\\\"\\n }\\n }'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Only include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/artists/update\",\n children: \"Update Artist\"\n }), \" for the full body schema.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" tick \", _jsx(_components.code, {\n children: \"- [ ] 7.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 7.\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-8-synthesize-the-knowledge-base\",\n children: \"Step 8: Synthesize the knowledge base\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Combine the available structured and web research (\", _jsx(_components.code, {\n children: \"## Research\"\n }), \" section), the Spotify catalog (\", _jsx(_components.code, {\n children: \"releases/\"\n }), \"), and the discovered socials into a comprehensive markdown report. Recommended sections:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Artist biography and origin\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Discography highlights (top tracks + key albums)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Spotify presence (genres, listener count, notable playlists)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Social media footprint\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Recent activity / press\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Notable collaborations and achievements\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Append the report to the same \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" you scaffolded in Step 0 — add it as a \", _jsx(_components.code, {\n children: \"## Knowledge base\"\n }), \" section below the checklist. The path is:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"artists/$ARTIST_SLUG/RECOUP.md\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This dovetails with the \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace\",\n children: _jsx(_components.code, {\n children: \"artist-workspace\"\n })\n }), \" skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After this step:\"\n }), \" tick \", _jsx(_components.code, {\n children: \"- [ ] 8.\"\n }), \" → \", _jsx(_components.code, {\n children: \"- [x] 8.\"\n }), \". With every box ticked, the artist is fully set up.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"platform-key-reference\",\n children: \"Platform key reference\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"profileUrls\"\n }), \" keys are \", _jsx(_components.strong, {\n children: \"uppercase\"\n }), \" platform identifiers, inferred from the URL host. Recognized platforms:\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"URL contains\"\n }), _jsxs(_components.th, {\n children: [_jsx(_components.code, {\n children: \"profileUrls\"\n }), \" key\"]\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"spotify.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"SPOTIFY\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"instagram.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"INSTAGRAM\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"tiktok.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"TIKTOK\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"x.com\"\n }), \", \", _jsx(_components.code, {\n children: \"twitter.com\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"TWITTER\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"youtube.\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"YOUTUBE\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"apple.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"APPLE\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"facebook.com\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"FACEBOOK\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"threads.net\"\n }), \", \", _jsx(_components.code, {\n children: \"threads.com\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"THREADS\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"URLs that don't match any of these are silently skipped — they won't be saved.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-this-workflow-doesnt-enforce\",\n children: \"What this workflow doesn't enforce\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"There's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The \", _jsx(_components.code, {\n children: \"RECOUP.md\"\n }), \" checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A few constraints to honor:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Run steps in order.\"\n }), \" The frontmatter values written at one step are the inputs for later steps.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Don't continue past a 4xx/5xx without recovery.\"\n }), \" Leave the box unchecked, write the error to \", _jsx(_components.code, {\n children: \"## Notes\"\n }), \", and resolve before resuming.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Treat the file as the source of truth.\"\n }), \" If something isn't on disk, don't assume it ran.\"]\n }), \"\\n\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Create a New Artist End-to-end workflow to create, research and enrich a new artist account in a single session. Artists Workflows This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to \"researched + enriched\" parity from a sandbox or any external agent. The chain is 8 sequential steps. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it. ## Prerequisites - `$RECOUP_API_KEY` (`x-api-key`) or `$RECOUP_ACCESS_TOKEN` (Privy Bearer JWT) for `api.recoupable.dev` - `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes) - An artist name to create (e.g. `ARTIST_NAME=\"The Weeknd\"`) Select one credential obtained through the approved real-account REST setup: Use your real account and selected organization. Do not create a disposable `agent+` identity or paste credentials into the workspace file. The flow has three phases, run from a single checklist file: 1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match 2. **Enrich** — `PATCH` the artist with image/label/socials, then read available Recoup research and search the web for narrative context and additional socials 3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array ## Step 0: Scaffold the workspace BEFORE any API call Pick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps: The sandbox is already scoped to a single Recoupable organization (its repo _is_ the org), so artists live at the top level — there is no `orgs/` directory. Don't proceed to step 1 until the file exists on disk. **After every step that follows, do two writes back to `RECOUP.md`:** tick the checkbox for the step you just ran (`- [ ]` → `- [x]`) and persist any captured value into the frontmatter. Later steps read those values from the frontmatter — never re-derive what's already saved. ## Resuming a partial setup If `$ARTIST_DIR/RECOUP.md` already exists, do not re-scaffold and do not re-run completed steps. Read the file, find the first unchecked item, and resume from there using the values already saved in the frontmatter: If every item is checked, the artist is fully set up — confirm with the user before doing anything else. ## Step 1: Create the artist Capture `account_id` as `$ARTIST_ID` — every subsequent step needs it. `organization_id` is optional but should be included when running inside a sandbox so the artist is scoped to the right org. See [Create Artist](/api-reference/artists/create) for the full request/response schema. **After this step:** write `artistId: $ARTIST_ID` into the frontmatter and tick `- [ ] 1.` → `- [x] 1.` in `RECOUP.md`. ## Step 2: Find the canonical Spotify match Inspect the returned candidates' names, profile links, images and catalog. Set `SELECTED_SPOTIFY_ARTIST_ID` to the verified match; popularity alone does not establish identity. If candidates remain ambiguous, resolve that before saving the artist's profile. If the verified artist is absent from the first ten results, repeat the search with a more specific name or known catalog context and inspect the new results. Do not substitute another artist. After verifying the candidate, export its fields: Also keep `genres`, `followers.total`, and `popularity` from `$MATCH` for the KB report later. See [Spotify Search](/api-reference/spotify/search) for the full query parameters and response schema. **After this step:** write `spotifyArtistId`, `spotifyProfileUrl`, and `imageUrl` into the frontmatter, save `genres` / `followers.total` / `popularity` to the `## Notes` section, and tick `- [ ] 2.` → `- [x] 2.`. ## Step 3: Set basic profile + Spotify URL One `PATCH` covers the image and the Spotify social URL. Use **uppercase** platform keys in `profileUrls` (the API matches platforms case-sensitively — see the reference table below). 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 only after verifying it in the research (step 4). See [Update Artist](/api-reference/artists/update) for the full body schema. **After this step:** tick `- [ ] 3.` → `- [x] 3.`. ## Step 4: Run Recoup research Resolve the verified Spotify artist to an opaque Recoup research ID, then read available profile fields, activity and playlist placements. Coverage varies by artist and platform: an empty successful response is a data gap, not a request to warm a cache. Use a web search for biography, press and collaborations. The four structured reads below cost $0.05 each when successful, or $0.20 total (200,000 micro-dollar credits). Web research is billed separately; check the current credit reference before running it. Check HTTP status before extracting IDs or making dependent calls. This helper allows at most three attempts for network failures or `5xx`, each with a 90-second timeout. A `402` surfaces `billingUrl`; a `429` stops the step and prints `Retry-After` for a later manual retry; it does not wait or retry automatically. Leave the step unchecked on errors. ### 4a: Resolve the research artist ID Save this value as `researchArtistId`. It is separate from the Recoup artist account UUID and Spotify ID. Do not coerce it to a number or copy an older saved research ID into it; re-resolve and verify older workspaces. If a successful lookup has no usable `id`, record that gap and skip 4b–4d, then run 4e. See [Artist Lookup](/api-reference/research/lookup) for the response contract. ### 4b–4d: Read available structured signals Inspect the fields actually returned. Profile data may be partial; `career` is an available activity feed, not a guaranteed complete career timeline. `playlists` returns `placements`, which may be empty. Do not turn missing data into zero or infer a label, achievement or placement that is absent. See [Artist Profile](/api-reference/research/profile), [Artist Activity](/api-reference/research/career) and [Playlist Placements](/api-reference/research/playlists). ### 4e: Search for narrative, press and collaborations Verify source links before asserting a fact. See [Web Search](/api-reference/research/web). **After this step:** persist `researchArtistId` when available. Save the returned payloads, source links and coverage gaps under `## Research` in `RECOUP.md`, with one subsection per request. Tick step 4 only after the successful reads and any intentional structured-data skip have been recorded. ## Step 5: Pull the Spotify catalog `$SPOTIFY_ARTIST_ID` is the value you exported in step 2. See [Spotify Top Tracks](/api-reference/spotify/artist-top-tracks), [Spotify Artist Albums](/api-reference/spotify/artist-albums), and [Spotify Album](/api-reference/spotify/album) for full schemas. **After this step:** populate the artist's `releases/` folder — write one `releases/{release-slug}/RELEASE.md` per album (album slugs are bare, `-ep` / `-single` / `-compilation` suffixes for other types) using the per-album `GET /api/spotify/album?id=$ALBUM_ID` response, and write the top tracks snapshot to `releases/top-tracks.md`. `RELEASE.md` is the 18-section master release-management document (project snapshot, identifiers, narrative, audience, DSP strategy, marketing, social, PR, visuals, physical/merch/touring, team, budget, KPI tracking, links hub, plus Outstanding Deliverables and a Document History log) — Step 5 fills the Spotify-derivable fields and leaves the rest as `⚠️ TBD`. The full template + the field-by-field Spotify mapping live in the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill at `references/release-template.md`. Tick `- [ ] 5.` → `- [x] 5.`. ## Step 6: Search the web for additional socials Parse the results to extract any new social URLs whose host matches the platform reference table below. See [Web Search](/api-reference/research/web) for the request/response schema. **After this step:** save the discovered URLs (one per platform) into the `## Notes` section so step 7 can read them without re-querying. Tick `- [ ] 6.` → `- [x] 6.`. ## Step 7: PATCH the artist with the discovered socials Only include keys for platforms you actually found URLs for. The PATCH preserves existing socials for keys you omit, so this is safe to run incrementally. See [Update Artist](/api-reference/artists/update) for the full body schema. **After this step:** tick `- [ ] 7.` → `- [x] 7.`. ## Step 8: Synthesize the knowledge base Combine the available structured and web research (`## Research` section), the Spotify catalog (`releases/`), and the discovered socials into a comprehensive markdown report. Recommended sections: - Artist biography and origin - Discography highlights (top tracks + key albums) - Spotify presence (genres, listener count, notable playlists) - Social media footprint - Recent activity / press - Notable collaborations and achievements Append the report to the same `RECOUP.md` you scaffolded in Step 0 — add it as a `## Knowledge base` section below the checklist. The path is: This dovetails with the [`artist-workspace`](https://github.com/recoupable/recoup-platform-plugin/tree/main/skills/artist-workspace) skill's filesystem conventions, so future sandbox sessions can read both the checklist and the KB without needing a hosted URL. **After this step:** tick `- [ ] 8.` → `- [x] 8.`. With every box ticked, the artist is fully set up. ## Platform key reference `profileUrls` keys are **uppercase** platform identifiers, inferred from the URL host. Recognized platforms: | URL contains | `profileUrls` key | | ---------------------------- | ----------------- | | `spotify.com` | `SPOTIFY` | | `instagram.com` | `INSTAGRAM` | | `tiktok.com` | `TIKTOK` | | `x.com`, `twitter.com` | `TWITTER` | | `youtube.` | `YOUTUBE` | | `apple.com` | `APPLE` | | `facebook.com` | `FACEBOOK` | | `threads.net`, `threads.com` | `THREADS` | URLs that don't match any of these are silently skipped — they won't be saved. ## What this workflow doesn't enforce There's no server-side orchestrator forcing each step to run in order — the chain is honor-system. The `RECOUP.md` checklist is what gives you determinism in practice: as long as you tick boxes and persist values after each step, a fresh turn (or a different agent) can pick up exactly where the last one stopped. If you skip a checkbox or skip the persist, the next turn won't know that step ran and may either redo it or, worse, treat downstream calls as ready when they aren't. A few constraints to honor: - **Run steps in order.** The frontmatter values written at one step are the inputs for later steps. - **Don't continue past a 4xx/5xx without recovery.** Leave the box unchecked, write the error to `## Notes`, and resolve before resuming. - **Treat the file as the source of truth.** If something isn't on disk, don't assume it ran. "},{"slug":"api-reference/artists/list","title":"Get Artists","description":"Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to.","category":"Artists","group":"Artists","source":"api-reference/artists/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists","spec":"releases.json"},"searchText":"Get Artists Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to. Artists Artists GET /api/artists "},{"slug":"api-reference/artists/profile","title":"Get Artist Profile","description":"Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call.","category":"Artists","group":"Artists","source":"api-reference/artists/profile.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/profile","spec":"releases.json"},"searchText":"Get Artist Profile Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call. Artists Artists GET /api/artists/{id}/profile "},{"slug":"api-reference/artists/create","title":"Create Artist","description":"Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization.","category":"Artists","group":"Artists","source":"api-reference/artists/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/artists","spec":"releases.json"},"searchText":"Create Artist Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization. Artists Artists POST /api/artists "},{"slug":"api-reference/artists/update","title":"Update Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Update Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/pin","title":"Pin Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/pin.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Pin Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/unpin","title":"Unpin Artist","description":"Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.","category":"Artists","group":"Artists","source":"api-reference/artists/unpin.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Unpin Artist Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account. Artists Artists PATCH /api/artists/{id} "},{"slug":"api-reference/artists/delete","title":"Delete Artist","description":"Delete an artist accessible to the authenticated account.","category":"Artists","group":"Artists","source":"api-reference/artists/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/artists/{id}","spec":"releases.json"},"searchText":"Delete Artist Delete an artist accessible to the authenticated account. Artists Artists DELETE /api/artists/{id} "},{"slug":"api-reference/artists/socials","title":"Get Artist Socials","description":"Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember.","category":"Artists","group":"Artists","source":"api-reference/artists/socials.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/socials","spec":"releases.json"},"searchText":"Get Artist Socials Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember. Artists Artists GET /api/artists/{id}/socials "},{"slug":"api-reference/artists/socials-delete","title":"Delete Artist Social","description":"Remove a social profile link from an artist to correct a wrongly auto-matched social.","category":"Artists","group":"Artists","source":"api-reference/artists/socials-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/artists/{id}/socials/{socialId}","spec":"releases.json"},"searchText":"Delete Artist Social Remove a social profile link from an artist to correct a wrongly auto-matched social. Artists Artists DELETE /api/artists/{id}/socials/{socialId} "},{"slug":"api-reference/fans/get","title":"Get Artist Fans","description":"Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists.","category":"Artists","group":"Fans","source":"api-reference/fans/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/fans","spec":"releases.json"},"searchText":"Get Artist Fans Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists. Artists Fans GET /api/artists/{id}/fans "},{"slug":"api-reference/chat/workflow","title":"Stream Chat","description":"Stream sandbox-driven chat (Vercel Workflow)","category":"Chats","group":"Streaming","source":"api-reference/chat/workflow.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat","spec":"research.json"},"searchText":"Stream Chat Stream sandbox-driven chat (Vercel Workflow) Chats Streaming POST /api/chat "},{"slug":"api-reference/chat/workflow-stream","title":"Resume Chat Stream","description":"Resume a chat response stream","category":"Chats","group":"Streaming","source":"api-reference/chat/workflow-stream.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chat/{chatId}/stream","spec":"research.json"},"searchText":"Resume Chat Stream Resume a chat response stream Chats Streaming GET /api/chat/{chatId}/stream "},{"slug":"api-reference/chat/runs","title":"Start Chat Run","description":"Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow).","category":"Chats","group":"Streaming","source":"api-reference/chat/runs.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat/runs","spec":"research.json"},"searchText":"Start Chat Run Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow). Chats Streaming POST /api/chat/runs "},{"slug":"api-reference/chat/runs-status","title":"Get Chat Run Status","description":"Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.","category":"Chats","group":"Streaming","source":"api-reference/chat/runs-status.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chat/runs/{runId}","spec":"research.json"},"searchText":"Get Chat Run Status Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content. Chats Streaming GET /api/chat/runs/{runId} "},{"slug":"api-reference/chat/stop","title":"Stop Chat","description":"Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account.","category":"Chats","group":"Streaming","source":"api-reference/chat/stop.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chat/{chatId}/stop","spec":"research.json"},"searchText":"Stop Chat Stop the response currently being generated for a chat, freeing it to accept a new message. Idempotent — returns `stopped: false` when nothing is in progress. The chat must belong to the authenticated account. Chats Streaming POST /api/chat/{chatId}/stop "},{"slug":"api-reference/chat/create","title":"Create Chat","description":"Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to.","category":"Chats","group":"Chats","source":"api-reference/chat/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats","spec":"research.json"},"searchText":"Create Chat Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to. Chats Chats POST /api/chats "},{"slug":"api-reference/chat/chats","title":"Get Chats","description":"Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL.","category":"Chats","group":"Chats","source":"api-reference/chat/chats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats","spec":"research.json"},"searchText":"Get Chats Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL. Chats Chats GET /api/chats "},{"slug":"api-reference/chat/artist","title":"Get Chat Artist","description":"Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller.","category":"Chats","group":"Chats","source":"api-reference/chat/artist.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats/{id}/artist","spec":"research.json"},"searchText":"Get Chat Artist Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller. Chats Chats GET /api/chats/{id}/artist "},{"slug":"api-reference/chat/update","title":"Update Chat","description":"Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters.","category":"Chats","group":"Chats","source":"api-reference/chat/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/chats","spec":"research.json"},"searchText":"Update Chat Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters. Chats Chats PATCH /api/chats "},{"slug":"api-reference/chat/delete","title":"Delete Chat","description":"Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself.","category":"Chats","group":"Chats","source":"api-reference/chat/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/chats","spec":"research.json"},"searchText":"Delete Chat Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself. Chats Chats DELETE /api/chats "},{"slug":"api-reference/chat/compact","title":"Compact Chats","description":"Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary.","category":"Chats","group":"Chats","source":"api-reference/chat/compact.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats/compact","spec":"research.json"},"searchText":"Compact Chats Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary. Chats Chats POST /api/chats/compact "},{"slug":"api-reference/ai/models","title":"List Models","description":"Returns the catalog of language models available through the Vercel AI Gateway. Embedding models are filtered out. The full schema mirrors the Vercel AI Gateway response (`GatewayLanguageModelEntry` from `@ai-sdk/gateway`); the documented properties below are the load-bearing fields used by clients. No authentication required.","category":"Chats","group":"Chats","source":"api-reference/ai/models.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/ai/models","spec":"ai.json"},"searchText":"List Models Returns the catalog of language models available through the Vercel AI Gateway. Embedding models are filtered out. The full schema mirrors the Vercel AI Gateway response (`GatewayLanguageModelEntry` from `@ai-sdk/gateway`); the documented properties below are the load-bearing fields used by clients. No authentication required. Chats Chats GET /api/ai/models "},{"slug":"api-reference/chat/messages","title":"Get Chat Messages","description":"Retrieve all messages (memories) for a specific chat room in chronological order.","category":"Chats","group":"Messages","source":"api-reference/chat/messages.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/chats/{id}/messages","spec":"research.json"},"searchText":"Get Chat Messages Retrieve all messages (memories) for a specific chat room in chronological order. Chats Messages GET /api/chats/{id}/messages "},{"slug":"api-reference/chat/messages-copy","title":"Copy Chat Messages","description":"Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy.","category":"Chats","group":"Messages","source":"api-reference/chat/messages-copy.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/chats/{id}/messages/copy","spec":"research.json"},"searchText":"Copy Chat Messages Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy. Chats Messages POST /api/chats/{id}/messages/copy "},{"slug":"api-reference/chat/messages-trailing-delete","title":"Delete Trailing Chat Messages","description":"Delete a message in a Workflow chat and every message after it, ordered by `created_at` then `id`. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns `409`. `200` means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending.","category":"Chats","group":"Messages","source":"api-reference/chat/messages-trailing-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/chats/{id}/messages/trailing","spec":"research.json"},"searchText":"Delete Trailing Chat Messages Delete a message in a Workflow chat and every message after it, ordered by `created_at` then `id`. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns `409`. `200` means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending. Chats Messages DELETE /api/chats/{id}/messages/trailing "},{"slug":"api-reference/research/search","title":"Research Search","description":"Search Recoup Research for artists, tracks or labels by name. Artist and track matches include an `id` when an identifier is available. Select a match and reuse that ID for detail requests. `type` accepts artists, tracks or labels, plus their singular aliases, case-insensitively. Playlist search is unavailable. Recoup defaults `limit` to 10; pagination strings are passed to the data connection and its limits apply.","category":"Research","group":"Artist discovery","source":"api-reference/research/search.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research","spec":"research.json"},"searchText":"Research Search Search Recoup Research for artists, tracks or labels by name. Artist and track matches include an `id` when an identifier is available. Select a match and reuse that ID for detail requests. `type` accepts artists, tracks or labels, plus their singular aliases, case-insensitively. Playlist search is unavailable. Recoup defaults `limit` to 10; pagination strings are passed to the data connection and its limits apply. Research Artist discovery GET /api/research "},{"slug":"api-reference/research/lookup","title":"Lookup by URL","description":"Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved.","category":"Research","group":"Artist discovery","source":"api-reference/research/lookup.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/lookup","spec":"research.json"},"searchText":"Lookup by URL Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved. Research Artist discovery GET /api/research/lookup "},{"slug":"api-reference/research/profile","title":"Artist Profile","description":"Read artist identity and available biography, links, genres and related-artist metadata. Fields depend on available research data. For current platform counts, use [Metrics](/api-reference/research/metrics).","category":"Research","group":"Artist discovery","source":"api-reference/research/profile.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/profile","spec":"research.json"},"searchText":"Artist Profile Read artist identity and available biography, links, genres and related-artist metadata. Fields depend on available research data. For current platform counts, use [Metrics](/api-reference/research/metrics). Research Artist discovery GET /api/research/profile "},{"slug":"api-reference/research/metrics","title":"Platform Metrics","description":"Read current artist statistics for the required platform `source`. This is a synchronous snapshot, without a historical series or refresh-pending job. A valid source does not guarantee data is available. Save dated responses to compare results over time.","category":"Research","group":"Metrics & insights","source":"api-reference/research/metrics.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/metrics","spec":"research.json"},"searchText":"Platform Metrics Read current artist statistics for the required platform `source`. This is a synchronous snapshot, without a historical series or refresh-pending job. A valid source does not guarantee data is available. Save dated responses to compare results over time. Research Metrics & insights GET /api/research/metrics "},{"slug":"api-reference/research/audience","title":"Audience Demographics","description":"Read available audience data for an artist and platform. The default is `instagram`; other supported data connections can include Spotify, TikTok and YouTube. Geographic and demographic coverage varies. Age and gender breakdowns are not guaranteed.","category":"Research","group":"Metrics & insights","source":"api-reference/research/audience.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/audience","spec":"research.json"},"searchText":"Audience Demographics Read available audience data for an artist and platform. The default is `instagram`; other supported data connections can include Spotify, TikTok and YouTube. Geographic and demographic coverage varies. Age and gender breakdowns are not guaranteed. Research Metrics & insights GET /api/research/audience "},{"slug":"api-reference/research/insights","title":"Insights Activities","description":"Read available artist activities under `insights`. This endpoint returns activity data; it does not generate an AI analysis or a separate insight report.","category":"Research","group":"Metrics & insights","source":"api-reference/research/insights.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/insights","spec":"research.json"},"searchText":"Insights Activities Read available artist activities under `insights`. This endpoint returns activity data; it does not generate an AI analysis or a separate insight report. Research Metrics & insights GET /api/research/insights "},{"slug":"api-reference/research/career","title":"Career Timeline","description":"Read available dated artist activities under `career`. Career, insights and milestones use the same activity feed. This endpoint does not calculate a career stage or score, and does not guarantee a complete career history.","category":"Research","group":"Metrics & insights","source":"api-reference/research/career.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/career","spec":"research.json"},"searchText":"Career Timeline Read available dated artist activities under `career`. Career, insights and milestones use the same activity feed. This endpoint does not calculate a career stage or score, and does not guarantee a complete career history. Research Metrics & insights GET /api/research/career "},{"slug":"api-reference/research/milestones","title":"Milestones","description":"Read available artist activities under `milestones`. Coverage varies; an empty result does not prove the artist has no milestones. This endpoint does not guarantee a complete history or scored career timeline.","category":"Research","group":"Metrics & insights","source":"api-reference/research/milestones.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/milestones","spec":"research.json"},"searchText":"Milestones Read available artist activities under `milestones`. Coverage varies; an empty result does not prove the artist has no milestones. This endpoint does not guarantee a complete history or scored career timeline. Research Metrics & insights GET /api/research/milestones "},{"slug":"api-reference/research/events","title":"Artist Events","description":"List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup.","category":"Research","group":"Metrics & insights","source":"api-reference/research/events.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/events","spec":"research.json"},"searchText":"Artist Events List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup. Research Metrics & insights POST /api/research/events "},{"slug":"api-reference/research/similar","title":"Similar Artists","description":"Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored.","category":"Research","group":"Metrics & insights","source":"api-reference/research/similar.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/similar","spec":"research.json"},"searchText":"Similar Artists Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored. Research Metrics & insights GET /api/research/similar "},{"slug":"api-reference/research/urls","title":"Social URLs","description":"Read available platform URLs as `{domain, url}` entries. A missing link means no matching URL was returned; it does not prove the artist lacks an account on that platform.","category":"Research","group":"Metrics & insights","source":"api-reference/research/urls.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/urls","spec":"research.json"},"searchText":"Social URLs Read available platform URLs as `{domain, url}` entries. A missing link means no matching URL was returned; it does not prove the artist lacks an account on that platform. Research Metrics & insights GET /api/research/urls "},{"slug":"api-reference/research/albums","title":"Albums","description":"Read the artist catalog through the `albums` view using the `artist_id` selected from [Search](/api-reference/research/search). Results can include track-shaped catalog entries rather than distinct album objects. `is_primary` accepts true/false; filtering depends on the data connection. `limit` must be a positive integer string and `offset` a non-negative integer string.","category":"Research","group":"Catalog","source":"api-reference/research/albums.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/albums","spec":"research.json"},"searchText":"Albums Read the artist catalog through the `albums` view using the `artist_id` selected from [Search](/api-reference/research/search). Results can include track-shaped catalog entries rather than distinct album objects. `is_primary` accepts true/false; filtering depends on the data connection. `limit` must be a positive integer string and `offset` a non-negative integer string. Research Catalog GET /api/research/albums "},{"slug":"api-reference/research/tracks","title":"Tracks","description":"Read available artist catalog entries under `tracks`. Entries can include remixes and features; completeness and fields vary. This endpoint accepts an artist identifier without catalog pagination or filtering controls.","category":"Research","group":"Catalog","source":"api-reference/research/tracks.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/tracks","spec":"research.json"},"searchText":"Tracks Read available artist catalog entries under `tracks`. Entries can include remixes and features; completeness and fields vary. This endpoint accepts an artist identifier without catalog pagination or filtering controls. Research Catalog GET /api/research/tracks "},{"slug":"api-reference/research/track","title":"Track","description":"Read track details using the `id` selected from [Search](/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording.","category":"Research","group":"Catalog","source":"api-reference/research/track.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track","spec":"research.json"},"searchText":"Track Read track details using the `id` selected from [Search](/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording. Research Catalog GET /api/research/track "},{"slug":"api-reference/research/track-stats","title":"Track Stats","description":"Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown.","category":"Research","group":"Catalog","source":"api-reference/research/track-stats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track/stats","spec":"research.json"},"searchText":"Track Stats Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown. Research Catalog GET /api/research/track/stats "},{"slug":"api-reference/research/measurements","title":"Track measurements","description":"Track measurements","category":"Research","group":"Catalog","source":"api-reference/research/measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/tracks/{id}/measurements","spec":"research.json"},"searchText":"Track measurements Track measurements Research Catalog GET /api/research/tracks/{id}/measurements "},{"slug":"api-reference/research/album-measurements","title":"Album measurements","description":"Album measurements","category":"Research","group":"Catalog","source":"api-reference/research/album-measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/albums/{id}/measurements","spec":"research.json"},"searchText":"Album measurements Album measurements Research Catalog GET /api/research/albums/{id}/measurements "},{"slug":"api-reference/research/measurement-jobs","title":"Create measurement job","description":"Create a measurement job","category":"Research","group":"Catalog","source":"api-reference/research/measurement-jobs.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/measurement-jobs","spec":"research.json"},"searchText":"Create measurement job Create a measurement job Research Catalog POST /api/research/measurement-jobs "},{"slug":"api-reference/research/playlists","title":"Playlist Placements","description":"Read available playlist placements for an artist. `status=current` selects current scope; `status=past` selects all-time scope, which can include current placements. `limit` is an optional raw string with no Recoup default; supported limits and coverage depend on the data connection.","category":"Research","group":"Playlists","source":"api-reference/research/playlists.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/playlists","spec":"research.json"},"searchText":"Playlist Placements Read available playlist placements for an artist. `status=current` selects current scope; `status=past` selects all-time scope, which can include current placements. `limit` is an optional raw string with no Recoup default; supported limits and coverage depend on the data connection. Research Playlists GET /api/research/playlists "},{"slug":"api-reference/research/track-playlists","title":"Track Playlists","description":"Read available track playlist and activity entries. Supply a selected track `id`, or a track name `q` with optional `artist`. Name resolution selects the first Spotify match and resolves its research ID; `id` takes precedence. Filtering and pagination support depend on the data connection. With no filter flags, editorial, indie, majorCurator and popularIndie default to true. Track-name resolution can add separately charged lookup calls; reuse a selected ID to avoid them.","category":"Research","group":"Playlists","source":"api-reference/research/track-playlists.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/research/track/playlists","spec":"research.json"},"searchText":"Track Playlists Read available track playlist and activity entries. Supply a selected track `id`, or a track name `q` with optional `artist`. Name resolution selects the first Spotify match and resolves its research ID; `id` takes precedence. Filtering and pagination support depend on the data connection. With no filter flags, editorial, indie, majorCurator and popularIndie default to true. Track-name resolution can add separately charged lookup calls; reuse a selected ID to avoid them. Research Playlists GET /api/research/track/playlists "},{"slug":"api-reference/research/web","title":"Web Search","description":"Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover.","category":"Research","group":"Web & social","source":"api-reference/research/web.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/web","spec":"research.json"},"searchText":"Web Search Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover. Research Web & social POST /api/research/web "},{"slug":"api-reference/research/deep","title":"Deep Research","description":"Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources.","category":"Research","group":"Web & social","source":"api-reference/research/deep.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/deep","spec":"research.json"},"searchText":"Deep Research Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources. Research Web & social POST /api/research/deep "},{"slug":"api-reference/research/people","title":"People Search","description":"Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data.","category":"Research","group":"Web & social","source":"api-reference/research/people.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/people","spec":"research.json"},"searchText":"People Search Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data. Research Web & social POST /api/research/people "},{"slug":"api-reference/research/extract","title":"Extract URL","description":"Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content.","category":"Research","group":"Web & social","source":"api-reference/research/extract.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/extract","spec":"research.json"},"searchText":"Extract URL Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content. Research Web & social POST /api/research/extract "},{"slug":"api-reference/research/enrich","title":"Enrich","description":"Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected.","category":"Research","group":"Web & social","source":"api-reference/research/enrich.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/research/enrich","spec":"research.json"},"searchText":"Enrich Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected. Research Web & social POST /api/research/enrich "},{"slug":"api-reference/songs/songs","title":"Get Songs","description":"Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information.","category":"Catalog","group":"Songs","source":"api-reference/songs/songs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/songs","spec":"releases.json"},"searchText":"Get Songs Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information. Catalog Songs GET /api/songs "},{"slug":"api-reference/songs/create","title":"Song creation availability","description":"Import songs into an owned catalog; standalone song creation is not available.","category":"Catalog","group":"Songs","source":"api-reference/songs/create.mdx","body":"Standalone `POST /api/songs` is not available. The API currently supports\n[`GET /api/songs`](/api-reference/songs/songs) for reading songs.\n\n## Add songs to a catalog\n\nIf you have an existing catalog you can access, use\n[`POST /api/catalogs/songs`](/api-reference/songs/catalog-songs-add).\nEach song needs its `catalog_id` and `isrc`; optional name, album, notes and\nartist names supply fallback metadata. The API checks access to every named\ncatalog before processing songs. This writes song records and catalog links;\nit is not a standalone create-only replacement.\n\n## Unfinished product decision\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) owns the\ndecision whether a separate song-creation API is needed and what ownership,\nmetadata-update and duplicate behavior it should allow. The old standalone\nrequest and response are removed from the callable specification until that\ndecision and its implementation exist. Do not omit `catalog_id` or substitute\nan unrelated catalog to make a write succeed.\n","headings":[{"title":"Add songs to a catalog","id":"add-songs-to-a-catalog"},{"title":"Unfinished product decision","id":"unfinished-product-decision"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Standalone \", _jsx(_components.code, {\n children: \"POST /api/songs\"\n }), \" is not available. The API currently supports\\n\", _jsx(_components.a, {\n href: \"/api-reference/songs/songs\",\n children: _jsx(_components.code, {\n children: \"GET /api/songs\"\n })\n }), \" for reading songs.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"add-songs-to-a-catalog\",\n children: \"Add songs to a catalog\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If you have an existing catalog you can access, use\\n\", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-add\",\n children: _jsx(_components.code, {\n children: \"POST /api/catalogs/songs\"\n })\n }), \".\\nEach song needs its \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" and \", _jsx(_components.code, {\n children: \"isrc\"\n }), \"; optional name, album, notes and\\nartist names supply fallback metadata. The API checks access to every named\\ncatalog before processing songs. This writes song records and catalog links;\\nit is not a standalone create-only replacement.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"unfinished-product-decision\",\n children: \"Unfinished product decision\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" owns the\\ndecision whether a separate song-creation API is needed and what ownership,\\nmetadata-update and duplicate behavior it should allow. The old standalone\\nrequest and response are removed from the callable specification until that\\ndecision and its implementation exist. Do not omit \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" or substitute\\nan unrelated catalog to make a write succeed.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Song creation availability Import songs into an owned catalog; standalone song creation is not available. Catalog Songs Standalone `POST /api/songs` is not available. The API currently supports [`GET /api/songs`](/api-reference/songs/songs) for reading songs. ## Add songs to a catalog If you have an existing catalog you can access, use [`POST /api/catalogs/songs`](/api-reference/songs/catalog-songs-add). Each song needs its `catalog_id` and `isrc`; optional name, album, notes and artist names supply fallback metadata. The API checks access to every named catalog before processing songs. This writes song records and catalog links; it is not a standalone create-only replacement. ## Unfinished product decision [Reconciliation #327](https://github.com/recoupable/mono/issues/327) owns the decision whether a separate song-creation API is needed and what ownership, metadata-update and duplicate behavior it should allow. The old standalone request and response are removed from the callable specification until that decision and its implementation exist. Do not omit `catalog_id` or substitute an unrelated catalog to make a write succeed. "},{"slug":"api-reference/songs/analyze","title":"Analyze Songs","description":"Analyze music using a state-of-the-art Audio Language Model ([Music Flamingo](https://www.universalmusic.com/universal-music-group-to-transform-music-experience-for-billions-of-fans-with-nvidia-ai/)) that listens directly to the audio waveform.","category":"Catalog","group":"Songs","source":"api-reference/songs/analyze.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/songs/analyze","spec":"releases.json"},"searchText":"Analyze Songs Analyze music using a state-of-the-art Audio Language Model ([Music Flamingo](https://www.universalmusic.com/universal-music-group-to-transform-music-experience-for-billions-of-fans-with-nvidia-ai/)) that listens directly to the audio waveform. Catalog Songs POST /api/songs/analyze "},{"slug":"api-reference/songs/analyze-presets","title":"List Analyze Presets","description":"Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token.","category":"Catalog","group":"Songs","source":"api-reference/songs/analyze-presets.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/songs/analyze/presets","spec":"releases.json"},"searchText":"List Analyze Presets Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token. Catalog Songs GET /api/songs/analyze/presets "},{"slug":"api-reference/songs/catalogs","title":"Get Catalogs","description":"Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalogs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/catalogs","spec":"releases.json"},"searchText":"Get Catalogs Retrieve the catalogs visible to a specific account. Returns the catalogs the account owns directly, plus the catalogs owned by any organization the account belongs to - so every member of an organization sees that organization's catalogs without passing the organization's id. A catalog owned both directly and through an organization is returned once. An account that belongs to no organization receives only its own catalogs. Create an organization-owned catalog with [Create catalog](/api-reference/songs/catalogs-create) or [Run valuation](/api-reference/songs/valuation-run). Catalog Catalogs GET /api/accounts/{id}/catalogs "},{"slug":"api-reference/songs/catalogs-create","title":"Create Catalog","description":"Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalogs-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/catalogs","spec":"releases.json"},"searchText":"Create Catalog Create a catalog, owned by the calling account or - with organization_id - by one of the caller's organizations, in which case every member of that organization sees it via [Get Catalogs](/api-reference/songs/catalogs). When materializing from a valuation snapshot, the endpoint also attaches the snapshot's canonical artist to the caller's roster: the measured songs' existing song-artist links are resolved to the dominant artist account, which is added to the caller's roster if not already present. The attach also runs on idempotent re-claims of an already-materialized snapshot. The roster attach always targets the calling account, even when the catalog is owned by an organization. Catalog Catalogs POST /api/catalogs "},{"slug":"api-reference/songs/catalog-rename","title":"Rename Catalog","description":"Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-rename.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/catalogs/{catalogId}","spec":"releases.json"},"searchText":"Rename Catalog Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete). Catalog Catalogs PATCH /api/catalogs/{catalogId} "},{"slug":"api-reference/songs/catalog-delete","title":"Delete Catalog","description":"Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations).","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/catalogs/{catalogId}","spec":"releases.json"},"searchText":"Delete Catalog Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations). Catalog Catalogs DELETE /api/catalogs/{catalogId} "},{"slug":"api-reference/songs/valuation-run","title":"Run Valuation","description":"Run valuation","category":"Catalog","group":"Catalogs","source":"api-reference/songs/valuation-run.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/valuation","spec":"releases.json"},"searchText":"Run Valuation Run valuation Catalog Catalogs POST /api/valuation "},{"slug":"api-reference/songs/runs","title":"Get Runs","description":"Get runs","category":"Catalog","group":"Catalogs","source":"api-reference/songs/runs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/runs","spec":"releases.json"},"searchText":"Get Runs Get runs Catalog Catalogs GET /api/runs "},{"slug":"api-reference/songs/catalog-measurements","title":"Get Catalog Measurements","description":"Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-measurements.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/measurements","spec":"releases.json"},"searchText":"Get Catalog Measurements Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song. Catalog Catalogs GET /api/catalogs/{catalogId}/measurements "},{"slug":"api-reference/songs/catalog-playcount-history","title":"Catalog Playcount History","description":"Read catalog playcount history and period comparisons","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-playcount-history.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/playcount-history","spec":"releases.json"},"searchText":"Catalog Playcount History Read catalog playcount history and period comparisons Catalog Catalogs GET /api/catalogs/{catalogId}/playcount-history "},{"slug":"api-reference/songs/catalog-valuations","title":"Valuation history availability","description":"Saved valuation history is unfinished; current estimates do not establish a history.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-valuations.mdx","body":"Saved catalog valuation history is not available through\n`GET /api/catalogs/{catalogId}/valuations`. Current valuation calculations and\ncatalog measurements do not establish that estimates were saved or can be read\nback as a dated series.\n\n## Existing implementation work\n\n[Reconciliation #326](https://github.com/recoupable/mono/issues/326) owns this\noutcome through [App #1911](https://github.com/recoupable/app/issues/1911) and\n[API #795](https://github.com/recoupable/api/pull/795).\n[API #1059](https://github.com/recoupable/api/pull/1059) continues that work as a\nheld draft of internal adapters. It does not register a REST route, MCP tool or\nproduction caller and does not connect successful valuation runs to persistence.\n\nThe existing owner must finish the access prerequisite, run-to-save integration,\npublic read contract and authorized deployed save/readback before this feature\ncan be advertised. Removing the unfinished operation from the callable\nspecification does not complete or cancel valuation history. Do not rerun a paid\nvaluation solely to try to recover an unconfirmed save.\n","headings":[{"title":"Existing implementation work","id":"existing-implementation-work"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Saved catalog valuation history is not available through\\n\", _jsx(_components.code, {\n children: \"GET /api/catalogs/{catalogId}/valuations\"\n }), \". Current valuation calculations and\\ncatalog measurements do not establish that estimates were saved or can be read\\nback as a dated series.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"existing-implementation-work\",\n children: \"Existing implementation work\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/326\",\n children: \"Reconciliation #326\"\n }), \" owns this\\noutcome through \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/app/issues/1911\",\n children: \"App #1911\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/795\",\n children: \"API #795\"\n }), \".\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/1059\",\n children: \"API #1059\"\n }), \" continues that work as a\\nheld draft of internal adapters. It does not register a REST route, MCP tool or\\nproduction caller and does not connect successful valuation runs to persistence.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The existing owner must finish the access prerequisite, run-to-save integration,\\npublic read contract and authorized deployed save/readback before this feature\\ncan be advertised. Removing the unfinished operation from the callable\\nspecification does not complete or cancel valuation history. Do not rerun a paid\\nvaluation solely to try to recover an unconfirmed save.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Valuation history availability Saved valuation history is unfinished; current estimates do not establish a history. Catalog Catalogs Saved catalog valuation history is not available through `GET /api/catalogs/{catalogId}/valuations`. Current valuation calculations and catalog measurements do not establish that estimates were saved or can be read back as a dated series. ## Existing implementation work [Reconciliation #326](https://github.com/recoupable/mono/issues/326) owns this outcome through [App #1911](https://github.com/recoupable/app/issues/1911) and [API #795](https://github.com/recoupable/api/pull/795). [API #1059](https://github.com/recoupable/api/pull/1059) continues that work as a held draft of internal adapters. It does not register a REST route, MCP tool or production caller and does not connect successful valuation runs to persistence. The existing owner must finish the access prerequisite, run-to-save integration, public read contract and authorized deployed save/readback before this feature can be advertised. Removing the unfinished operation from the callable specification does not complete or cancel valuation history. Do not rerun a paid valuation solely to try to recover an unconfirmed save. "},{"slug":"api-reference/songs/catalog-songs","title":"Get Catalog Songs","description":"Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs.mdx","body":"\n This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints.\n\n\nA successful query with no matching songs returns HTTP `200`, an empty `songs`\narray, and `pagination.total_count: 0`. This also applies to an accessible catalog\nwith no songs. An empty result is not a `404` response.\n\nUse a nonempty `artistName` to request songs with a matching artist name. Omit the filter to\ninclude songs without a linked artist. Filtering applies before pagination and\nthe total count; a client can use a zero count to decide whether to retry without\nthe artist filter.\n\nMissing or inaccessible catalogs return `403`. A server or database failure\nreturns `500` with `status: \"error\"` and `error: \"Internal server error\"`.\n","headings":[],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the \", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-add\",\n children: \"Add Catalog Songs\"\n }), \" and \", _jsx(_components.a, {\n href: \"/api-reference/songs/catalog-songs-delete\",\n children: \"Remove Catalog Songs\"\n }), \" endpoints.\"]\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A successful query with no matching songs returns HTTP \", _jsx(_components.code, {\n children: \"200\"\n }), \", an empty \", _jsx(_components.code, {\n children: \"songs\"\n }), \"\\narray, and \", _jsx(_components.code, {\n children: \"pagination.total_count: 0\"\n }), \". This also applies to an accessible catalog\\nwith no songs. An empty result is not a \", _jsx(_components.code, {\n children: \"404\"\n }), \" response.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use a nonempty \", _jsx(_components.code, {\n children: \"artistName\"\n }), \" to request songs with a matching artist name. Omit the filter to\\ninclude songs without a linked artist. Filtering applies before pagination and\\nthe total count; a client can use a zero count to decide whether to retry without\\nthe artist filter.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Missing or inaccessible catalogs return \", _jsx(_components.code, {\n children: \"403\"\n }), \". A server or database failure\\nreturns \", _jsx(_components.code, {\n children: \"500\"\n }), \" with \", _jsx(_components.code, {\n children: \"status: \\\"error\\\"\"\n }), \" and \", _jsx(_components.code, {\n children: \"error: \\\"Internal server error\\\"\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"GET","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Get Catalog Songs Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0. Catalog Catalogs GET /api/catalogs/songs This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints. A successful query with no matching songs returns HTTP `200`, an empty `songs` array, and `pagination.total_count: 0`. This also applies to an accessible catalog with no songs. An empty result is not a `404` response. Use a nonempty `artistName` to request songs with a matching artist name. Omit the filter to include songs without a linked artist. Filtering applies before pagination and the total count; a client can use a zero count to decide whether to retry without the artist filter. Missing or inaccessible catalogs return `403`. A server or database failure returns `500` with `status: \"error\"` and `error: \"Internal server error\"`. "},{"slug":"api-reference/songs/catalog-songs-add","title":"Add Catalog Songs","description":"Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs-add.mdx","body":"\n For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.\n\n","headings":[],"compiled":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.\"\n })\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"POST","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Add Catalog Songs Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used. Catalog Catalogs POST /api/catalogs/songs For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used. "},{"slug":"api-reference/songs/catalog-songs-delete","title":"Remove Catalog Songs","description":"Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair.","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-songs-delete.mdx","body":"\n This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted.\n\n","headings":[],"compiled":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ...props.components\n }, {Note} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n return _jsx(Note, {\n children: _jsxs(_components.p, {\n children: [\"This endpoint removes the relationship in \", _jsx(_components.code, {\n children: \"catalog_songs\"\n }), \" for each \", _jsx(_components.code, {\n children: \"catalog_id\"\n }), \" and ISRC pair. The song data itself is not deleted.\"]\n })\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"DELETE","path":"/api/catalogs/songs","spec":"releases.json"},"searchText":"Remove Catalog Songs Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair. Catalog Catalogs DELETE /api/catalogs/songs This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted. "},{"slug":"api-reference/songs/catalog-streams","title":"Daily Catalog Streams","description":"Read daily catalog streams","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-streams.mdx","body":"## Date range and coverage\n\nSet `days` to an integer from 1 to 366 days. For example, use `days=90` for a 90-day comparison period. `since` is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive.\n\nA supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while `pagination.has_more` is true. Missing measurements suppress growth; they do not establish zero streams.\n\nThe catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection.\n","headings":[{"title":"Date range and coverage","id":"date-range-and-coverage"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"date-range-and-coverage\",\n children: \"Date range and coverage\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Set \", _jsx(_components.code, {\n children: \"days\"\n }), \" to an integer from 1 to 366 days. For example, use \", _jsx(_components.code, {\n children: \"days=90\"\n }), \" for a 90-day comparison period. \", _jsx(_components.code, {\n children: \"since\"\n }), \" is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while \", _jsx(_components.code, {\n children: \"pagination.has_more\"\n }), \" is true. Missing measurements suppress growth; they do not establish zero streams.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","api":{"method":"GET","path":"/api/catalogs/{catalogId}/streams","spec":"releases.json"},"searchText":"Daily Catalog Streams Read daily catalog streams Catalog Catalogs GET /api/catalogs/{catalogId}/streams ## Date range and coverage Set `days` to an integer from 1 to 366 days. For example, use `days=90` for a 90-day comparison period. `since` is the inclusive start of the current period; the previous period has the same length and immediately precedes it. End dates are exclusive. A supported date range does not prove complete measurements or historical backfill. Inspect each recording's coverage and missing dates before using growth comparisons, and continue through pages while `pagination.has_more` is true. Missing measurements suppress growth; they do not establish zero streams. The catalog playcount-history operation has a separate 31-day maximum. It reports saved Spotify playcount observations; this endpoint reports saved worldwide aggregate daily streams across reporting services. Neither is a royalty statement. These reads do not start provider collection. "},{"slug":"api-reference/songs/catalog-stream-tracking","title":"Catalog Stream Tracking","description":"Inspect daily catalog tracking","category":"Catalog","group":"Catalogs","source":"api-reference/songs/catalog-stream-tracking.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/catalogs/{catalogId}/stream-tracking","spec":"releases.json"},"searchText":"Catalog Stream Tracking Inspect daily catalog tracking Catalog Catalogs GET /api/catalogs/{catalogId}/stream-tracking "},{"slug":"api-reference/songs/update-catalog-stream-tracking","title":"Update Catalog Stream Tracking","description":"Control daily catalog tracking","category":"Catalog","group":"Catalogs","source":"api-reference/songs/update-catalog-stream-tracking.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/catalogs/{catalogId}/stream-tracking","spec":"releases.json"},"searchText":"Update Catalog Stream Tracking Control daily catalog tracking Catalog Catalogs POST /api/catalogs/{catalogId}/stream-tracking "},{"slug":"api-reference/context/operate","title":"Context Engine","description":"Ingest, read, or compile context briefs","category":"Catalog","group":"Context","source":"api-reference/context/operate.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context","spec":"context.json"},"searchText":"Context Engine Ingest, read, or compile context briefs Catalog Context POST /api/context "},{"slug":"api-reference/context/guest-start","title":"Start guest context","description":"Start guest context extraction","category":"Catalog","group":"Context","source":"api-reference/context/guest-start.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context/guest","spec":"context.json"},"searchText":"Start guest context Start guest context extraction Catalog Context POST /api/context/guest "},{"slug":"api-reference/context/guest-read","title":"Read guest context","description":"Read guest context","category":"Catalog","group":"Context","source":"api-reference/context/guest-read.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/context/guest","spec":"context.json"},"searchText":"Read guest context Read guest context Catalog Context GET /api/context/guest "},{"slug":"api-reference/context/guest-claim","title":"Claim guest context","description":"Claim guest context after sign-in","category":"Catalog","group":"Context","source":"api-reference/context/guest-claim.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/context/guest/claim","spec":"context.json"},"searchText":"Claim guest context Claim guest context after sign-in Catalog Context POST /api/context/guest/claim "},{"slug":"workflows/generate-music-video","title":"Generate a Music Video","description":"End-to-end workflow to produce a vertical, social-ready music video — image, motion, caption — from an artist and a song.","category":"Content","group":"Workflows","source":"workflows/generate-music-video.mdx","body":"This is the canonical recipe used internally by Recoup's `create-content` background task. Two paths are documented below: the **async pipeline** that an LLM agent should use, and the **manual recipe** for humans (or for cases where you want to swap a single step).\n\n## Hand it to your LLM\n\nThe fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a `.md` suffix, so models can fetch and follow it without parsing HTML:\n\n```\nGenerate a music video for The Weeknd – \"Blinding Lights\" using\nhttps://docs.recoupable.dev/workflows/generate-music-video.md\n```\n\nSwap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL.\n\n## Running as an agent? Use the async pipeline\n\n`POST /api/content/video` is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments.\n\nUse the async path instead — same five steps, run server-side:\n\n```bash\n# Trigger\nRUN_IDS=$(curl -sS -X POST \"https://api.recoupable.dev/api/content/create\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" -H \"Content-Type: application/json\" \\\n -d \"$(jq -n --arg artist \"$ARTIST_ACCOUNT_ID\" --arg template \"$TEMPLATE\" \\\n '{artist_account_id: $artist, template: $template}')\" \\\n | jq -r '.runIds[]')\n\n# Poll (every ~10s) until COMPLETED / FAILED / CANCELED / CRASHED\nRUN_ID=$(echo \"$RUN_IDS\" | head -1)\nuntil STATUS=$(curl -sS \"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq -r '.runs[0].status') && \\\n [[ \"$STATUS\" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do\n sleep 10\ndone\n\n# Read the output\ncurl -sS \"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq '.runs[0].output'\n# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }\n```\n\nPolling fits inside short shell timeouts and survives session restarts. See [Tasks Runs](/api-reference/tasks/runs) for the full status enum (`QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, etc.) and the `CreateContentRunOutput` schema.\n\n### Resolving `$ARTIST_ACCOUNT_ID`\n\n`POST /api/content/create` needs the artist's `account_id`. Three calls:\n\n```bash\nORG_ID=$(curl -sS \"https://api.recoupable.dev/api/organizations\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" | jq -r '.organizations[0].id')\n\nARTIST_ACCOUNT_ID=$(curl -sS \"https://api.recoupable.dev/api/artists?org_id=$ORG_ID\" \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n | jq -r --arg name \"$ARTIST_NAME\" '.artists[] | select(.name == $name) | .account_id')\n```\n\nThe artist record exposes both `id` and `account_id` (both UUIDs). Use **`account_id`** — `id` is the artist row's primary key, `account_id` is the underlying account that owns it. The two are easy to swap; you'll get a 404 from `/api/content/create` if you pass the wrong one.\n\n## Where the song lives\n\nStep 5 (and the async pipeline's lipsync mode) need a `song.mp3`. **Don't assume one exists, and don't assume the user has one locally.** Walk the agent through this fallback chain:\n\n1. **Check the artist's sandbox repo first.** Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths:\n\n ```\n .openclaw/workspace/orgs/{org-slug}/artists/{artist-slug}/songs/{song-slug}/{song-slug}.mp3\n /lyrics.json\n /clips.json\n ```\n\n Discover the repo with [`GET /api/sandboxes`](/api-reference/sandboxes/list) (returns `github_repo` and a `filetree`); fetch a file with [`GET /api/sandboxes/file?path=…`](/api-reference/sandboxes/file). **Binary files (`.mp3`, `.png`, `.mp4`) come back base64-encoded in the `content` field — decode before writing to disk.**\n\n2. **If no song is in the sandbox, ask the user how to proceed.** Two options to offer:\n - *\"Want me to fetch the audio from YouTube?\"* — agent downloads via `yt-dlp` (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications.\n - *\"Want to supply the song yourself?\"* — user uploads / drops a path; agent reads from there.\n\n Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call.\n\n3. **Don't fall back to \"use a placeholder track.\"** A music video without the song is not a deliverable.\n\n## Manual recipe (humans + targeted overrides)\n\nThe rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length).\n\n### Prerequisites\n\n- An auth credential for `api.recoupable.dev`. Two options — pick one and use it for every call below:\n - **API key** (`recoup_sk_…`, recommended for sandbox / agent use): pass as `-H \"x-api-key: $RECOUP_API_KEY\"`.\n - One-shot agent: `POST /api/agents/signup` with an `agent+{unique}@recoupable.com` email returns the key immediately.\n - Real-email signup: same endpoint with a real email mails a 6-digit code; complete with `POST /api/agents/verify`. See [Agents](/agents).\n - **Privy access token** (for end-user flows in chat/UI): pass as `-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\"`.\n - The examples below use `x-api-key`. Substitute `Authorization: Bearer …` if you're using a Privy token.\n- `$ARTIST_NAME`, `$SONG_TITLE`, `$SONG_LYRICS_CLIP` (a 1–2 sentence mood snippet)\n- `$REFERENCE_IMAGE_URL` *(optional)* — an artist photo or album cover to seed the image; if your template's purpose is \"show this exact image\" (e.g. `album-record-store`), set this and skip image generation in step 2\n- A `song.mp3` for step 5. **Don't ask the user for a local file** — fetch from the artist's repo via `/api/sandboxes/file`.\n- `ffmpeg` installed locally for step 5\n\n### Step 0: Scaffold the workspace BEFORE any API call\n\nThe `VIDEO.md` checklist *is* the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box.\n\n```bash\nVIDEO_SLUG=$(echo \"$SONG_TITLE\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-//; s/-$//')\nVIDEO_DIR=\"videos/$VIDEO_SLUG\"\nmkdir -p \"$VIDEO_DIR\"\n\ncat > \"$VIDEO_DIR/VIDEO.md\" < \"$VIDEO_DIR/caption.txt\"\n\n# Single-line filter graph — newlines inside -filter_complex are literal characters and break the [v] label\nffmpeg -y \\\n -stream_loop -1 -i \"$VIDEO_DIR/clip.mp4\" \\\n -i \"$SONG_PATH\" \\\n -filter_complex \"[0:v]crop=ih*9/16:ih,scale=1080:1920,drawtext=fontfile=$CAPTION_FONT:textfile=$VIDEO_DIR/caption.txt:fontcolor=$CAPTION_COLOR:fontsize=$CAPTION_FONT_SIZE:x=(w-text_w)/2:y=h-text_h-120:box=1:boxcolor=$CAPTION_STROKE@0.5:boxborderw=20[v]\" \\\n -map \"[v]\" -map \"1:a\" \\\n -shortest -c:v libx264 -c:a aac -pix_fmt yuv420p \\\n \"$FINAL_PATH\"\n```\n\n**After:** write `finalVideoPath`, tick the box. With every box ticked, the music video is complete.\n\n## Step 6: Publish (optional)\n\nOnce the MP4 is rendered, push it to the artist's socials with the [Connectors API](/api-reference/connectors/list). One heads-up worth knowing:\n\n- **TikTok URL ownership.** `TIKTOK_PUBLISH_VIDEO` (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. `fal.media` URLs will fail with `url_ownership_unverified` — use `TIKTOK_UPLOAD_VIDEO` instead, which accepts the same URL and uploads server-side.\n\n---\n\nThe checklist is the source of truth — if a box isn't ticked, treat the step as not run.\n","headings":[{"title":"Hand it to your LLM","id":"hand-it-to-your-llm"},{"title":"Running as an agent? Use the async pipeline","id":"running-as-an-agent-use-the-async-pipeline"},{"title":"Where the song lives","id":"where-the-song-lives"},{"title":"Manual recipe (humans + targeted overrides)","id":"manual-recipe-humans-targeted-overrides"},{"title":"Step 6: Publish (optional)","id":"step-6-publish-optional"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n em: \"em\",\n h2: \"h2\",\n h3: \"h3\",\n hr: \"hr\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"This is the canonical recipe used internally by Recoup's \", _jsx(_components.code, {\n children: \"create-content\"\n }), \" background task. Two paths are documented below: the \", _jsx(_components.strong, {\n children: \"async pipeline\"\n }), \" that an LLM agent should use, and the \", _jsx(_components.strong, {\n children: \"manual recipe\"\n }), \" for humans (or for cases where you want to swap a single step).\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hand-it-to-your-llm\",\n children: \"Hand it to your LLM\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a \", _jsx(_components.code, {\n children: \".md\"\n }), \" suffix, so models can fetch and follow it without parsing HTML:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \"Generate a music video for The Weeknd – \\\"Blinding Lights\\\" using\\nhttps://docs.recoupable.dev/workflows/generate-music-video.md\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Swap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"running-as-an-agent-use-the-async-pipeline\",\n children: \"Running as an agent? Use the async pipeline\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/video\"\n }), \" is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the async path instead — same five steps, run server-side:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"# Trigger\\nRUN_IDS=$(curl -sS -X POST \\\"https://api.recoupable.dev/api/content/create\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" -H \\\"Content-Type: application/json\\\" \\\\\\n -d \\\"$(jq -n --arg artist \\\"$ARTIST_ACCOUNT_ID\\\" --arg template \\\"$TEMPLATE\\\" \\\\\\n '{artist_account_id: $artist, template: $template}')\\\" \\\\\\n | jq -r '.runIds[]')\\n\\n# Poll (every ~10s) until COMPLETED / FAILED / CANCELED / CRASHED\\nRUN_ID=$(echo \\\"$RUN_IDS\\\" | head -1)\\nuntil STATUS=$(curl -sS \\\"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq -r '.runs[0].status') && \\\\\\n [[ \\\"$STATUS\\\" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do\\n sleep 10\\ndone\\n\\n# Read the output\\ncurl -sS \\\"https://api.recoupable.dev/api/tasks/runs?runId=$RUN_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq '.runs[0].output'\\n# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Polling fits inside short shell timeouts and survives session restarts. See \", _jsx(_components.a, {\n href: \"/api-reference/tasks/runs\",\n children: \"Tasks Runs\"\n }), \" for the full status enum (\", _jsx(_components.code, {\n children: \"QUEUED\"\n }), \", \", _jsx(_components.code, {\n children: \"EXECUTING\"\n }), \", \", _jsx(_components.code, {\n children: \"COMPLETED\"\n }), \", \", _jsx(_components.code, {\n children: \"FAILED\"\n }), \", \", _jsx(_components.code, {\n children: \"CANCELED\"\n }), \", \", _jsx(_components.code, {\n children: \"CRASHED\"\n }), \", etc.) and the \", _jsx(_components.code, {\n children: \"CreateContentRunOutput\"\n }), \" schema.\"]\n }), \"\\n\", _jsxs(_components.h3, {\n id: \"resolving-artistaccountid\",\n children: [\"Resolving \", _jsx(_components.code, {\n children: \"$ARTIST_ACCOUNT_ID\"\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/create\"\n }), \" needs the artist's \", _jsx(_components.code, {\n children: \"account_id\"\n }), \". Three calls:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"ORG_ID=$(curl -sS \\\"https://api.recoupable.dev/api/organizations\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" | jq -r '.organizations[0].id')\\n\\nARTIST_ACCOUNT_ID=$(curl -sS \\\"https://api.recoupable.dev/api/artists?org_id=$ORG_ID\\\" \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n | jq -r --arg name \\\"$ARTIST_NAME\\\" '.artists[] | select(.name == $name) | .account_id')\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The artist record exposes both \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" (both UUIDs). Use \", _jsx(_components.strong, {\n children: _jsx(_components.code, {\n children: \"account_id\"\n })\n }), \" — \", _jsx(_components.code, {\n children: \"id\"\n }), \" is the artist row's primary key, \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" is the underlying account that owns it. The two are easy to swap; you'll get a 404 from \", _jsx(_components.code, {\n children: \"/api/content/create\"\n }), \" if you pass the wrong one.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"where-the-song-lives\",\n children: \"Where the song lives\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Step 5 (and the async pipeline's lipsync mode) need a \", _jsx(_components.code, {\n children: \"song.mp3\"\n }), \". \", _jsx(_components.strong, {\n children: \"Don't assume one exists, and don't assume the user has one locally.\"\n }), \" Walk the agent through this fallback chain:\"]\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Check the artist's sandbox repo first.\"\n }), \" Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n children: \".openclaw/workspace/orgs/{org-slug}/artists/{artist-slug}/songs/{song-slug}/{song-slug}.mp3\\n /lyrics.json\\n /clips.json\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Discover the repo with \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/list\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes\"\n })\n }), \" (returns \", _jsx(_components.code, {\n children: \"github_repo\"\n }), \" and a \", _jsx(_components.code, {\n children: \"filetree\"\n }), \"); fetch a file with \", _jsx(_components.a, {\n href: \"/api-reference/sandboxes/file\",\n children: _jsx(_components.code, {\n children: \"GET /api/sandboxes/file?path=…\"\n })\n }), \". \", _jsxs(_components.strong, {\n children: [\"Binary files (\", _jsx(_components.code, {\n children: \".mp3\"\n }), \", \", _jsx(_components.code, {\n children: \".png\"\n }), \", \", _jsx(_components.code, {\n children: \".mp4\"\n }), \") come back base64-encoded in the \", _jsx(_components.code, {\n children: \"content\"\n }), \" field — decode before writing to disk.\"]\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"If no song is in the sandbox, ask the user how to proceed.\"\n }), \" Two options to offer:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.em, {\n children: \"\\\"Want me to fetch the audio from YouTube?\\\"\"\n }), \" — agent downloads via \", _jsx(_components.code, {\n children: \"yt-dlp\"\n }), \" (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.em, {\n children: \"\\\"Want to supply the song yourself?\\\"\"\n }), \" — user uploads / drops a path; agent reads from there.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Don't fall back to \\\"use a placeholder track.\\\"\"\n }), \" A music video without the song is not a deliverable.\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"manual-recipe-humans-targeted-overrides\",\n children: \"Manual recipe (humans + targeted overrides)\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length).\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"prerequisites\",\n children: \"Prerequisites\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"An auth credential for \", _jsx(_components.code, {\n children: \"api.recoupable.dev\"\n }), \". Two options — pick one and use it for every call below:\", \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"API key\"\n }), \" (\", _jsx(_components.code, {\n children: \"recoup_sk_…\"\n }), \", recommended for sandbox / agent use): pass as \", _jsx(_components.code, {\n children: \"-H \\\"x-api-key: $RECOUP_API_KEY\\\"\"\n }), \".\", \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"One-shot agent: \", _jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" with an \", _jsx(_components.code, {\n children: \"agent+{unique}@recoupable.com\"\n }), \" email returns the key immediately.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Real-email signup: same endpoint with a real email mails a 6-digit code; complete with \", _jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \". See \", _jsx(_components.a, {\n href: \"/agents\",\n children: \"Agents\"\n }), \".\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Privy access token\"\n }), \" (for end-user flows in chat/UI): pass as \", _jsx(_components.code, {\n children: \"-H \\\"Authorization: Bearer $RECOUP_ACCESS_TOKEN\\\"\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The examples below use \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \". Substitute \", _jsx(_components.code, {\n children: \"Authorization: Bearer …\"\n }), \" if you're using a Privy token.\"]\n }), \"\\n\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$ARTIST_NAME\"\n }), \", \", _jsx(_components.code, {\n children: \"$SONG_TITLE\"\n }), \", \", _jsx(_components.code, {\n children: \"$SONG_LYRICS_CLIP\"\n }), \" (a 1–2 sentence mood snippet)\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"$REFERENCE_IMAGE_URL\"\n }), \" \", _jsx(_components.em, {\n children: \"(optional)\"\n }), \" — an artist photo or album cover to seed the image; if your template's purpose is \\\"show this exact image\\\" (e.g. \", _jsx(_components.code, {\n children: \"album-record-store\"\n }), \"), set this and skip image generation in step 2\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"A \", _jsx(_components.code, {\n children: \"song.mp3\"\n }), \" for step 5. \", _jsx(_components.strong, {\n children: \"Don't ask the user for a local file\"\n }), \" — fetch from the artist's repo via \", _jsx(_components.code, {\n children: \"/api/sandboxes/file\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"ffmpeg\"\n }), \" installed locally for step 5\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"step-0-scaffold-the-workspace-before-any-api-call\",\n children: \"Step 0: Scaffold the workspace BEFORE any API call\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.code, {\n children: \"VIDEO.md\"\n }), \" checklist \", _jsx(_components.em, {\n children: \"is\"\n }), \" the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"VIDEO_SLUG=$(echo \\\"$SONG_TITLE\\\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-//; s/-$//')\\nVIDEO_DIR=\\\"videos/$VIDEO_SLUG\\\"\\nmkdir -p \\\"$VIDEO_DIR\\\"\\n\\ncat > \\\"$VIDEO_DIR/VIDEO.md\\\" < \\\"$VIDEO_DIR/caption.txt\\\"\\n\\n# Single-line filter graph — newlines inside -filter_complex are literal characters and break the [v] label\\nffmpeg -y \\\\\\n -stream_loop -1 -i \\\"$VIDEO_DIR/clip.mp4\\\" \\\\\\n -i \\\"$SONG_PATH\\\" \\\\\\n -filter_complex \\\"[0:v]crop=ih*9/16:ih,scale=1080:1920,drawtext=fontfile=$CAPTION_FONT:textfile=$VIDEO_DIR/caption.txt:fontcolor=$CAPTION_COLOR:fontsize=$CAPTION_FONT_SIZE:x=(w-text_w)/2:y=h-text_h-120:box=1:boxcolor=$CAPTION_STROKE@0.5:boxborderw=20[v]\\\" \\\\\\n -map \\\"[v]\\\" -map \\\"1:a\\\" \\\\\\n -shortest -c:v libx264 -c:a aac -pix_fmt yuv420p \\\\\\n \\\"$FINAL_PATH\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"After:\"\n }), \" write \", _jsx(_components.code, {\n children: \"finalVideoPath\"\n }), \", tick the box. With every box ticked, the music video is complete.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"step-6-publish-optional\",\n children: \"Step 6: Publish (optional)\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Once the MP4 is rendered, push it to the artist's socials with the \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors API\"\n }), \". One heads-up worth knowing:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"TikTok URL ownership.\"\n }), \" \", _jsx(_components.code, {\n children: \"TIKTOK_PUBLISH_VIDEO\"\n }), \" (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. \", _jsx(_components.code, {\n children: \"fal.media\"\n }), \" URLs will fail with \", _jsx(_components.code, {\n children: \"url_ownership_unverified\"\n }), \" — use \", _jsx(_components.code, {\n children: \"TIKTOK_UPLOAD_VIDEO\"\n }), \" instead, which accepts the same URL and uploads server-side.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.p, {\n children: \"The checklist is the source of truth — if a box isn't ticked, treat the step as not run.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Generate a Music Video End-to-end workflow to produce a vertical, social-ready music video — image, motion, caption — from an artist and a song. Content Workflows This is the canonical recipe used internally by Recoup's `create-content` background task. Two paths are documented below: the **async pipeline** that an LLM agent should use, and the **manual recipe** for humans (or for cases where you want to swap a single step). ## Hand it to your LLM The fastest way to use this guide is to point an LLM at it directly — every page on this site is also served as raw markdown at the same path with a `.md` suffix, so models can fetch and follow it without parsing HTML: Swap in your own artist and song. The LLM will resolve the artist, kick off the async pipeline, poll until done, and pull back the final video URL. ## Running as an agent? Use the async pipeline `POST /api/content/video` is synchronous and routinely takes 60–180s. Most agent shells (Claude Cowork, OpenAI tool calls, etc.) cap a single command at 30–60s and kill background processes when the shell exits — the manual recipe below is effectively un-runnable from those environments. Use the async path instead — same five steps, run server-side: Polling fits inside short shell timeouts and survives session restarts. See [Tasks Runs](/api-reference/tasks/runs) for the full status enum (`QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, etc.) and the `CreateContentRunOutput` schema. ### Resolving `$ARTIST_ACCOUNT_ID` `POST /api/content/create` needs the artist's `account_id`. Three calls: The artist record exposes both `id` and `account_id` (both UUIDs). Use **`account_id`** — `id` is the artist row's primary key, `account_id` is the underlying account that owns it. The two are easy to swap; you'll get a 404 from `/api/content/create` if you pass the wrong one. ## Where the song lives Step 5 (and the async pipeline's lipsync mode) need a `song.mp3`. **Don't assume one exists, and don't assume the user has one locally.** Walk the agent through this fallback chain: 1. **Check the artist's sandbox repo first.** Each Recoup account has a backing GitHub repo. If the user has imported songs through Recoup, they live at predictable paths: Discover the repo with [`GET /api/sandboxes`](/api-reference/sandboxes/list) (returns `github_repo` and a `filetree`); fetch a file with [`GET /api/sandboxes/file?path=…`](/api-reference/sandboxes/file). **Binary files (`.mp3`, `.png`, `.mp4`) come back base64-encoded in the `content` field — decode before writing to disk.** 2. **If no song is in the sandbox, ask the user how to proceed.** Two options to offer: - *\"Want me to fetch the audio from YouTube?\"* — agent downloads via `yt-dlp` (or equivalent), saves locally; user is responsible for any rights / DSP-licensing implications. - *\"Want to supply the song yourself?\"* — user uploads / drops a path; agent reads from there. Don't pick a path silently. The cost of fetching the wrong song from YouTube (or fetching one at all) is enough that the user should make the call. 3. **Don't fall back to \"use a placeholder track.\"** A music video without the song is not a deliverable. ## Manual recipe (humans + targeted overrides) The rest of this page walks the same steps you can run by hand or call individually if you want to swap a single stage (different prompt for image, different motion, different caption length). ### Prerequisites - An auth credential for `api.recoupable.dev`. Two options — pick one and use it for every call below: - **API key** (`recoup_sk_…`, recommended for sandbox / agent use): pass as `-H \"x-api-key: $RECOUP_API_KEY\"`. - One-shot agent: `POST /api/agents/signup` with an `agent+{unique}@recoupable.com` email returns the key immediately. - Real-email signup: same endpoint with a real email mails a 6-digit code; complete with `POST /api/agents/verify`. See [Agents](/agents). - **Privy access token** (for end-user flows in chat/UI): pass as `-H \"Authorization: Bearer $RECOUP_ACCESS_TOKEN\"`. - The examples below use `x-api-key`. Substitute `Authorization: Bearer …` if you're using a Privy token. - `$ARTIST_NAME`, `$SONG_TITLE`, `$SONG_LYRICS_CLIP` (a 1–2 sentence mood snippet) - `$REFERENCE_IMAGE_URL` *(optional)* — an artist photo or album cover to seed the image; if your template's purpose is \"show this exact image\" (e.g. `album-record-store`), set this and skip image generation in step 2 - A `song.mp3` for step 5. **Don't ask the user for a local file** — fetch from the artist's repo via `/api/sandboxes/file`. - `ffmpeg` installed locally for step 5 ### Step 0: Scaffold the workspace BEFORE any API call The `VIDEO.md` checklist *is* the workflow state — tick boxes and persist values back to the frontmatter as you go. To resume later, find the first unchecked box. ### Step 1: Pick a template (required: list **and** detail) Templates carry the prompt, reference images, and styling that drive the rest of the chain — you can't write a good Step 2 prompt without them. List, pick, then fetch detail: **Templates that list \"Requires: face image\"** (e.g. `artist-caption-bedroom`) will fall back to their bundled reference images and produce a generic-likeness subject if you don't supply one — they don't 400. Pass `$REFERENCE_IMAGE_URL` if you want the model to preserve a specific artist's likeness, or omit it for a stock-feeling result. See [List Templates](/api-reference/content/templates) and [Template Detail](/api-reference/content/template-detail). **After:** write `template` into frontmatter, tick the box. ### Step 2: Generate the base image Use the template's own prompt and reference images — don't write your own from scratch. The template encodes the visual style; freeform prompts almost always drift off-brand. **Shortcut:** if `$REFERENCE_IMAGE_URL` is the exact image you want (e.g. an album cover for `album-record-store`, or a final editorial photo), set `IMAGE_URL=$REFERENCE_IMAGE_URL` and skip this call entirely. **Avoid:** prompts that aim for a real artist's likeness. Veo (used in step 3) rejects celebrity-likeness images with a 422. Use the template's prompt as-is and let the reference images carry the style. See [Generate Image](/api-reference/content/generate-image). **After:** write `imageUrl`, tick the box. ### Optional: Upscale (image or video) Same endpoint for both, swap `type`. Skip if you don't need the resolution bump. See [Upscale](/api-reference/content/upscale). ### Step 3: Generate the video Pass the image and a short motion prompt. For lipsync, also pass a presigned `audio_url` to a song clip — the model will animate the artist's mouth. This call routinely takes 60–180s. **From a short-shell agent, use the async pipeline at the top of this page instead.** From a long-lived shell, output is an 8s clip. Step 5 loops it to song length. See [Generate Video](/api-reference/content/generate-video). **After:** write `videoUrl`, tick the box. ### Step 4: Generate the caption `length` accepts `\"short\"` (default), `\"medium\"`, `\"long\"`, or `\"none\"` to skip. The four styling fields (`font`, `color`, `borderColor`, `maxFontSize`) are template-driven hints — Step 5 wires them into ffmpeg's `drawtext` so the burned-in caption matches the template's brand. See [Generate Caption](/api-reference/content/generate-caption). **After:** write `captionText`, tick the box. ### Step 5: Compose the final 9:16 video (local) The API returns a 16:9 motion clip. Compose locally: crop to 9:16, overlay the song audio for the full duration, and burn in the caption with the styling from step 4. **After:** write `finalVideoPath`, tick the box. With every box ticked, the music video is complete. ## Step 6: Publish (optional) Once the MP4 is rendered, push it to the artist's socials with the [Connectors API](/api-reference/connectors/list). One heads-up worth knowing: - **TikTok URL ownership.** `TIKTOK_PUBLISH_VIDEO` (pull-from-URL mode) requires the source domain be verified in the TikTok dev portal. `fal.media` URLs will fail with `url_ownership_unverified` — use `TIKTOK_UPLOAD_VIDEO` instead, which accepts the same URL and uploads server-side. --- The checklist is the source of truth — if a box isn't ticked, treat the step as not run. "},{"slug":"api-reference/content/create","title":"Create Content","description":"Trigger 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).","category":"Content","group":"Content Creation","source":"api-reference/content/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/create","spec":"content.json"},"searchText":"Create Content Trigger 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). Content Content Creation POST /api/content/create "},{"slug":"api-reference/content/generate-image","title":"Generate Image","description":"Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL.","category":"Content","group":"Content Creation","source":"api-reference/content/generate-image.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/image","spec":"content.json"},"searchText":"Generate Image Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL. Content Content Creation POST /api/content/image "},{"slug":"api-reference/content/generate-video","title":"Generate Video","description":"Generate a video from a text prompt, optionally animating a still image (`image_url`) or transitioning between two images (`image_url` + `end_image_url`).","category":"Content","group":"Content Creation","source":"api-reference/content/generate-video.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/video","spec":"content.json"},"searchText":"Generate Video Generate a video from a text prompt, optionally animating a still image (`image_url`) or transitioning between two images (`image_url` + `end_image_url`). Content Content Creation POST /api/content/video "},{"slug":"api-reference/content/generate-caption","title":"Generate Caption","description":"Generate a short caption from a topic. Returns the text content and default styling (font, color, size).","category":"Content","group":"Content Creation","source":"api-reference/content/generate-caption.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/caption","spec":"content.json"},"searchText":"Generate Caption Generate a short caption from a topic. Returns the text content and default styling (font, color, size). Content Content Creation POST /api/content/caption "},{"slug":"api-reference/content/transcribe-audio","title":"Transcribe Audio","description":"Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments.","category":"Content","group":"Content Creation","source":"api-reference/content/transcribe-audio.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/transcribe","spec":"content.json"},"searchText":"Transcribe Audio Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments. Content Content Creation POST /api/content/transcribe "},{"slug":"api-reference/content/edit","title":"Edit Content","description":"Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.","category":"Content","group":"Content Creation","source":"api-reference/content/edit.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/content","spec":"content.json"},"searchText":"Edit Content Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array. Content Content Creation PATCH /api/content "},{"slug":"api-reference/content/upscale","title":"Upscale Content","description":"Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL.","category":"Content","group":"Content Creation","source":"api-reference/content/upscale.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/upscale","spec":"content.json"},"searchText":"Upscale Content Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL. Content Content Creation POST /api/content/upscale "},{"slug":"api-reference/content/analyze-video","title":"Analyze Video","description":"Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text.","category":"Content","group":"Content Creation","source":"api-reference/content/analyze-video.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/analyze","spec":"content.json"},"searchText":"Analyze Video Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text. Content Content Creation POST /api/content/analyze "},{"slug":"api-reference/content/templates","title":"List Templates","description":"List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one.","category":"Content","group":"Content Creation","source":"api-reference/content/templates.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/templates","spec":"content.json"},"searchText":"List Templates List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one. Content Content Creation GET /api/content/templates "},{"slug":"api-reference/content/template-detail","title":"Get Template Detail","description":"Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations.","category":"Content","group":"Content Creation","source":"api-reference/content/template-detail.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/templates/{id}","spec":"content.json"},"searchText":"Get Template Detail Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations. Content Content Creation GET /api/content/templates/{id} "},{"slug":"api-reference/content/validate","title":"Validate Artist","description":"Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter.","category":"Content","group":"Content Creation","source":"api-reference/content/validate.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/validate","spec":"content.json"},"searchText":"Validate Artist Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter. Content Content Creation GET /api/content/validate "},{"slug":"api-reference/content/estimate","title":"Estimate Cost","description":"Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits.","category":"Content","group":"Content Creation","source":"api-reference/content/estimate.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/content/estimate","spec":"content.json"},"searchText":"Estimate Cost Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits. Content Content Creation GET /api/content/estimate "},{"slug":"api-reference/image/generation","title":"Generate Image","description":"Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking.","category":"Content","group":"Content Creation","source":"api-reference/image/generation.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/image/generate","spec":"content.json"},"searchText":"Generate Image Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking. Content Content Creation GET /api/image/generate "},{"slug":"api-reference/transcribe/audio","title":"Transcribe Audio","description":"Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage. The owner account is derived from your credentials; you must have access to the specified artist_account_id.","category":"Content","group":"Content Creation","source":"api-reference/transcribe/audio.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/transcribe","spec":"content.json"},"searchText":"Transcribe Audio Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage. The owner account is derived from your credentials; you must have access to the specified artist_account_id. Content Content Creation POST /api/transcribe "},{"slug":"api-reference/content/lipsync","title":"Generate lipsync (release pending)","description":"Generate audio-driven video (release pending)","category":"Content","group":"Content Creation","source":"api-reference/content/lipsync.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content/lipsync","spec":"content.json"},"searchText":"Generate lipsync (release pending) Generate audio-driven video (release pending) Content Content Creation POST /api/content/lipsync "},{"slug":"api-reference/music/generate","title":"Generate Music","description":"Generate music","category":"Content","group":"Music","source":"api-reference/music/generate.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/music","spec":"content.json"},"searchText":"Generate Music Generate music Content Music POST /api/music "},{"slug":"api-reference/music/list","title":"List Music Generations","description":"List music generations","category":"Content","group":"Music","source":"api-reference/music/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/music","spec":"content.json"},"searchText":"List Music Generations List music generations Content Music GET /api/music "},{"slug":"api-reference/music/get","title":"Get Music Generation","description":"Get music generation","category":"Content","group":"Music","source":"api-reference/music/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/music/{generationId}","spec":"content.json"},"searchText":"Get Music Generation Get music generation Content Music GET /api/music/{generationId} "},{"slug":"api-reference/music/legacy","title":"Music API migration","description":"Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths.","category":"Content","group":"Music","source":"api-reference/music/legacy.mdx","body":"## Generate a song now\n\nUse [`POST /api/music`](/api-reference/music/generate) with a prompt and lyrics.\nIt returns `202` with a generation record; poll\n[`GET /api/music/{generationId}`](/api-reference/music/get) for completion and\nthe resulting audio URL. It does not return audio in the initial response.\nSee the current reference for accepted settings, account scope and credits.\n\n## Former music routes\n\nThe six POST paths below are retired from the callable specification because\nthey have no implemented handlers in the current API. They are not aliases for\n`POST /api/music`. Their specialized outcomes are not equivalent to ordinary\nsong generation and are not declared canceled by this correction.\n\n| Former path | Current choice and remaining limit |\n| --- | --- |\n| `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. |\n| `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. |\n| `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. |\n| `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. |\n| `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. |\n| `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. |\n\n## What remains undecided\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the\nspecialized capability decisions. The current music-generation implementation\nis tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and\n[API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every\nformer capability. An agent or local skill may help prepare inputs, but that\ndoes not establish a hosted route or compatibility with the former request.\n\nThis is a reference correction. No provider run or audio-quality check was\nperformed to make these availability statements.\n","headings":[{"title":"Generate a song now","id":"generate-a-song-now"},{"title":"Former music routes","id":"former-music-routes"},{"title":"What remains undecided","id":"what-remains-undecided"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"generate-a-song-now\",\n children: \"Generate a song now\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.a, {\n href: \"/api-reference/music/generate\",\n children: _jsx(_components.code, {\n children: \"POST /api/music\"\n })\n }), \" with a prompt and lyrics.\\nIt returns \", _jsx(_components.code, {\n children: \"202\"\n }), \" with a generation record; poll\\n\", _jsx(_components.a, {\n href: \"/api-reference/music/get\",\n children: _jsx(_components.code, {\n children: \"GET /api/music/{generationId}\"\n })\n }), \" for completion and\\nthe resulting audio URL. It does not return audio in the initial response.\\nSee the current reference for accepted settings, account scope and credits.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"former-music-routes\",\n children: \"Former music routes\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The six POST paths below are retired from the callable specification because\\nthey have no implemented handlers in the current API. They are not aliases for\\n\", _jsx(_components.code, {\n children: \"POST /api/music\"\n }), \". Their specialized outcomes are not equivalent to ordinary\\nsong generation and are not declared canceled by this correction.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Former path\"\n }), _jsx(_components.th, {\n children: \"Current choice and remaining limit\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/compose\"\n })\n }), _jsx(_components.td, {\n children: \"Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/compose/detailed\"\n })\n }), _jsx(_components.td, {\n children: \"Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/plan\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/stream\"\n })\n }), _jsx(_components.td, {\n children: \"Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/video-to-music\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"/api/music/stem-separation\"\n })\n }), _jsx(_components.td, {\n children: \"No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems.\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-remains-undecided\",\n children: \"What remains undecided\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" retains the\\nspecialized capability decisions. The current music-generation implementation\\nis tracked in \", _jsx(_components.a, {\n href: \"https://github.com/recoupable/app/issues/1992\",\n children: \"App #1992\"\n }), \" and\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/848\",\n children: \"API #848\"\n }), \"; it is not delivery of every\\nformer capability. An agent or local skill may help prepare inputs, but that\\ndoes not establish a hosted route or compatibility with the former request.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This is a reference correction. No provider run or audio-quality check was\\nperformed to make these availability statements.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Music API migration Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths. Content Music ## Generate a song now Use [`POST /api/music`](/api-reference/music/generate) with a prompt and lyrics. It returns `202` with a generation record; poll [`GET /api/music/{generationId}`](/api-reference/music/get) for completion and the resulting audio URL. It does not return audio in the initial response. See the current reference for accepted settings, account scope and credits. ## Former music routes The six POST paths below are retired from the callable specification because they have no implemented handlers in the current API. They are not aliases for `POST /api/music`. Their specialized outcomes are not equivalent to ordinary song generation and are not declared canceled by this correction. | Former path | Current choice and remaining limit | | --- | --- | | `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. | | `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. | | `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. | | `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. | | `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. | | `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. | ## What remains undecided [Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the specialized capability decisions. The current music-generation implementation is tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and [API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every former capability. An agent or local skill may help prepare inputs, but that does not establish a hosted route or compatibility with the former request. This is a reference correction. No provider run or audio-quality check was performed to make these availability statements. "},{"slug":"api-reference/posts/get","title":"Get Artist Posts","description":"Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections.","category":"Content","group":"Posts & Comments","source":"api-reference/posts/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/artists/{id}/posts","spec":"social.json"},"searchText":"Get Artist Posts Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections. Content Posts & Comments GET /api/artists/{id}/posts "},{"slug":"api-reference/comments/get","title":"Get Comments","description":"Read saved comments on an authorized creator’s linked posts","category":"Content","group":"Posts & Comments","source":"api-reference/comments/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/comments","spec":"social.json"},"searchText":"Get Comments Read saved comments on an authorized creator’s linked posts Content Posts & Comments GET /api/comments "},{"slug":"api-reference/social/scrape","title":"Social Scrape","description":"Trigger a scrape of one social profile. Use [Get Artist Socials](/api-reference/artists/socials) first to get the social `id`. The response contains scraper run metadata; poll it with the [Scraper Results API](/api-reference/apify/scraper).","category":"Social Media","group":"Social","source":"api-reference/social/scrape.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/socials/{id}/scrape","spec":"social.json"},"searchText":"Social Scrape Trigger a scrape of one social profile. Use [Get Artist Socials](/api-reference/artists/socials) first to get the social `id`. The response contains scraper run metadata; poll it with the [Scraper Results API](/api-reference/apify/scraper). Social Media Social POST /api/socials/{id}/scrape "},{"slug":"api-reference/artist/socials-scrape","title":"api-reference/artist/socials-scrape","description":"Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper).","category":"Social Media","group":"Social","source":"api-reference/artist/socials-scrape.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/artist/socials/scrape","spec":"releases.json"},"searchText":"api-reference/artist/socials-scrape Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper). Social Media Social POST /api/artist/socials/scrape "},{"slug":"api-reference/spotify/search","title":"Search","description":"Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/search.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/search","spec":"social.json"},"searchText":"Search Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API. Social Media Spotify GET /api/spotify/search "},{"slug":"api-reference/spotify/artist","title":"Get Artist","description":"Get Spotify catalog information for a single artist identified by their unique Spotify ID.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/","spec":"social.json"},"searchText":"Get Artist Get Spotify catalog information for a single artist identified by their unique Spotify ID. Social Media Spotify GET /api/spotify/artist/ "},{"slug":"api-reference/spotify/artist-albums","title":"Get Artist Albums","description":"Get Spotify catalog information about an artist's albums.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist-albums.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/albums","spec":"social.json"},"searchText":"Get Artist Albums Get Spotify catalog information about an artist's albums. Social Media Spotify GET /api/spotify/artist/albums "},{"slug":"api-reference/spotify/artist-top-tracks","title":"Get Artist Top Tracks","description":"Get an artist's top tracks by country.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/artist-top-tracks.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/artist/topTracks","spec":"social.json"},"searchText":"Get Artist Top Tracks Get an artist's top tracks by country. Social Media Spotify GET /api/spotify/artist/topTracks "},{"slug":"api-reference/spotify/album","title":"Get Album","description":"Get Spotify catalog information for a single album.","category":"Social Media","group":"Spotify","source":"api-reference/spotify/album.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/spotify/album","spec":"social.json"},"searchText":"Get Album Get Spotify catalog information for a single album. Social Media Spotify GET /api/spotify/album "},{"slug":"api-reference/apple/songs","title":"Songs by ISRC","description":"Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose.","category":"Social Media","group":"Apple Music","source":"api-reference/apple/songs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/apple/songs","spec":"social.json"},"searchText":"Songs by ISRC Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose. Social Media Apple Music GET /api/apple/songs "},{"slug":"api-reference/apify/scraper","title":"Scraper Results","description":"Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results.","category":"Social Media","group":"Apify","source":"api-reference/apify/scraper.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/apify/runs/{runId}","spec":"social.json"},"searchText":"Scraper Results Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results. Social Media Apify GET /api/apify/runs/{runId} "},{"slug":"api-reference/agents/signup","title":"Agent Signup","description":"Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key.","category":"Agents & Sandboxes","group":"Agent Onboarding","source":"api-reference/agents/signup.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/signup","spec":"accounts.json"},"searchText":"Agent Signup Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key. Agents & Sandboxes Agent Onboarding POST /api/agents/signup "},{"slug":"api-reference/agents/verify","title":"Verify Agent Email","description":"Verify an agent's email with the code sent during signup. Returns an API key on success.","category":"Agents & Sandboxes","group":"Agent Onboarding","source":"api-reference/agents/verify.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/verify","spec":"accounts.json"},"searchText":"Verify Agent Email Verify an agent's email with the code sent during signup. Returns an API key on success. Agents & Sandboxes Agent Onboarding POST /api/agents/verify "},{"slug":"agents","title":"Agents","description":"Verified email onboarding for a separate Recoup REST API key.","category":"Agents & Sandboxes","group":"Agents","source":"agents.mdx","body":"## Use your real account\n\nPrefer [MCP OAuth](/mcp-oauth) for supported AI hosts. REST integrations need a\nseparate API key; an OAuth connection does not export one into your shell.\n\nUse the email verification flow below with an address the user controls. Keep\nthe returned key out of messages and logs, and store it through a secret facility\nor an explicitly approved local environment file. Never use a disposable account\nto recover an existing user's data.\n\nThe source signup contract also supports immediate keys for new `agent+` addresses.\nThat creates a separate identity; it does not grant customer or organization access.\nIt is not the recommended onboarding path for customer work. Multiple API keys per\naccount are supported, without revoking existing keys.\n\n## Standard signup (email verification)\n\nIf you're building a human-facing integration and want the user to verify their real email, use an email address the user controls:\n\nStep 1 — request a verification code:\n\n```bash\ncurl -X POST \"https://api.recoupable.dev/api/agents/signup\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\"}'\n```\n\nStep 2 — submit the 6-digit code from the verification email:\n\n```bash\ncurl -X POST \"https://api.recoupable.dev/api/agents/verify\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"code\": \"123456\"}'\n```\n\nResponse:\n\n```json\n{\n \"account_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"api_key\": \"recoup_sk_abc123...\",\n \"message\": \"Verified\"\n}\n```\n\n## Using your API key\n\nPass the returned `api_key` in the `x-api-key` header on every authenticated request:\n\n```bash\ncurl -X GET \"https://api.recoupable.dev/api/tasks\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\nSee [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request.\n","headings":[{"title":"Use your real account","id":"use-your-real-account"},{"title":"Standard signup (email verification)","id":"standard-signup-email-verification"},{"title":"Using your API key","id":"using-your-api-key"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"use-your-real-account\",\n children: \"Use your real account\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Prefer \", _jsx(_components.a, {\n href: \"/mcp-oauth\",\n children: \"MCP OAuth\"\n }), \" for supported AI hosts. REST integrations need a\\nseparate API key; an OAuth connection does not export one into your shell.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the email verification flow below with an address the user controls. Keep\\nthe returned key out of messages and logs, and store it through a secret facility\\nor an explicitly approved local environment file. Never use a disposable account\\nto recover an existing user's data.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The source signup contract also supports immediate keys for new \", _jsx(_components.code, {\n children: \"agent+\"\n }), \" addresses.\\nThat creates a separate identity; it does not grant customer or organization access.\\nIt is not the recommended onboarding path for customer work. Multiple API keys per\\naccount are supported, without revoking existing keys.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"standard-signup-email-verification\",\n children: \"Standard signup (email verification)\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If you're building a human-facing integration and want the user to verify their real email, use an email address the user controls:\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Step 1 — request a verification code:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X POST \\\"https://api.recoupable.dev/api/agents/signup\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"email\\\": \\\"you@example.com\\\"}'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Step 2 — submit the 6-digit code from the verification email:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X POST \\\"https://api.recoupable.dev/api/agents/verify\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"email\\\": \\\"you@example.com\\\", \\\"code\\\": \\\"123456\\\"}'\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Response:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"account_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\\n \\\"api_key\\\": \\\"recoup_sk_abc123...\\\",\\n \\\"message\\\": \\\"Verified\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"using-your-api-key\",\n children: \"Using your API key\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass the returned \", _jsx(_components.code, {\n children: \"api_key\"\n }), \" in the \", _jsx(_components.code, {\n children: \"x-api-key\"\n }), \" header on every authenticated request:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl -X GET \\\"https://api.recoupable.dev/api/tasks\\\" \\\\\\n -H \\\"x-api-key: YOUR_API_KEY\\\"\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"Authentication\"\n }), \" for the full authentication model, including organization access and Bearer token support, and \", _jsx(_components.a, {\n href: \"/quickstart\",\n children: \"Quickstart\"\n }), \" for your first end-to-end request.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Agents Verified email onboarding for a separate Recoup REST API key. Agents & Sandboxes Agents ## Use your real account Prefer [MCP OAuth](/mcp-oauth) for supported AI hosts. REST integrations need a separate API key; an OAuth connection does not export one into your shell. Use the email verification flow below with an address the user controls. Keep the returned key out of messages and logs, and store it through a secret facility or an explicitly approved local environment file. Never use a disposable account to recover an existing user's data. The source signup contract also supports immediate keys for new `agent+` addresses. That creates a separate identity; it does not grant customer or organization access. It is not the recommended onboarding path for customer work. Multiple API keys per account are supported, without revoking existing keys. ## Standard signup (email verification) If you're building a human-facing integration and want the user to verify their real email, use an email address the user controls: Step 1 — request a verification code: Step 2 — submit the 6-digit code from the verification email: Response: ## Using your API key Pass the returned `api_key` in the `x-api-key` header on every authenticated request: See [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request. "},{"slug":"content-agent","title":"Content Agent","description":"Use hosted creative presets and current image, video and composition primitives.","category":"Agents & Sandboxes","group":"Agents","source":"content-agent.mdx","body":"## Release Packs\n\nFor a song-centered content pack, use [Release Packs](/release-packs): collect\nessential context inline, preserve one job, quote the complete scope and produce\nreviewed media. New releases, catalog rediscovery, anniversaries, reissues and\nremixes use the same brief-driven path. These pack operations do not require an\nexisting artist or repository; availability depends on deployed host tools.\n\n## Hosted workflows\n\n`POST /api/content/create` retains the hosted preset workflow. Supply the authorized\n`artist_account_id`, optional `template`, `images`, `songs`, `batch` (defaults to 1; range 1–30), `lipsync`, `upscale`\nand `caption_length`. Discover templates through `/api/content/templates` and its\ndetail route. The response contains `runIds`; poll `/api/tasks/runs?runId=...` until\nterminal. Report failures and inspect the final artifact before delivery.\n\nHosted lipsync is a supported preset intent. The coordinated API/worker repair\nrestores the selected song window to the fixed audio-to-video path; that repaired\njourney is release-pending until deployment and actual output verification.\n\n## Direct primitives\n\nFor images use `POST /api/content/image` with `prompt` and up to 10 unique\n`image_urls`. The house model is Muse Image, switching to its edit path when\nreferences are present. New clients must use `image_urls`; compatibility aliases\nare translated by the reconciliation release.\n\nFor video use `POST /api/content/video` with `prompt`, optional `image_url` and\n`end_image_url`, integer `duration` 5–15, and `resolution` `480P` or `768P`.\nThe house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model,\nreference-only, extend, `video_url` or `audio_url` request control. Unsupported\nsemantic inputs return 400 in the reconciliation release, before paid generation.\n\nThe dedicated `/api/content/lipsync` primitive restores the existing fixed LTX\nmodel for the worker; it is not assumed available on an older deployment.\nCaption, transcribe, analyze, upscale and edit have their own endpoint contracts.\nLocal ffmpeg composition can crop, trim, overlay or mux a song; it does not create\nmouth synchronization or prove a hosted generation succeeded.\n\n## Cost and evidence\n\nEach generation/inference stage can consume credits. `/api/content/estimate`\nreturns an advisory estimate, not a guaranteed price or complete final ledger.\nA later failed composition does not imply that completed upstream work was free.\nOn insufficient credits, surface `billingUrl` and stop. Consult [Credits](/credits).\n\nRecord image inspection, motion review and audio playback. The worker checks for\nan audio stream on lipsync output before composition; perceptual mouth alignment\nstill requires inspection. Automated checks do not replace human QA.\n\n## Slack integration\n\nThe separate [Slack webhook](/api-reference/content-agent/webhook) handles\nContent Agent mentions. Its request/event contract and the [completion callback](/api-reference/content-agent/callback) are distinct from direct primitives.\nWorkspace operators must configure the Slack application and service credentials;\ninstalling a creative skill does not install that integration.\n\n### Set up the Slack app\n\nCreate a Slack app, enable the `chat:write` and `app_mentions:read` bot scopes,\nand subscribe to `app_mention` events at\n`https://api.recoupable.dev/api/content-agent/slack`. Install it in the intended\nworkspace and invite it to the channel.\n\nConfigure `SLACK_CONTENT_BOT_TOKEN`, `SLACK_CONTENT_SIGNING_SECRET`,\n`CODING_AGENT_CALLBACK_SECRET` and `REDIS_URL` in the Recoup API service.\nThe existing Tasks worker uses the same `CODING_AGENT_CALLBACK_SECRET` for\ncompletion callbacks and its authorized Recoup credential and API base URL.\nKeep these values in service secret settings. The current callback secret name\nis `CODING_AGENT_CALLBACK_SECRET`; `CONTENT_AGENT_CALLBACK_SECRET` is obsolete.\n\nSlack sends the signed-request headers listed in the [webhook reference](/api-reference/content-agent/webhook).\nKeep `SLACK_CONTENT_SIGNING_SECRET` matched to that Slack app. Setup requests\nwith missing or invalid signatures, a timestamp outside the five-minute window,\nor an unavailable signing secret return `401` with plain-text `Unauthorized`.\nA verified setup request returns its JSON challenge. If setup fails, check the\napp secret and service clock against [Slack request verification](https://docs.slack.dev/authentication/verifying-requests-from-slack/).\nOrdinary event acknowledgements come from the Slack adapter; they acknowledge\nreceipt while generation completes separately.\n\nMention the installed bot with the authorized artist account UUID:\n\n```text\n@RecoupContentAgent ARTIST_ACCOUNT_UUID artist-caption-bedroom batch=1\n```\n\nThe template, `batch=N` (1–30) and `lipsync` flags are optional. Check the\nacknowledgment, then inspect the completed result or reported failure in the\nthread. Generated output still requires the inspection described above.\n","headings":[{"title":"Release Packs","id":"release-packs"},{"title":"Hosted workflows","id":"hosted-workflows"},{"title":"Direct primitives","id":"direct-primitives"},{"title":"Cost and evidence","id":"cost-and-evidence"},{"title":"Slack integration","id":"slack-integration"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n p: \"p\",\n pre: \"pre\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"release-packs\",\n children: \"Release Packs\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a song-centered content pack, use \", _jsx(_components.a, {\n href: \"/release-packs\",\n children: \"Release Packs\"\n }), \": collect\\nessential context inline, preserve one job, quote the complete scope and produce\\nreviewed media. New releases, catalog rediscovery, anniversaries, reissues and\\nremixes use the same brief-driven path. These pack operations do not require an\\nexisting artist or repository; availability depends on deployed host tools.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"hosted-workflows\",\n children: \"Hosted workflows\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"POST /api/content/create\"\n }), \" retains the hosted preset workflow. Supply the authorized\\n\", _jsx(_components.code, {\n children: \"artist_account_id\"\n }), \", optional \", _jsx(_components.code, {\n children: \"template\"\n }), \", \", _jsx(_components.code, {\n children: \"images\"\n }), \", \", _jsx(_components.code, {\n children: \"songs\"\n }), \", \", _jsx(_components.code, {\n children: \"batch\"\n }), \" (defaults to 1; range 1–30), \", _jsx(_components.code, {\n children: \"lipsync\"\n }), \", \", _jsx(_components.code, {\n children: \"upscale\"\n }), \"\\nand \", _jsx(_components.code, {\n children: \"caption_length\"\n }), \". Discover templates through \", _jsx(_components.code, {\n children: \"/api/content/templates\"\n }), \" and its\\ndetail route. The response contains \", _jsx(_components.code, {\n children: \"runIds\"\n }), \"; poll \", _jsx(_components.code, {\n children: \"/api/tasks/runs?runId=...\"\n }), \" until\\nterminal. Report failures and inspect the final artifact before delivery.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Hosted lipsync is a supported preset intent. The coordinated API/worker repair\\nrestores the selected song window to the fixed audio-to-video path; that repaired\\njourney is release-pending until deployment and actual output verification.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"direct-primitives\",\n children: \"Direct primitives\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For images use \", _jsx(_components.code, {\n children: \"POST /api/content/image\"\n }), \" with \", _jsx(_components.code, {\n children: \"prompt\"\n }), \" and up to 10 unique\\n\", _jsx(_components.code, {\n children: \"image_urls\"\n }), \". The house model is Muse Image, switching to its edit path when\\nreferences are present. New clients must use \", _jsx(_components.code, {\n children: \"image_urls\"\n }), \"; compatibility aliases\\nare translated by the reconciliation release.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For video use \", _jsx(_components.code, {\n children: \"POST /api/content/video\"\n }), \" with \", _jsx(_components.code, {\n children: \"prompt\"\n }), \", optional \", _jsx(_components.code, {\n children: \"image_url\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"end_image_url\"\n }), \", integer \", _jsx(_components.code, {\n children: \"duration\"\n }), \" 5–15, and \", _jsx(_components.code, {\n children: \"resolution\"\n }), \" \", _jsx(_components.code, {\n children: \"480P\"\n }), \" or \", _jsx(_components.code, {\n children: \"768P\"\n }), \".\\nThe house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model,\\nreference-only, extend, \", _jsx(_components.code, {\n children: \"video_url\"\n }), \" or \", _jsx(_components.code, {\n children: \"audio_url\"\n }), \" request control. Unsupported\\nsemantic inputs return 400 in the reconciliation release, before paid generation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The dedicated \", _jsx(_components.code, {\n children: \"/api/content/lipsync\"\n }), \" primitive restores the existing fixed LTX\\nmodel for the worker; it is not assumed available on an older deployment.\\nCaption, transcribe, analyze, upscale and edit have their own endpoint contracts.\\nLocal ffmpeg composition can crop, trim, overlay or mux a song; it does not create\\nmouth synchronization or prove a hosted generation succeeded.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"cost-and-evidence\",\n children: \"Cost and evidence\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each generation/inference stage can consume credits. \", _jsx(_components.code, {\n children: \"/api/content/estimate\"\n }), \"\\nreturns an advisory estimate, not a guaranteed price or complete final ledger.\\nA later failed composition does not imply that completed upstream work was free.\\nOn insufficient credits, surface \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \" and stop. Consult \", _jsx(_components.a, {\n href: \"/credits\",\n children: \"Credits\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Record image inspection, motion review and audio playback. The worker checks for\\nan audio stream on lipsync output before composition; perceptual mouth alignment\\nstill requires inspection. Automated checks do not replace human QA.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"slack-integration\",\n children: \"Slack integration\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The separate \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/webhook\",\n children: \"Slack webhook\"\n }), \" handles\\nContent Agent mentions. Its request/event contract and the \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/callback\",\n children: \"completion callback\"\n }), \" are distinct from direct primitives.\\nWorkspace operators must configure the Slack application and service credentials;\\ninstalling a creative skill does not install that integration.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"set-up-the-slack-app\",\n children: \"Set up the Slack app\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Create a Slack app, enable the \", _jsx(_components.code, {\n children: \"chat:write\"\n }), \" and \", _jsx(_components.code, {\n children: \"app_mentions:read\"\n }), \" bot scopes,\\nand subscribe to \", _jsx(_components.code, {\n children: \"app_mention\"\n }), \" events at\\n\", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/api/content-agent/slack\"\n }), \". Install it in the intended\\nworkspace and invite it to the channel.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Configure \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_BOT_TOKEN\"\n }), \", \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_SIGNING_SECRET\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \" and \", _jsx(_components.code, {\n children: \"REDIS_URL\"\n }), \" in the Recoup API service.\\nThe existing Tasks worker uses the same \", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \" for\\ncompletion callbacks and its authorized Recoup credential and API base URL.\\nKeep these values in service secret settings. The current callback secret name\\nis \", _jsx(_components.code, {\n children: \"CODING_AGENT_CALLBACK_SECRET\"\n }), \"; \", _jsx(_components.code, {\n children: \"CONTENT_AGENT_CALLBACK_SECRET\"\n }), \" is obsolete.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Slack sends the signed-request headers listed in the \", _jsx(_components.a, {\n href: \"/api-reference/content-agent/webhook\",\n children: \"webhook reference\"\n }), \".\\nKeep \", _jsx(_components.code, {\n children: \"SLACK_CONTENT_SIGNING_SECRET\"\n }), \" matched to that Slack app. Setup requests\\nwith missing or invalid signatures, a timestamp outside the five-minute window,\\nor an unavailable signing secret return \", _jsx(_components.code, {\n children: \"401\"\n }), \" with plain-text \", _jsx(_components.code, {\n children: \"Unauthorized\"\n }), \".\\nA verified setup request returns its JSON challenge. If setup fails, check the\\napp secret and service clock against \", _jsx(_components.a, {\n href: \"https://docs.slack.dev/authentication/verifying-requests-from-slack/\",\n children: \"Slack request verification\"\n }), \".\\nOrdinary event acknowledgements come from the Slack adapter; they acknowledge\\nreceipt while generation completes separately.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Mention the installed bot with the authorized artist account UUID:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-text\",\n children: \"@RecoupContentAgent ARTIST_ACCOUNT_UUID artist-caption-bedroom batch=1\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The template, \", _jsx(_components.code, {\n children: \"batch=N\"\n }), \" (1–30) and \", _jsx(_components.code, {\n children: \"lipsync\"\n }), \" flags are optional. Check the\\nacknowledgment, then inspect the completed result or reported failure in the\\nthread. Generated output still requires the inspection described above.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Content Agent Use hosted creative presets and current image, video and composition primitives. Agents & Sandboxes Agents ## Release Packs For a song-centered content pack, use [Release Packs](/release-packs): collect essential context inline, preserve one job, quote the complete scope and produce reviewed media. New releases, catalog rediscovery, anniversaries, reissues and remixes use the same brief-driven path. These pack operations do not require an existing artist or repository; availability depends on deployed host tools. ## Hosted workflows `POST /api/content/create` retains the hosted preset workflow. Supply the authorized `artist_account_id`, optional `template`, `images`, `songs`, `batch` (defaults to 1; range 1–30), `lipsync`, `upscale` and `caption_length`. Discover templates through `/api/content/templates` and its detail route. The response contains `runIds`; poll `/api/tasks/runs?runId=...` until terminal. Report failures and inspect the final artifact before delivery. Hosted lipsync is a supported preset intent. The coordinated API/worker repair restores the selected song window to the fixed audio-to-video path; that repaired journey is release-pending until deployment and actual output verification. ## Direct primitives For images use `POST /api/content/image` with `prompt` and up to 10 unique `image_urls`. The house model is Muse Image, switching to its edit path when references are present. New clients must use `image_urls`; compatibility aliases are translated by the reconciliation release. For video use `POST /api/content/video` with `prompt`, optional `image_url` and `end_image_url`, integer `duration` 5–15, and `resolution` `480P` or `768P`. The house model is MiniMax H3 Max. It has no six-mode selector, arbitrary model, reference-only, extend, `video_url` or `audio_url` request control. Unsupported semantic inputs return 400 in the reconciliation release, before paid generation. The dedicated `/api/content/lipsync` primitive restores the existing fixed LTX model for the worker; it is not assumed available on an older deployment. Caption, transcribe, analyze, upscale and edit have their own endpoint contracts. Local ffmpeg composition can crop, trim, overlay or mux a song; it does not create mouth synchronization or prove a hosted generation succeeded. ## Cost and evidence Each generation/inference stage can consume credits. `/api/content/estimate` returns an advisory estimate, not a guaranteed price or complete final ledger. A later failed composition does not imply that completed upstream work was free. On insufficient credits, surface `billingUrl` and stop. Consult [Credits](/credits). Record image inspection, motion review and audio playback. The worker checks for an audio stream on lipsync output before composition; perceptual mouth alignment still requires inspection. Automated checks do not replace human QA. ## Slack integration The separate [Slack webhook](/api-reference/content-agent/webhook) handles Content Agent mentions. Its request/event contract and the [completion callback](/api-reference/content-agent/callback) are distinct from direct primitives. Workspace operators must configure the Slack application and service credentials; installing a creative skill does not install that integration. ### Set up the Slack app Create a Slack app, enable the `chat:write` and `app_mentions:read` bot scopes, and subscribe to `app_mention` events at `https://api.recoupable.dev/api/content-agent/slack`. Install it in the intended workspace and invite it to the channel. Configure `SLACK_CONTENT_BOT_TOKEN`, `SLACK_CONTENT_SIGNING_SECRET`, `CODING_AGENT_CALLBACK_SECRET` and `REDIS_URL` in the Recoup API service. The existing Tasks worker uses the same `CODING_AGENT_CALLBACK_SECRET` for completion callbacks and its authorized Recoup credential and API base URL. Keep these values in service secret settings. The current callback secret name is `CODING_AGENT_CALLBACK_SECRET`; `CONTENT_AGENT_CALLBACK_SECRET` is obsolete. Slack sends the signed-request headers listed in the [webhook reference](/api-reference/content-agent/webhook). Keep `SLACK_CONTENT_SIGNING_SECRET` matched to that Slack app. Setup requests with missing or invalid signatures, a timestamp outside the five-minute window, or an unavailable signing secret return `401` with plain-text `Unauthorized`. A verified setup request returns its JSON challenge. If setup fails, check the app secret and service clock against [Slack request verification](https://docs.slack.dev/authentication/verifying-requests-from-slack/). Ordinary event acknowledgements come from the Slack adapter; they acknowledge receipt while generation completes separately. Mention the installed bot with the authorized artist account UUID: The template, `batch=N` (1–30) and `lipsync` flags are optional. Check the acknowledgment, then inspect the completed result or reported failure in the thread. Generated output still requires the inspection described above. "},{"slug":"release-packs","title":"Release Packs","description":"Turn a song and a campaign occasion into a coherent set of reviewed music assets.","category":"Agents & Sandboxes","group":"Agents","source":"release-packs.mdx","body":"\nThis contract accompanies the Release Packs first-use rollout. Availability depends\non the deployed API and the tools exposed by your connected host. A plugin download\nor successful sign-in alone does not establish that generation is available.\n\n\n## Start with the music\n\nAsk your agent: **“Create a release pack for this song.”** Supply the audio or an\naccessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a\nreissue, a remix, or a catalog rediscovery campaign.\n\nThe agent reuses information you have already supplied and any selected, accessible\nRecoup context. It asks only for essential gaps: the correct artist and recording,\nthe occasion, and artwork or creative direction. You can ask it to propose a\ndirection from the music instead. It must distinguish that proposal from your\nestablished branding.\n\nYou do not need an existing artist profile, Spotify history, connected social\naccounts, a catalog import, or a GitHub workspace to prepare a pack. An empty\nRecoup roster is a valid new account. Sign in through your host's Recoup connection\nwhen the agent needs authenticated execution; it should resume the same request.\n\n**“Plan a release” is a different request.** It produces a creative brief and\nrollout plan. Ask for a release pack to produce media, or ask for both so the agent\ncan carry the same brief into production.\n\nWhen ChatGPT supplies a selected attachment to the upload tool, the tool accepts\nits host file reference directly. It imports the selected download URL into\nprivate Recoup storage and validates the actual media bytes. Other hosts can use\nthe supported source URL, inline or signed-upload modes; a filename alone is not\nan accessible recording.\n\nFor direct API uploads, small inline files are limited to approximately 3 MB\n(4,000,000 base64 characters). For normal song files, request a private signed\nupload, transfer the file and finalize it, or import an accessible HTTPS source\nup to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable\nonly after the agent can access its actual bytes. Audio formats include MP3,\nWAV, FLAC and M4A. Source images can be PNG, JPEG or WebP.\n\n## What the brief contains\n\n| Input | How it is used |\n| --- | --- |\n| Artist, song and exact version | Keep the recording, remix and artist identity consistent |\n| Real audio and selected hook | Put the correct music into the finished clips |\n| Occasion | Choose relevant concepts and copy rather than defaulting to “out now” |\n| Creative direction or references | Keep a coherent visual family and voice |\n| Primary action and destination | Write relevant captions without inventing links |\n| Audience, platforms and constraints | Choose useful formats and respect supplied boundaries |\n\nFor anniversaries, the original release date and campaign date are separate. If\nthe original date is unknown, the agent must obtain it before making dated\nanniversary claims. A catalog request needs a bounded selection of recordings;\nit must not silently generate a pack for every track.\n\nResearch enriches the brief. Missing research or audience metrics should not\nforce unrelated onboarding or fabricated statistics. Existing artwork and\nsupplied preferences can be enough to propose strong creative work. An artist's\nface is optional; artwork-led and typographic work are valid directions.\n\n## Scope and budget before generation\n\n### Save a direction and choose how involved to be\n\nConnections exposing `brief.creative_context` can save an established visual world,\na rough idea or an exploratory direction in the same pack. The field is optional;\nolder connections keep their existing brief behavior. It holds attributed references,\nup to three direction candidates and the selected candidate.\n\n**Run with it** uses `working_mode: \"autonomous\"`: the agent records its direction\nselection and continues within the approved budget. **Show me directions first**\nuses `working_mode: \"guided\"`: final quoting and generation wait for a selection\nrecorded from the customer's feedback. An agent's own choice does not count as\ncustomer selection in guided mode.\n\nSave candidates under `directions`, then record `selection.direction_id`,\n`selection.selected_by` (`customer` or `agent`) and a short `decision_note`.\nDirection and reference IDs must be unique within this brief; selections cannot\npoint to another pack's candidate. Updating these fields follows the same saved\njob and expected-revision rules and invalidates its earlier quote.\n\nA reference manifest item declares its source, media type and `usage`:\n`reference_only` is inspiration, while `production` explicitly makes an image\neligible as a selected generation input. Only production images referenced by\nthe chosen direction enter the renderer. Together with explicit legacy\n`reference_image_urls`, at most five distinct production images are supported.\nThe original source manifest stays unchanged when production inputs are resolved.\n\nThis first slice accepts supplied direction boards through an optional `board_url`.\nIt does not add automatic mood-board generation, public-profile harvesting or new\nasset types. Discover those capabilities before promising them. An optional\ncustomer checkpoint does not authorize additional spending or publication.\n\nPreparation and generation are separate operations. Before paid production, the\nagent shows the proposed direction, deliverables, cost scope and maximum budget.\nThe quote binds the current brief and deliverables. Changing the song or scope\nrequires a new quote; an earlier approval cannot silently authorize different work.\n\nThe default scope is 15 creative pieces: eight video clips, four quote cards, one\nartwork, one carousel and one visualizer, with captions. A carousel is one piece;\nits slides and alternate aspect ratios are identified as components or variants.\nYou can request a smaller scope. The quote must describe the actual selected work,\nincluding chargeable stages and any retry allowance. Current quotes charge for\nimage and motion generation; captioning, audio analysis, composition and inspection\nare included without an added customer fee. The approved amount is held before\nproduction; unused stages are refunded. A new paid retry needs its own quote.\n\nThe older `GET /api/content/estimate` is an advisory per-video estimate. It is not\na complete Release Packs quote. On insufficient credits the agent surfaces the\nreturned `billingUrl`; it must not buy credits, switch accounts or retry paid\ngeneration automatically.\n\n## One job, with visible progress\n\nThe pack retains its brief, revision, quote, individual asset states and completed\nwork. Signing in, waiting for a render, or recovering from a failed stage should\nnot make you repeat the request or regenerate the whole pack.\n\nThe first representative asset is produced and inspected early. The agent then\ncontinues the agreed batch within your budget, unless you requested a preview\ncheckpoint. Progress distinguishes requested, generated, inspected and delivered\nassets. A partly generated pack is reported as partial.\n\n## Review and delivery\n\nA finished music-bearing asset must contain the selected recording and the correct\naudio window. Inspection covers sound, timing, duration, framing, readable text,\nvisual consistency and the campaign brief. A render request, a prompt or a concept\nis not a finished asset. Static image inspection and video inspection are separate.\n\nDelivery includes previews, usable files, captions, a manifest and any unresolved\ngaps. The agent retains successful work when a stage fails and retries only within\nthe approved scope and budget. Release Packs stops at the assets: posting and\nscheduling need a separate request.\n\nAfter delivery, you can save confirmed artist preferences for next time. A\none-off creative proposal must not overwrite established branding or become a\npermanent public knowledge-base entry automatically.\n\n## API and connected tools\n\nConnected operations are `prepare_release_pack`, `get_release_pack`,\n`estimate_release_pack`, `generate_release_pack`, `retry_release_pack`,\n`upload_release_pack_asset` and `export_release_pack`. Discover their actual schemas\nin the connected host; older connections may need a refresh.\n\nThe shared API contract separates preparation, reading, quoting, generation,\nretry and selected-asset upload. Connected tools use the same account and job\nrules. Credentials remain with the host; an agent must not extract OAuth tokens\ninto REST requests or ask for an API key to compensate for a missing MCP tool.\n\nIf a required operation is unavailable, the agent should name that operation,\nretain the brief and explain the next step. It must not claim the entire account\nis disconnected or present a plan as completed media.\n","headings":[{"title":"Start with the music","id":"start-with-the-music"},{"title":"What the brief contains","id":"what-the-brief-contains"},{"title":"Scope and budget before generation","id":"scope-and-budget-before-generation"},{"title":"One job, with visible progress","id":"one-job-with-visible-progress"},{"title":"Review and delivery","id":"review-and-delivery"},{"title":"API and connected tools","id":"api-and-connected-tools"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ...props.components\n }, {Info} = _components;\n if (!Info) _missingMdxReference(\"Info\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Info, {\n children: _jsx(_components.p, {\n children: \"This contract accompanies the Release Packs first-use rollout. Availability depends\\non the deployed API and the tools exposed by your connected host. A plugin download\\nor successful sign-in alone does not establish that generation is available.\"\n })\n }), \"\\n\", _jsx(_components.h2, {\n id: \"start-with-the-music\",\n children: \"Start with the music\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Ask your agent: \", _jsx(_components.strong, {\n children: \"“Create a release pack for this song.”\"\n }), \" Supply the audio or an\\naccessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a\\nreissue, a remix, or a catalog rediscovery campaign.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The agent reuses information you have already supplied and any selected, accessible\\nRecoup context. It asks only for essential gaps: the correct artist and recording,\\nthe occasion, and artwork or creative direction. You can ask it to propose a\\ndirection from the music instead. It must distinguish that proposal from your\\nestablished branding.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"You do not need an existing artist profile, Spotify history, connected social\\naccounts, a catalog import, or a GitHub workspace to prepare a pack. An empty\\nRecoup roster is a valid new account. Sign in through your host's Recoup connection\\nwhen the agent needs authenticated execution; it should resume the same request.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"“Plan a release” is a different request.\"\n }), \" It produces a creative brief and\\nrollout plan. Ask for a release pack to produce media, or ask for both so the agent\\ncan carry the same brief into production.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"When ChatGPT supplies a selected attachment to the upload tool, the tool accepts\\nits host file reference directly. It imports the selected download URL into\\nprivate Recoup storage and validates the actual media bytes. Other hosts can use\\nthe supported source URL, inline or signed-upload modes; a filename alone is not\\nan accessible recording.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"For direct API uploads, small inline files are limited to approximately 3 MB\\n(4,000,000 base64 characters). For normal song files, request a private signed\\nupload, transfer the file and finalize it, or import an accessible HTTPS source\\nup to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable\\nonly after the agent can access its actual bytes. Audio formats include MP3,\\nWAV, FLAC and M4A. Source images can be PNG, JPEG or WebP.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-the-brief-contains\",\n children: \"What the brief contains\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Input\"\n }), _jsx(_components.th, {\n children: \"How it is used\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Artist, song and exact version\"\n }), _jsx(_components.td, {\n children: \"Keep the recording, remix and artist identity consistent\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Real audio and selected hook\"\n }), _jsx(_components.td, {\n children: \"Put the correct music into the finished clips\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Occasion\"\n }), _jsx(_components.td, {\n children: \"Choose relevant concepts and copy rather than defaulting to “out now”\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Creative direction or references\"\n }), _jsx(_components.td, {\n children: \"Keep a coherent visual family and voice\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Primary action and destination\"\n }), _jsx(_components.td, {\n children: \"Write relevant captions without inventing links\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Audience, platforms and constraints\"\n }), _jsx(_components.td, {\n children: \"Choose useful formats and respect supplied boundaries\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For anniversaries, the original release date and campaign date are separate. If\\nthe original date is unknown, the agent must obtain it before making dated\\nanniversary claims. A catalog request needs a bounded selection of recordings;\\nit must not silently generate a pack for every track.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Research enriches the brief. Missing research or audience metrics should not\\nforce unrelated onboarding or fabricated statistics. Existing artwork and\\nsupplied preferences can be enough to propose strong creative work. An artist's\\nface is optional; artwork-led and typographic work are valid directions.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"scope-and-budget-before-generation\",\n children: \"Scope and budget before generation\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"save-a-direction-and-choose-how-involved-to-be\",\n children: \"Save a direction and choose how involved to be\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connections exposing \", _jsx(_components.code, {\n children: \"brief.creative_context\"\n }), \" can save an established visual world,\\na rough idea or an exploratory direction in the same pack. The field is optional;\\nolder connections keep their existing brief behavior. It holds attributed references,\\nup to three direction candidates and the selected candidate.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Run with it\"\n }), \" uses \", _jsx(_components.code, {\n children: \"working_mode: \\\"autonomous\\\"\"\n }), \": the agent records its direction\\nselection and continues within the approved budget. \", _jsx(_components.strong, {\n children: \"Show me directions first\"\n }), \"\\nuses \", _jsx(_components.code, {\n children: \"working_mode: \\\"guided\\\"\"\n }), \": final quoting and generation wait for a selection\\nrecorded from the customer's feedback. An agent's own choice does not count as\\ncustomer selection in guided mode.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save candidates under \", _jsx(_components.code, {\n children: \"directions\"\n }), \", then record \", _jsx(_components.code, {\n children: \"selection.direction_id\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"selection.selected_by\"\n }), \" (\", _jsx(_components.code, {\n children: \"customer\"\n }), \" or \", _jsx(_components.code, {\n children: \"agent\"\n }), \") and a short \", _jsx(_components.code, {\n children: \"decision_note\"\n }), \".\\nDirection and reference IDs must be unique within this brief; selections cannot\\npoint to another pack's candidate. Updating these fields follows the same saved\\njob and expected-revision rules and invalidates its earlier quote.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A reference manifest item declares its source, media type and \", _jsx(_components.code, {\n children: \"usage\"\n }), \":\\n\", _jsx(_components.code, {\n children: \"reference_only\"\n }), \" is inspiration, while \", _jsx(_components.code, {\n children: \"production\"\n }), \" explicitly makes an image\\neligible as a selected generation input. Only production images referenced by\\nthe chosen direction enter the renderer. Together with explicit legacy\\n\", _jsx(_components.code, {\n children: \"reference_image_urls\"\n }), \", at most five distinct production images are supported.\\nThe original source manifest stays unchanged when production inputs are resolved.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This first slice accepts supplied direction boards through an optional \", _jsx(_components.code, {\n children: \"board_url\"\n }), \".\\nIt does not add automatic mood-board generation, public-profile harvesting or new\\nasset types. Discover those capabilities before promising them. An optional\\ncustomer checkpoint does not authorize additional spending or publication.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Preparation and generation are separate operations. Before paid production, the\\nagent shows the proposed direction, deliverables, cost scope and maximum budget.\\nThe quote binds the current brief and deliverables. Changing the song or scope\\nrequires a new quote; an earlier approval cannot silently authorize different work.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The default scope is 15 creative pieces: eight video clips, four quote cards, one\\nartwork, one carousel and one visualizer, with captions. A carousel is one piece;\\nits slides and alternate aspect ratios are identified as components or variants.\\nYou can request a smaller scope. The quote must describe the actual selected work,\\nincluding chargeable stages and any retry allowance. Current quotes charge for\\nimage and motion generation; captioning, audio analysis, composition and inspection\\nare included without an added customer fee. The approved amount is held before\\nproduction; unused stages are refunded. A new paid retry needs its own quote.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The older \", _jsx(_components.code, {\n children: \"GET /api/content/estimate\"\n }), \" is an advisory per-video estimate. It is not\\na complete Release Packs quote. On insufficient credits the agent surfaces the\\nreturned \", _jsx(_components.code, {\n children: \"billingUrl\"\n }), \"; it must not buy credits, switch accounts or retry paid\\ngeneration automatically.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"one-job-with-visible-progress\",\n children: \"One job, with visible progress\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The pack retains its brief, revision, quote, individual asset states and completed\\nwork. Signing in, waiting for a render, or recovering from a failed stage should\\nnot make you repeat the request or regenerate the whole pack.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The first representative asset is produced and inspected early. The agent then\\ncontinues the agreed batch within your budget, unless you requested a preview\\ncheckpoint. Progress distinguishes requested, generated, inspected and delivered\\nassets. A partly generated pack is reported as partial.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"review-and-delivery\",\n children: \"Review and delivery\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"A finished music-bearing asset must contain the selected recording and the correct\\naudio window. Inspection covers sound, timing, duration, framing, readable text,\\nvisual consistency and the campaign brief. A render request, a prompt or a concept\\nis not a finished asset. Static image inspection and video inspection are separate.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Delivery includes previews, usable files, captions, a manifest and any unresolved\\ngaps. The agent retains successful work when a stage fails and retries only within\\nthe approved scope and budget. Release Packs stops at the assets: posting and\\nscheduling need a separate request.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"After delivery, you can save confirmed artist preferences for next time. A\\none-off creative proposal must not overwrite established branding or become a\\npermanent public knowledge-base entry automatically.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"api-and-connected-tools\",\n children: \"API and connected tools\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connected operations are \", _jsx(_components.code, {\n children: \"prepare_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"get_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"estimate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"generate_release_pack\"\n }), \", \", _jsx(_components.code, {\n children: \"retry_release_pack\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"upload_release_pack_asset\"\n }), \" and \", _jsx(_components.code, {\n children: \"export_release_pack\"\n }), \". Discover their actual schemas\\nin the connected host; older connections may need a refresh.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"The shared API contract separates preparation, reading, quoting, generation,\\nretry and selected-asset upload. Connected tools use the same account and job\\nrules. Credentials remain with the host; an agent must not extract OAuth tokens\\ninto REST requests or ask for an API key to compensate for a missing MCP tool.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If a required operation is unavailable, the agent should name that operation,\\nretain the brief and explain the next step. It must not claim the entire account\\nis disconnected or present a plan as completed media.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Release Packs Turn a song and a campaign occasion into a coherent set of reviewed music assets. Agents & Sandboxes Agents This contract accompanies the Release Packs first-use rollout. Availability depends on the deployed API and the tools exposed by your connected host. A plugin download or successful sign-in alone does not establish that generation is available. ## Start with the music Ask your agent: **“Create a release pack for this song.”** Supply the audio or an accessible audio link. A listening page is not an audio file. Tell it whether this is a new release, an anniversary, a reissue, a remix, or a catalog rediscovery campaign. The agent reuses information you have already supplied and any selected, accessible Recoup context. It asks only for essential gaps: the correct artist and recording, the occasion, and artwork or creative direction. You can ask it to propose a direction from the music instead. It must distinguish that proposal from your established branding. You do not need an existing artist profile, Spotify history, connected social accounts, a catalog import, or a GitHub workspace to prepare a pack. An empty Recoup roster is a valid new account. Sign in through your host's Recoup connection when the agent needs authenticated execution; it should resume the same request. **“Plan a release” is a different request.** It produces a creative brief and rollout plan. Ask for a release pack to produce media, or ask for both so the agent can carry the same brief into production. When ChatGPT supplies a selected attachment to the upload tool, the tool accepts its host file reference directly. It imports the selected download URL into private Recoup storage and validates the actual media bytes. Other hosts can use the supported source URL, inline or signed-upload modes; a filename alone is not an accessible recording. For direct API uploads, small inline files are limited to approximately 3 MB (4,000,000 base64 characters). For normal song files, request a private signed upload, transfer the file and finalize it, or import an accessible HTTPS source up to 50 MiB for audio or 10 MiB for a reference image. Supported transfers depend on your host; an attachment is usable only after the agent can access its actual bytes. Audio formats include MP3, WAV, FLAC and M4A. Source images can be PNG, JPEG or WebP. ## What the brief contains | Input | How it is used | | --- | --- | | Artist, song and exact version | Keep the recording, remix and artist identity consistent | | Real audio and selected hook | Put the correct music into the finished clips | | Occasion | Choose relevant concepts and copy rather than defaulting to “out now” | | Creative direction or references | Keep a coherent visual family and voice | | Primary action and destination | Write relevant captions without inventing links | | Audience, platforms and constraints | Choose useful formats and respect supplied boundaries | For anniversaries, the original release date and campaign date are separate. If the original date is unknown, the agent must obtain it before making dated anniversary claims. A catalog request needs a bounded selection of recordings; it must not silently generate a pack for every track. Research enriches the brief. Missing research or audience metrics should not force unrelated onboarding or fabricated statistics. Existing artwork and supplied preferences can be enough to propose strong creative work. An artist's face is optional; artwork-led and typographic work are valid directions. ## Scope and budget before generation ### Save a direction and choose how involved to be Connections exposing `brief.creative_context` can save an established visual world, a rough idea or an exploratory direction in the same pack. The field is optional; older connections keep their existing brief behavior. It holds attributed references, up to three direction candidates and the selected candidate. **Run with it** uses `working_mode: \"autonomous\"`: the agent records its direction selection and continues within the approved budget. **Show me directions first** uses `working_mode: \"guided\"`: final quoting and generation wait for a selection recorded from the customer's feedback. An agent's own choice does not count as customer selection in guided mode. Save candidates under `directions`, then record `selection.direction_id`, `selection.selected_by` (`customer` or `agent`) and a short `decision_note`. Direction and reference IDs must be unique within this brief; selections cannot point to another pack's candidate. Updating these fields follows the same saved job and expected-revision rules and invalidates its earlier quote. A reference manifest item declares its source, media type and `usage`: `reference_only` is inspiration, while `production` explicitly makes an image eligible as a selected generation input. Only production images referenced by the chosen direction enter the renderer. Together with explicit legacy `reference_image_urls`, at most five distinct production images are supported. The original source manifest stays unchanged when production inputs are resolved. This first slice accepts supplied direction boards through an optional `board_url`. It does not add automatic mood-board generation, public-profile harvesting or new asset types. Discover those capabilities before promising them. An optional customer checkpoint does not authorize additional spending or publication. Preparation and generation are separate operations. Before paid production, the agent shows the proposed direction, deliverables, cost scope and maximum budget. The quote binds the current brief and deliverables. Changing the song or scope requires a new quote; an earlier approval cannot silently authorize different work. The default scope is 15 creative pieces: eight video clips, four quote cards, one artwork, one carousel and one visualizer, with captions. A carousel is one piece; its slides and alternate aspect ratios are identified as components or variants. You can request a smaller scope. The quote must describe the actual selected work, including chargeable stages and any retry allowance. Current quotes charge for image and motion generation; captioning, audio analysis, composition and inspection are included without an added customer fee. The approved amount is held before production; unused stages are refunded. A new paid retry needs its own quote. The older `GET /api/content/estimate` is an advisory per-video estimate. It is not a complete Release Packs quote. On insufficient credits the agent surfaces the returned `billingUrl`; it must not buy credits, switch accounts or retry paid generation automatically. ## One job, with visible progress The pack retains its brief, revision, quote, individual asset states and completed work. Signing in, waiting for a render, or recovering from a failed stage should not make you repeat the request or regenerate the whole pack. The first representative asset is produced and inspected early. The agent then continues the agreed batch within your budget, unless you requested a preview checkpoint. Progress distinguishes requested, generated, inspected and delivered assets. A partly generated pack is reported as partial. ## Review and delivery A finished music-bearing asset must contain the selected recording and the correct audio window. Inspection covers sound, timing, duration, framing, readable text, visual consistency and the campaign brief. A render request, a prompt or a concept is not a finished asset. Static image inspection and video inspection are separate. Delivery includes previews, usable files, captions, a manifest and any unresolved gaps. The agent retains successful work when a stage fails and retries only within the approved scope and budget. Release Packs stops at the assets: posting and scheduling need a separate request. After delivery, you can save confirmed artist preferences for next time. A one-off creative proposal must not overwrite established branding or become a permanent public knowledge-base entry automatically. ## API and connected tools Connected operations are `prepare_release_pack`, `get_release_pack`, `estimate_release_pack`, `generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and `export_release_pack`. Discover their actual schemas in the connected host; older connections may need a refresh. The shared API contract separates preparation, reading, quoting, generation, retry and selected-asset upload. Connected tools use the same account and job rules. Credentials remain with the host; an agent must not extract OAuth tokens into REST requests or ask for an API key to compensate for a missing MCP tool. If a required operation is unavailable, the agent should name that operation, retain the brief and explain the next step. It must not claim the entire account is disconnected or present a plan as completed media. "},{"slug":"api-reference/templates/list","title":"List Templates","description":"List templates","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/agents/templates","spec":"templates.json"},"searchText":"List Templates List templates Agents & Sandboxes Templates GET /api/agents/templates "},{"slug":"api-reference/templates/create","title":"Create Template","description":"Create a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/agents/templates","spec":"templates.json"},"searchText":"Create Template Create a template Agents & Sandboxes Templates POST /api/agents/templates "},{"slug":"api-reference/templates/update","title":"Update Template","description":"Update a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/agents/templates/{id}","spec":"templates.json"},"searchText":"Update Template Update a template Agents & Sandboxes Templates PATCH /api/agents/templates/{id} "},{"slug":"api-reference/templates/delete","title":"Delete Template","description":"Delete a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/agents/templates/{id}","spec":"templates.json"},"searchText":"Delete Template Delete a template Agents & Sandboxes Templates DELETE /api/agents/templates/{id} "},{"slug":"api-reference/templates/favorite","title":"Favorite Template","description":"Toggle favorite on a template","category":"Agents & Sandboxes","group":"Templates","source":"api-reference/templates/favorite.mdx","body":"","headings":[],"api":{"method":"PUT","path":"/api/agents/templates/{id}/favorite","spec":"templates.json"},"searchText":"Favorite Template Toggle favorite on a template Agents & Sandboxes Templates PUT /api/agents/templates/{id}/favorite "},{"slug":"api-reference/tasks/get","title":"Get Tasks","description":"Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/tasks","spec":"releases.json"},"searchText":"Get Tasks Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id. Agents & Sandboxes Tasks GET /api/tasks "},{"slug":"api-reference/tasks/create","title":"Create Task","description":"Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array).","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/tasks","spec":"releases.json"},"searchText":"Create Task Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array). Agents & Sandboxes Tasks POST /api/tasks "},{"slug":"api-reference/tasks/update","title":"Update Task","description":"Update scheduled task","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/tasks","spec":"releases.json"},"searchText":"Update Task Update scheduled task Agents & Sandboxes Tasks PATCH /api/tasks "},{"slug":"api-reference/tasks/delete","title":"Delete Task","description":"Delete scheduled task","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/tasks","spec":"releases.json"},"searchText":"Delete Task Delete scheduled task Agents & Sandboxes Tasks DELETE /api/tasks "},{"slug":"api-reference/tasks/runs","title":"Get Task Runs","description":"Get task runs","category":"Agents & Sandboxes","group":"Tasks","source":"api-reference/tasks/runs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/tasks/runs","spec":"releases.json"},"searchText":"Get Task Runs Get task runs Agents & Sandboxes Tasks GET /api/tasks/runs "},{"slug":"api-reference/content-agent/webhook","title":"Slack Webhook","description":"Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread.","category":"Agents & Sandboxes","group":"Content Agent","source":"api-reference/content-agent/webhook.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content-agent/{platform}","spec":"content.json"},"searchText":"Slack Webhook Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread. Agents & Sandboxes Content Agent POST /api/content-agent/{platform} "},{"slug":"api-reference/content-agent/callback","title":"Task Callback","description":"Internal worker callback for a configured content agent. Requires the shared callback secret in x-callback-secret. Public content creation uses POST /api/content/create.","category":"Agents & Sandboxes","group":"Content Agent","source":"api-reference/content-agent/callback.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/content-agent/callback","spec":"content.json"},"searchText":"Task Callback Internal worker callback for a configured content agent. Requires the shared callback secret in x-callback-secret. Public content creation uses POST /api/content/create. Agents & Sandboxes Content Agent POST /api/content-agent/callback "},{"slug":"api-reference/sandboxes/list","title":"List Sandboxes","description":"List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandboxes","spec":"content.json"},"searchText":"List Sandboxes List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes GET /api/sandboxes "},{"slug":"api-reference/sandboxes/create","title":"Create Sandbox","description":"Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes","spec":"content.json"},"searchText":"Create Sandbox Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes "},{"slug":"api-reference/sandboxes/snapshot","title":"Update Snapshot","description":"Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/snapshot.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sandboxes","spec":"content.json"},"searchText":"Update Snapshot Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files. Agents & Sandboxes Sandboxes PATCH /api/sandboxes "},{"slug":"api-reference/sandboxes/delete","title":"Delete Sandbox","description":"Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/sandboxes","spec":"content.json"},"searchText":"Delete Sandbox Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes DELETE /api/sandboxes "},{"slug":"api-reference/sandboxes/setup","title":"Setup Sandbox","description":"Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/setup.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/setup","spec":"content.json"},"searchText":"Setup Sandbox Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes/setup "},{"slug":"api-reference/sandboxes/get-file","title":"Get File Contents","description":"Read a file from the authenticated account's Git-backed repository, or an explicitly authorized target account's repository, including resolved submodule paths, on `main`. The repository comes from the [account's snapshot](/api-reference/sandboxes/list). Authenticate with `x-api-key` or an Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/get-file.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandboxes/file","spec":"content.json"},"searchText":"Get File Contents Read a file from the authenticated account's Git-backed repository, or an explicitly authorized target account's repository, including resolved submodule paths, on `main`. The repository comes from the [account's snapshot](/api-reference/sandboxes/list). Authenticate with `x-api-key` or an Authorization Bearer token. Agents & Sandboxes Sandboxes GET /api/sandboxes/file "},{"slug":"api-reference/sandboxes/stage-file","title":"Stage File","description":"Issue a presigned upload token so the browser can upload a file directly to Vercel Blob, then call `POST /api/sandboxes/files` with the resulting blob URL to commit it to the sandbox repo. Use `upload()` from `@vercel/blob/client` rather than calling this route by hand. Max file size 100MB.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/stage-file.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/staged-file","spec":"content.json"},"searchText":"Stage File Issue a presigned upload token so the browser can upload a file directly to Vercel Blob, then call `POST /api/sandboxes/files` with the resulting blob URL to commit it to the sandbox repo. Use `upload()` from `@vercel/blob/client` rather than calling this route by hand. Max file size 100MB. Agents & Sandboxes Sandboxes POST /api/sandboxes/staged-file "},{"slug":"api-reference/sandboxes/upload-files","title":"Upload Files","description":"Upload one or more files to the authenticated account's Git-backed repository. Each file URL is committed separately; paths inside a submodule resolve to that repository. Authenticate with `x-api-key` or an Authorization Bearer token.","category":"Agents & Sandboxes","group":"Sandboxes","source":"api-reference/sandboxes/upload-files.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandboxes/files","spec":"content.json"},"searchText":"Upload Files Upload one or more files to the authenticated account's Git-backed repository. Each file URL is committed separately; paths inside a submodule resolve to that repository. Authenticate with `x-api-key` or an Authorization Bearer token. Agents & Sandboxes Sandboxes POST /api/sandboxes/files "},{"slug":"api-reference/sessions/create","title":"Create Session","description":"Create session","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions","spec":"sessions.json"},"searchText":"Create Session Create session Agents & Sandboxes Sessions POST /api/sessions "},{"slug":"api-reference/sessions/get","title":"Get Session","description":"Get session by id","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}","spec":"sessions.json"},"searchText":"Get Session Get session by id Agents & Sandboxes Sessions GET /api/sessions/{sessionId} "},{"slug":"api-reference/sessions/patch","title":"Update Session","description":"Rename a session, change lifecycle status, or update line counters.","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/patch.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sessions/{sessionId}","spec":"sessions.json"},"searchText":"Update Session Rename a session, change lifecycle status, or update line counters. Agents & Sandboxes Sessions PATCH /api/sessions/{sessionId} "},{"slug":"api-reference/sessions/list-chats","title":"List Session Chats","description":"List session chats","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/list-chats.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}/chats","spec":"sessions.json"},"searchText":"List Session Chats List session chats Agents & Sandboxes Sessions GET /api/sessions/{sessionId}/chats "},{"slug":"api-reference/sessions/create-chat","title":"Create Session Chat","description":"Create session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/create-chat.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions/{sessionId}/chats","spec":"sessions.json"},"searchText":"Create Session Chat Create session chat Agents & Sandboxes Sessions POST /api/sessions/{sessionId}/chats "},{"slug":"api-reference/sessions/get-chat","title":"Get Session Chat","description":"Get session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/get-chat.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Get Session Chat Get session chat Agents & Sandboxes Sessions GET /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/patch-chat","title":"Update Session Chat","description":"Update session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/patch-chat.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Update Session Chat Update session chat Agents & Sandboxes Sessions PATCH /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/delete-chat","title":"Delete Session Chat","description":"Delete session chat","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/delete-chat.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/sessions/{sessionId}/chats/{chatId}","spec":"sessions.json"},"searchText":"Delete Session Chat Delete session chat Agents & Sandboxes Sessions DELETE /api/sessions/{sessionId}/chats/{chatId} "},{"slug":"api-reference/sessions/mark-chat-read","title":"Mark Chat Read","description":"Marks a session chat as read for the authenticated account.","category":"Agents & Sandboxes","group":"Sessions","source":"api-reference/sessions/mark-chat-read.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sessions/{sessionId}/chats/{chatId}/read","spec":"sessions.json"},"searchText":"Mark Chat Read Marks a session chat as read for the authenticated account. Agents & Sandboxes Sessions POST /api/sessions/{sessionId}/chats/{chatId}/read "},{"slug":"api-reference/sandbox/create","title":"Create or restore session sandbox","description":"Create or restore session sandbox","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/sandbox","spec":"sandbox.json"},"searchText":"Create or restore session sandbox Create or restore session sandbox Agents & Sandboxes Session Sandboxes POST /api/sandbox "},{"slug":"api-reference/sandbox/status","title":"Get session sandbox status","description":"Get session sandbox status","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/status.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandbox/status","spec":"sandbox.json"},"searchText":"Get session sandbox status Get session sandbox status Agents & Sandboxes Session Sandboxes GET /api/sandbox/status "},{"slug":"api-reference/sandbox/reconnect","title":"Reconnect to session sandbox","description":"Reconnect to session sandbox","category":"Agents & Sandboxes","group":"Session Sandboxes","source":"api-reference/sandbox/reconnect.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/sandbox/reconnect","spec":"sandbox.json"},"searchText":"Reconnect to session sandbox Reconnect to session sandbox Agents & Sandboxes Session Sandboxes GET /api/sandbox/reconnect "},{"slug":"api-reference/accounts/id","title":"Get Account ID","description":"Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/id.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/id","spec":"accounts.json"},"searchText":"Get Account ID Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId. Accounts Accounts GET /api/accounts/id "},{"slug":"api-reference/accounts/get","title":"Get Account","description":"Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}","spec":"accounts.json"},"searchText":"Get Account Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses. Accounts Accounts GET /api/accounts/{id} "},{"slug":"api-reference/accounts/create","title":"Create Account","description":"Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts","spec":"accounts.json"},"searchText":"Create Account Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits. Accounts Accounts POST /api/accounts "},{"slug":"api-reference/accounts/update","title":"Update Account","description":"Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/accounts","spec":"accounts.json"},"searchText":"Update Account Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override. Accounts Accounts PATCH /api/accounts "},{"slug":"api-reference/accounts/add-artist","title":"Add Artist to Account","description":"Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification.","category":"Accounts","group":"Accounts","source":"api-reference/accounts/add-artist.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/artists","spec":"accounts.json"},"searchText":"Add Artist to Account Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification. Accounts Accounts POST /api/accounts/artists "},{"slug":"api-reference/subscriptions/sessions-create","title":"Create Subscription Session","description":"Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial.","category":"Accounts","group":"Billing","source":"api-reference/subscriptions/sessions-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/subscriptions/sessions","spec":"accounts.json"},"searchText":"Create Subscription Session Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial. Accounts Billing POST /api/subscriptions/sessions "},{"slug":"api-reference/subscriptions/claim-create","title":"Claim Subscription","description":"Attach a subscription bought through [Create Subscription Session](/api-reference/subscriptions/sessions-create) (anonymous path) to the authenticated account. Needed only when the signed-in email differs from the email typed into Stripe Checkout; when they match, the webhook already linked the subscription and this call is a no-op that returns 200.","category":"Accounts","group":"Billing","source":"api-reference/subscriptions/claim-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/subscriptions/claim","spec":"accounts.json"},"searchText":"Claim Subscription Attach a subscription bought through [Create Subscription Session](/api-reference/subscriptions/sessions-create) (anonymous path) to the authenticated account. Needed only when the signed-in email differs from the email typed into Stripe Checkout; when they match, the webhook already linked the subscription and this call is a no-op that returns 200. Accounts Billing POST /api/subscriptions/claim "},{"slug":"api-reference/accounts/subscription-get","title":"Get Account Subscription","description":"Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/subscription-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/subscription","spec":"accounts.json"},"searchText":"Get Account Subscription Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/subscription "},{"slug":"api-reference/accounts/portal-create","title":"Create Billing Portal Session","description":"Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. The portal opens on the Stripe customer that owns the account's active subscription, so accounts without an active subscription get a 400 even when a tagged customer with a card exists. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with an active subscription.","category":"Accounts","group":"Billing","source":"api-reference/accounts/portal-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/{id}/portal","spec":"accounts.json"},"searchText":"Create Billing Portal Session Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. The portal opens on the Stripe customer that owns the account's active subscription, so accounts without an active subscription get a 400 even when a tagged customer with a card exists. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with an active subscription. Accounts Billing POST /api/accounts/{id}/portal "},{"slug":"api-reference/accounts/payment-method-get","title":"Get Default Payment Method","description":"Retrieve the default payment method on file for an account. An account may be tagged on more than one Stripe customer (for example an organization whose card was saved on one customer and whose invoiced plan lives on another); the card is read from the tagged customer that holds a default payment method. Returns `card: null` when the selected customer has no supported default card, including when no tagged customer exists — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline. Removing the selected card does not remove other saved cards: a later read can select a different remaining card. Auto top-up stays off after successful removal until explicitly re-enabled.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Get Default Payment Method Retrieve the default payment method on file for an account. An account may be tagged on more than one Stripe customer (for example an organization whose card was saved on one customer and whose invoiced plan lives on another); the card is read from the tagged customer that holds a default payment method. Returns `card: null` when the selected customer has no supported default card, including when no tagged customer exists — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline. Removing the selected card does not remove other saved cards: a later read can select a different remaining card. Auto top-up stays off after successful removal until explicitly re-enabled. Accounts Billing GET /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payment-method-create","title":"Save a Payment Method","description":"Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The card is saved on the account's Stripe customer that already holds a default card, or the newest tagged customer; a customer is created (and tagged with the account id) if none exists yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Save a Payment Method Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The card is saved on the account's Stripe customer that already holds a default card, or the newest tagged customer; a customer is created (and tagged with the account id) if none exists yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing POST /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payment-method-delete","title":"Remove the Payment Method","description":"Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payment-method-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/accounts/{id}/payment-method","spec":"accounts.json"},"searchText":"Remove the Payment Method Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing DELETE /api/accounts/{id}/payment-method "},{"slug":"api-reference/accounts/payments-get","title":"List Account Payments","description":"List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/payments-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/payments","spec":"accounts.json"},"searchText":"List Account Payments List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/payments "},{"slug":"api-reference/accounts/auto-top-up-get","title":"Get Auto Top-up Settings","description":"Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/auto-top-up-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/auto-top-up","spec":"accounts.json"},"searchText":"Get Auto Top-up Settings Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing GET /api/accounts/{id}/auto-top-up "},{"slug":"api-reference/accounts/auto-top-up-update","title":"Update Auto Top-up Settings","description":"Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `id` may be the authenticated account or an organization the caller belongs to.","category":"Accounts","group":"Billing","source":"api-reference/accounts/auto-top-up-update.mdx","body":"","headings":[],"api":{"method":"PUT","path":"/api/accounts/{id}/auto-top-up","spec":"accounts.json"},"searchText":"Update Auto Top-up Settings Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `id` may be the authenticated account or an organization the caller belongs to. Accounts Billing PUT /api/accounts/{id}/auto-top-up "},{"slug":"api-reference/credits/sessions-create","title":"Create Credits Top-Up Session","description":"Top up credits on the authenticated account.","category":"Accounts","group":"Billing","source":"api-reference/credits/sessions-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/credits/sessions","spec":"accounts.json"},"searchText":"Create Credits Top-Up Session Top up credits on the authenticated account. Accounts Billing POST /api/credits/sessions "},{"slug":"api-reference/accounts/credits-get","title":"Get Account Credits","description":"Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update.","category":"Accounts","group":"Billing","source":"api-reference/accounts/credits-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/credits","spec":"accounts.json"},"searchText":"Get Account Credits Retrieve the current credit balance for an account. Returns the remaining credits along with the plan-derived monthly total and used count, plus a flag indicating whether the account is on a pro plan (directly or via an organization). Credits refill monthly; the `timestamp` field reflects the last refill or balance update. Accounts Billing GET /api/accounts/{id}/credits "},{"slug":"api-reference/accounts/usage-get","title":"Get Account Usage","description":"List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership.","category":"Accounts","group":"Billing","source":"api-reference/accounts/usage-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/accounts/{id}/usage","spec":"accounts.json"},"searchText":"Get Account Usage List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership. Accounts Billing GET /api/accounts/{id}/usage "},{"slug":"api-reference/pulses/update","title":"Update Pulse","description":"Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint.","category":"Accounts","group":"Pulses","source":"api-reference/pulses/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/pulses","spec":"accounts.json"},"searchText":"Update Pulse Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint. Accounts Pulses PATCH /api/pulses "},{"slug":"api-reference/pulses/list","title":"List Pulses","description":"Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations.","category":"Accounts","group":"Pulses","source":"api-reference/pulses/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/pulses","spec":"accounts.json"},"searchText":"List Pulses Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations. Accounts Pulses GET /api/pulses "},{"slug":"api-reference/organizations/list","title":"Get Organizations","description":"Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations","spec":"accounts.json"},"searchText":"Get Organizations Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to. Accounts Organizations GET /api/organizations "},{"slug":"api-reference/organizations/create","title":"Create Organization","description":"Create a new organization. The creator is automatically added as a member of the organization.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations","spec":"accounts.json"},"searchText":"Create Organization Create a new organization. The creator is automatically added as a member of the organization. Accounts Organizations POST /api/organizations "},{"slug":"api-reference/organizations/add-artist","title":"Add Artist to Organization","description":"Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-artist.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/artists","spec":"accounts.json"},"searchText":"Add Artist to Organization Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records. Accounts Organizations POST /api/organizations/artists "},{"slug":"api-reference/organizations/add-member","title":"Add Member to Organization","description":"Add a member to an organization. This endpoint is idempotent - Adding an existing member returns the existing membership.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-member.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/members","spec":"accounts.json"},"searchText":"Add Member to Organization Add a member to an organization. This endpoint is idempotent - Adding an existing member returns the existing membership. Accounts Organizations POST /api/organizations/members "},{"slug":"api-reference/organizations/remove-member","title":"Remove Member from Organization","description":"Remove a member from an organization. This endpoint is idempotent - Removing an account that is not a member succeeds without error.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/remove-member.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/organizations/members","spec":"accounts.json"},"searchText":"Remove Member from Organization Remove a member from an organization. This endpoint is idempotent - Removing an account that is not a member succeeds without error. Accounts Organizations DELETE /api/organizations/members "},{"slug":"api-reference/organizations/list-domains","title":"List Organization Domains","description":"List the email domains mapped to an organization. Accounts that sign up with an email at a mapped domain automatically join the organization.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/list-domains.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"List Organization Domains List the email domains mapped to an organization. Accounts that sign up with an email at a mapped domain automatically join the organization. Accounts Organizations GET /api/organizations/domains "},{"slug":"api-reference/organizations/add-domain","title":"Add Organization Domain","description":"Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/add-domain.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"Add Organization Domain Map an email domain to an organization for automatic membership. After mapping, any account that signs up (or signs in) with an email at this domain is automatically added to the organization. A domain can belong to at most one organization. This endpoint is idempotent - re-adding the same domain to the same organization returns the existing mapping. Accounts Organizations POST /api/organizations/domains "},{"slug":"api-reference/organizations/remove-domain","title":"Remove Organization Domain","description":"Remove an email domain mapping from an organization. New signups at this domain will no longer auto-join the organization; existing members are not affected. This endpoint is idempotent.","category":"Accounts","group":"Organizations","source":"api-reference/organizations/remove-domain.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/organizations/domains","spec":"accounts.json"},"searchText":"Remove Organization Domain Remove an email domain mapping from an organization. New signups at this domain will no longer auto-join the organization; existing members are not affected. This endpoint is idempotent. Accounts Organizations DELETE /api/organizations/domains "},{"slug":"api-reference/organizations/professionals","title":"List Professional Roster","description":"List professional roster","category":"Accounts","group":"Organizations","source":"api-reference/organizations/professionals.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/organizations/professionals","spec":"accounts.json"},"searchText":"List Professional Roster List professional roster Accounts Organizations GET /api/organizations/professionals "},{"slug":"api-reference/organizations/professionals-confirm","title":"Confirm Professional Roster Addition","description":"Confirm professional roster addition","category":"Accounts","group":"Organizations","source":"api-reference/organizations/professionals-confirm.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/organizations/professionals","spec":"accounts.json"},"searchText":"Confirm Professional Roster Addition Confirm professional roster addition Accounts Organizations POST /api/organizations/professionals "},{"slug":"api-reference/admins/check","title":"Check Admin Status","description":"Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header.","category":"Accounts","group":"Admins","source":"api-reference/admins/check.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins","spec":"accounts.json"},"searchText":"Check Admin Status Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header. Accounts Admins GET /api/admins "},{"slug":"api-reference/admins/sandboxes","title":"List Account Sandboxes (Admin)","description":"Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/sandboxes.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/sandboxes","spec":"accounts.json"},"searchText":"List Account Sandboxes (Admin) Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/sandboxes "},{"slug":"api-reference/admins/sandboxes-orgs","title":"List Org Repo Stats (Admin)","description":"Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/sandboxes-orgs.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/sandboxes/orgs","spec":"accounts.json"},"searchText":"List Org Repo Stats (Admin) Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/sandboxes/orgs "},{"slug":"api-reference/admins/emails","title":"List Account Emails (Admin)","description":"Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email).","category":"Accounts","group":"Admins","source":"api-reference/admins/emails.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/emails","spec":"accounts.json"},"searchText":"List Account Emails (Admin) Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email). Accounts Admins GET /api/admins/emails "},{"slug":"api-reference/admins/privy","title":"List Privy Logins (Admin)","description":"Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/privy.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/privy","spec":"accounts.json"},"searchText":"List Privy Logins (Admin) Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/privy "},{"slug":"api-reference/admins/coding-agent-slack-tags","title":"List Coding Agent Slack Tags (Admin)","description":"Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Optional tag filters by the exact, case-sensitive Slack author ID after trimming whitespace. Filtering happens after the existing period collection and before all totals are calculated; omission preserves the unfiltered report, and an unknown ID returns empty tags with zero totals. Empty or whitespace-only tag values return 400 after admin authentication. This is display filtering, not authorization or a reduction in Slack collection work. Collection retains its existing channel access, retention, history/thread pagination and partial-failure limits. No automatic caller, UI, polling, scheduled action or Slack send is added.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-agent-slack-tags.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding/slack","spec":"accounts.json"},"searchText":"List Coding Agent Slack Tags (Admin) Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Optional tag filters by the exact, case-sensitive Slack author ID after trimming whitespace. Filtering happens after the existing period collection and before all totals are calculated; omission preserves the unfiltered report, and an unknown ID returns empty tags with zero totals. Empty or whitespace-only tag values return 400 after admin authentication. This is display filtering, not authorization or a reduction in Slack collection work. Collection retains its existing channel access, retention, history/thread pagination and partial-failure limits. No automatic caller, UI, polling, scheduled action or Slack send is added. Accounts Admins GET /api/admins/coding/slack "},{"slug":"api-reference/admins/coding-agent-slack-authors","title":"List Coding Agent Slack Authors (Admin)","description":"Returns distinct authors of collected Coding Agent mentions for an admin author selector. Requires the authenticated account to be a Recoup admin, using exactly one of x-api-key or Authorization Bearer. No query parameters are defined. Each authorized request runs the existing all-period Slack collector once, then deduplicates by Slack author ID, retains the first collected profile and sorts by display name using localeCompare; identical names do not merge different IDs. The result is authors in that collected data, not a complete all-time Slack directory. Existing channel access, retention, paginated history, first-page thread replies and partial-failure limits remain; partial collection can still produce an incomplete successful result. Thrown collection failures return 500. This call is not free cached metadata: a future caller must account for scan latency and quotas. The release adds no automatic caller, UI, polling, scheduled action, new Slack scope or Slack send. Production admin access, history coverage, latency and quotas were not verified by the source contract tests.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-agent-slack-authors.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding-agent/slack-tags","spec":"accounts.json"},"searchText":"List Coding Agent Slack Authors (Admin) Returns distinct authors of collected Coding Agent mentions for an admin author selector. Requires the authenticated account to be a Recoup admin, using exactly one of x-api-key or Authorization Bearer. No query parameters are defined. Each authorized request runs the existing all-period Slack collector once, then deduplicates by Slack author ID, retains the first collected profile and sorts by display name using localeCompare; identical names do not merge different IDs. The result is authors in that collected data, not a complete all-time Slack directory. Existing channel access, retention, paginated history, first-page thread replies and partial-failure limits remain; partial collection can still produce an incomplete successful result. Thrown collection failures return 500. This call is not free cached metadata: a future caller must account for scan latency and quotas. The release adds no automatic caller, UI, polling, scheduled action, new Slack scope or Slack send. Production admin access, history coverage, latency and quotas were not verified by the source contract tests. Accounts Admins GET /api/admins/coding-agent/slack-tags "},{"slug":"api-reference/admins/coding-pr","title":"Get Coding Agent PR Merged Status (Admin)","description":"Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/coding-pr.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/coding/pr","spec":"accounts.json"},"searchText":"Get Coding Agent PR Merged Status (Admin) Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/coding/pr "},{"slug":"api-reference/admins/content-slack-tags","title":"List Content Agent Slack Tags (Admin)","description":"Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.","category":"Accounts","group":"Admins","source":"api-reference/admins/content-slack-tags.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/content/slack","spec":"accounts.json"},"searchText":"List Content Agent Slack Tags (Admin) Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Accounts Admins GET /api/admins/content/slack "},{"slug":"api-reference/admins/agent-signups","title":"Admin signup report availability","description":"An admin key-metadata report is available; the former signup-report URL and broader reporting outcome remain separate.","category":"Accounts","group":"Admins","source":"api-reference/admins/agent-signups.mdx","body":"`GET /api/admins/agent/signups` is not available. The new\n[admin key-metadata report](/api-reference/admins/agent-key-metadata) uses\n`GET /api/admins/agent-signups` (a different URL).\n\nA Recoup admin can use the new report to inspect key-record IDs, names, creation\ntimes and matching current `agent+…` email addresses. It never returns API-key\ncredentials or hashes. Its `total` counts the returned key records; several keys\ncan belong to one account. It does not establish where an account signed up,\nhow many unique agents signed up, which keys are active, or whether people use\nthe product. Current email associations, database visibility and server row limits\nalso prevent a guarantee of complete historical reporting.\n\n## Unfinished reporting outcome\n\n[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the\nbroader reporting decision. The bounded metadata route from\n[API #1095](https://github.com/recoupable/api/pull/1095) does not complete the original\n[API #428](https://github.com/recoupable/api/issues/428) customer outcome or restore\nthe former URL. Follow the new route's period, admin-access and collection-limit\nnotes when using it; do not treat key-record counts as signup-origin or adoption\nmeasurements.\n","headings":[{"title":"Unfinished reporting outcome","id":"unfinished-reporting-outcome"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/admins/agent/signups\"\n }), \" is not available. The new\\n\", _jsx(_components.a, {\n href: \"/api-reference/admins/agent-key-metadata\",\n children: \"admin key-metadata report\"\n }), \" uses\\n\", _jsx(_components.code, {\n children: \"GET /api/admins/agent-signups\"\n }), \" (a different URL).\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A Recoup admin can use the new report to inspect key-record IDs, names, creation\\ntimes and matching current \", _jsx(_components.code, {\n children: \"agent+…\"\n }), \" email addresses. It never returns API-key\\ncredentials or hashes. Its \", _jsx(_components.code, {\n children: \"total\"\n }), \" counts the returned key records; several keys\\ncan belong to one account. It does not establish where an account signed up,\\nhow many unique agents signed up, which keys are active, or whether people use\\nthe product. Current email associations, database visibility and server row limits\\nalso prevent a guarantee of complete historical reporting.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"unfinished-reporting-outcome\",\n children: \"Unfinished reporting outcome\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.a, {\n href: \"https://github.com/recoupable/mono/issues/327\",\n children: \"Reconciliation #327\"\n }), \" retains the\\nbroader reporting decision. The bounded metadata route from\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/pull/1095\",\n children: \"API #1095\"\n }), \" does not complete the original\\n\", _jsx(_components.a, {\n href: \"https://github.com/recoupable/api/issues/428\",\n children: \"API #428\"\n }), \" customer outcome or restore\\nthe former URL. Follow the new route's period, admin-access and collection-limit\\nnotes when using it; do not treat key-record counts as signup-origin or adoption\\nmeasurements.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Admin signup report availability An admin key-metadata report is available; the former signup-report URL and broader reporting outcome remain separate. Accounts Admins `GET /api/admins/agent/signups` is not available. The new [admin key-metadata report](/api-reference/admins/agent-key-metadata) uses `GET /api/admins/agent-signups` (a different URL). A Recoup admin can use the new report to inspect key-record IDs, names, creation times and matching current `agent+…` email addresses. It never returns API-key credentials or hashes. Its `total` counts the returned key records; several keys can belong to one account. It does not establish where an account signed up, how many unique agents signed up, which keys are active, or whether people use the product. Current email associations, database visibility and server row limits also prevent a guarantee of complete historical reporting. ## Unfinished reporting outcome [Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the broader reporting decision. The bounded metadata route from [API #1095](https://github.com/recoupable/api/pull/1095) does not complete the original [API #428](https://github.com/recoupable/api/issues/428) customer outcome or restore the former URL. Follow the new route's period, admin-access and collection-limit notes when using it; do not treat key-record counts as signup-origin or adoption measurements. "},{"slug":"api-reference/admins/agent-key-metadata","title":"List Agent Key Metadata (Admin)","description":"List agent-prefixed API-key metadata (Admin)","category":"Accounts","group":"Admins","source":"api-reference/admins/agent-key-metadata.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/agent-signups","spec":"accounts.json"},"searchText":"List Agent Key Metadata (Admin) List agent-prefixed API-key metadata (Admin) Accounts Admins GET /api/admins/agent-signups "},{"slug":"api-reference/admins/artists-pro","title":"List Pro Artists (Admin)","description":"Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is \"pro\" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts.","category":"Accounts","group":"Admins","source":"api-reference/admins/artists-pro.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/artists/pro","spec":"accounts.json"},"searchText":"List Pro Artists (Admin) Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is \"pro\" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts. Accounts Admins GET /api/admins/artists/pro "},{"slug":"api-reference/admins/credits-rollup","title":"Credit Usage Rollup (Admin)","description":"Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-rollup.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/credits/rollup","spec":"accounts.json"},"searchText":"Credit Usage Rollup (Admin) Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin. Accounts Admins GET /api/admins/credits/rollup "},{"slug":"api-reference/admins/credits-events","title":"Credit Usage Events (Admin)","description":"Returns the raw `usage_events` rows for a single account over the selected period, sorted by `created_at` descending. Powers the drilldown view that expands when a row in the [`/api/admins/credits/rollup`](/api-reference/admins/credits-rollup) table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and `credits_deducted` matching the wallet drop on `credits_usage` for that account.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-events.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/admins/credits/events","spec":"accounts.json"},"searchText":"Credit Usage Events (Admin) Returns the raw `usage_events` rows for a single account over the selected period, sorted by `created_at` descending. Powers the drilldown view that expands when a row in the [`/api/admins/credits/rollup`](/api-reference/admins/credits-rollup) table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and `credits_deducted` matching the wallet drop on `credits_usage` for that account. Accounts Admins GET /api/admins/credits/events "},{"slug":"api-reference/admins/credits-grant","title":"Grant Credits (Admin)","description":"Sets an account's credit balance, and records who set it and why. Requires the authenticated account to be a Recoup admin.","category":"Accounts","group":"Admins","source":"api-reference/admins/credits-grant.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/admins/credits","spec":"accounts.json"},"searchText":"Grant Credits (Admin) Sets an account's credit balance, and records who set it and why. Requires the authenticated account to be a Recoup admin. Accounts Admins POST /api/admins/credits "},{"slug":"api-reference/emails/create","title":"Send Email","description":"Send an email to one or more recipients. Emails are sent from `Agent by Recoup `.","category":"Accounts","group":"Emails","source":"api-reference/emails/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/emails","spec":"accounts.json"},"searchText":"Send Email Send an email to one or more recipients. Emails are sent from `Agent by Recoup `. Accounts Emails POST /api/emails "},{"slug":"api-reference/projects/get","title":"Get Project","description":"Get project","category":"Accounts","group":"Projects","source":"api-reference/projects/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}","spec":"projects.json"},"searchText":"Get Project Get project Accounts Projects GET /api/projects/{projectId} "},{"slug":"api-reference/projects/task-get","title":"Get Project Task","description":"Get project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Get Project Task Get project task Accounts Projects GET /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/task-create","title":"Create Project Task","description":"Create project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/projects/{projectId}/tasks","spec":"projects.json"},"searchText":"Create Project Task Create project task Accounts Projects POST /api/projects/{projectId}/tasks "},{"slug":"api-reference/projects/task-update","title":"Update Project Task","description":"Update project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Update Project Task Update project task Accounts Projects PATCH /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/task-delete","title":"Delete Project Task","description":"Delete project task","category":"Accounts","group":"Projects","source":"api-reference/projects/task-delete.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/projects/{projectId}/tasks/{taskId}","spec":"projects.json"},"searchText":"Delete Project Task Delete project task Accounts Projects DELETE /api/projects/{projectId}/tasks/{taskId} "},{"slug":"api-reference/projects/comments-get","title":"List Task Comments","description":"List task comments","category":"Accounts","group":"Projects","source":"api-reference/projects/comments-get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/projects/{projectId}/tasks/{taskId}/comments","spec":"projects.json"},"searchText":"List Task Comments List task comments Accounts Projects GET /api/projects/{projectId}/tasks/{taskId}/comments "},{"slug":"api-reference/projects/comments-create","title":"Add Task Comment","description":"Add task comment","category":"Accounts","group":"Projects","source":"api-reference/projects/comments-create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/projects/{projectId}/tasks/{taskId}/comments","spec":"projects.json"},"searchText":"Add Task Comment Add task comment Accounts Projects POST /api/projects/{projectId}/tasks/{taskId}/comments "},{"slug":"connectors/ownership","title":"Connection Ownership","description":"The connector connection-ownership and authority contract: who owns a connection, who can act through it, and why roster membership never grants execute rights.","category":"Connectors","group":"Concepts","source":"connectors/ownership.mdx","body":"## Overview\n\nConnectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the **ownership and authority contract** for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it.\n\nThis contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the [Connectors API reference](/api-reference/connectors/list).\n\n---\n\n## Association ≠ Authority\n\nArtists in Recoup are **canonical and shared**. The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections:\n\n- An artist appearing in an account's roster (`account_artist_ids`) grants **read and analytics access only**.\n- An artist appearing in an organization's roster likewise grants **read and analytics access only** to org members.\n- Neither form of association ever grants the right to authorize, execute, or disconnect a connection.\n\n\nRoster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does **not** let Account B post through that connection.\n\n\n---\n\n## Connection Scope\n\nConnections are scoped to the **relationship between an owner and an artist**, not to the bare canonical artist:\n\n| Connection type | Scoped to |\n|-----------------|-----------|\n| Personal | The `(account, artist)` pair |\n| Org-shared | The `(organization, artist)` pair |\n\nThe connection is keyed on the **join row** (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist.\n\n**Whoever establishes a connection owns it.** Ownership is set at authorization time and does not transfer through roster changes.\n\nBecause artists stay canonical and shared, **isolation lives on the connection**: sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it.\n\n---\n\n## Authority Matrix\n\n| Capability | Who has it |\n|------------|-----------|\n| Read / analytics on an artist | Any account or org member with the artist in their roster |\n| Authorize a new connection | The account (or org member, for org-shared) establishing the connection, who then owns it |\n| Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org |\n| Disconnect a connection | The owning account only; for org-shared connections, members of the owning org |\n| Admin override | Recoup staff only (admins of the Recoup internal organization) |\n\n\nThe admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection.\n\n\n---\n\n## Relationship to the Current API Reference\n\nThe [Connectors endpoint reference](/api-reference/connectors/list) currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-`(account, artist)` / per-`(organization, artist)` model defined here. Where the two disagree, **this page is the authority contract**. Endpoint docs will be updated as the re-keyed API ships.\n\nEndpoint request and response shapes for the re-keyed model are deliberately not documented here yet.\n","headings":[{"title":"Overview","id":"overview"},{"title":"Association ≠ Authority","id":"association-authority"},{"title":"Connection Scope","id":"connection-scope"},{"title":"Authority Matrix","id":"authority-matrix"},{"title":"Relationship to the Current API Reference","id":"relationship-to-the-current-api-reference"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n hr: \"hr\",\n li: \"li\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n }, {Note, Warning} = _components;\n if (!Note) _missingMdxReference(\"Note\", true);\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"overview\",\n children: \"Overview\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the \", _jsx(_components.strong, {\n children: \"ownership and authority contract\"\n }), \" for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors API reference\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"association-authority\",\n children: \"Association ≠ Authority\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Artists in Recoup are \", _jsx(_components.strong, {\n children: \"canonical and shared\"\n }), \". The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"An artist appearing in an account's roster (\", _jsx(_components.code, {\n children: \"account_artist_ids\"\n }), \") grants \", _jsx(_components.strong, {\n children: \"read and analytics access only\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"An artist appearing in an organization's roster likewise grants \", _jsx(_components.strong, {\n children: \"read and analytics access only\"\n }), \" to org members.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Neither form of association ever grants the right to authorize, execute, or disconnect a connection.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(Warning, {\n children: _jsxs(_components.p, {\n children: [\"Roster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does \", _jsx(_components.strong, {\n children: \"not\"\n }), \" let Account B post through that connection.\"]\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"connection-scope\",\n children: \"Connection Scope\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Connections are scoped to the \", _jsx(_components.strong, {\n children: \"relationship between an owner and an artist\"\n }), \", not to the bare canonical artist:\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Connection type\"\n }), _jsx(_components.th, {\n children: \"Scoped to\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Personal\"\n }), _jsxs(_components.td, {\n children: [\"The \", _jsx(_components.code, {\n children: \"(account, artist)\"\n }), \" pair\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Org-shared\"\n }), _jsxs(_components.td, {\n children: [\"The \", _jsx(_components.code, {\n children: \"(organization, artist)\"\n }), \" pair\"]\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The connection is keyed on the \", _jsx(_components.strong, {\n children: \"join row\"\n }), \" (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Whoever establishes a connection owns it.\"\n }), \" Ownership is set at authorization time and does not transfer through roster changes.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Because artists stay canonical and shared, \", _jsx(_components.strong, {\n children: \"isolation lives on the connection\"\n }), \": sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it.\"]\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"authority-matrix\",\n children: \"Authority Matrix\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Capability\"\n }), _jsx(_components.th, {\n children: \"Who has it\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Read / analytics on an artist\"\n }), _jsx(_components.td, {\n children: \"Any account or org member with the artist in their roster\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Authorize a new connection\"\n }), _jsx(_components.td, {\n children: \"The account (or org member, for org-shared) establishing the connection, who then owns it\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Execute actions through a connection\"\n }), _jsx(_components.td, {\n children: \"The owning account only; for org-shared connections, members of the owning org\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Disconnect a connection\"\n }), _jsx(_components.td, {\n children: \"The owning account only; for org-shared connections, members of the owning org\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: \"Admin override\"\n }), _jsx(_components.td, {\n children: \"Recoup staff only (admins of the Recoup internal organization)\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(Note, {\n children: _jsx(_components.p, {\n children: \"The admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection.\"\n })\n }), \"\\n\", _jsx(_components.hr, {}), \"\\n\", _jsx(_components.h2, {\n id: \"relationship-to-the-current-api-reference\",\n children: \"Relationship to the Current API Reference\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The \", _jsx(_components.a, {\n href: \"/api-reference/connectors/list\",\n children: \"Connectors endpoint reference\"\n }), \" currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-\", _jsx(_components.code, {\n children: \"(account, artist)\"\n }), \" / per-\", _jsx(_components.code, {\n children: \"(organization, artist)\"\n }), \" model defined here. Where the two disagree, \", _jsx(_components.strong, {\n children: \"this page is the authority contract\"\n }), \". Endpoint docs will be updated as the re-keyed API ships.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Endpoint request and response shapes for the re-keyed model are deliberately not documented here yet.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","searchText":"Connection Ownership The connector connection-ownership and authority contract: who owns a connection, who can act through it, and why roster membership never grants execute rights. Connectors Concepts ## Overview Connectors link third-party services (Google Sheets, TikTok, YouTube, X, LinkedIn, and others) to Recoup so agents can act on an artist's behalf. This page defines the **ownership and authority contract** for those connections: who a connection belongs to, and who is allowed to authorize, execute through, or disconnect it. This contract is the source of truth for connector access control. Endpoint request and response shapes are documented separately in the [Connectors API reference](/api-reference/connectors/list). --- ## Association ≠ Authority Artists in Recoup are **canonical and shared**. The same artist can appear in many accounts' rosters and in multiple organizations. Being associated with an artist is not the same as having authority to act through that artist's connections: - An artist appearing in an account's roster (`account_artist_ids`) grants **read and analytics access only**. - An artist appearing in an organization's roster likewise grants **read and analytics access only** to org members. - Neither form of association ever grants the right to authorize, execute, or disconnect a connection. Roster membership never inherits connection authority. If Account A connects an artist's TikTok, Account B having that same artist on its roster does **not** let Account B post through that connection. --- ## Connection Scope Connections are scoped to the **relationship between an owner and an artist**, not to the bare canonical artist: | Connection type | Scoped to | |-----------------|-----------| | Personal | The `(account, artist)` pair | | Org-shared | The `(organization, artist)` pair | The connection is keyed on the **join row** (the specific account-to-artist or org-to-artist relationship), never on the canonical artist alone. Two accounts that both roster the same artist hold two independent connection scopes for that artist. **Whoever establishes a connection owns it.** Ownership is set at authorization time and does not transfer through roster changes. Because artists stay canonical and shared, **isolation lives on the connection**: sharing an artist across accounts and orgs is safe precisely because each connection is confined to the relationship that created it. --- ## Authority Matrix | Capability | Who has it | |------------|-----------| | Read / analytics on an artist | Any account or org member with the artist in their roster | | Authorize a new connection | The account (or org member, for org-shared) establishing the connection, who then owns it | | Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org | | Disconnect a connection | The owning account only; for org-shared connections, members of the owning org | | Admin override | Recoup staff only (admins of the Recoup internal organization) | The admin override exists for support and abuse response. No customer account or organization, regardless of roster or org membership, can override another owner's connection. --- ## Relationship to the Current API Reference The [Connectors endpoint reference](/api-reference/connectors/list) currently describes connections as scoped to the authenticated account alone. That reflects behavior that shipped before this contract; the API is being re-keyed to the per-`(account, artist)` / per-`(organization, artist)` model defined here. Where the two disagree, **this page is the authority contract**. Endpoint docs will be updated as the re-keyed API ships. Endpoint request and response shapes for the re-keyed model are deliberately not documented here yet. "},{"slug":"api-reference/connectors/list","title":"List Connectors","description":"List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok, YouTube, X (Twitter), LinkedIn) along with whether they are currently connected.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/connectors","spec":"social.json"},"searchText":"List Connectors List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok, YouTube, X (Twitter), LinkedIn) along with whether they are currently connected. Connectors Connectors GET /api/connectors "},{"slug":"api-reference/connectors/authorize","title":"Authorize Connector","description":"Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/authorize.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors","spec":"social.json"},"searchText":"Authorize Connector Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow. Connectors Connectors POST /api/connectors "},{"slug":"api-reference/connectors/disconnect","title":"Disconnect Connector","description":"Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/disconnect.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/connectors","spec":"social.json"},"searchText":"Disconnect Connector Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials. Connectors Connectors DELETE /api/connectors "},{"slug":"api-reference/connectors/list-actions","title":"List Connector Actions","description":"List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/list-actions.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/connectors/actions","spec":"social.json"},"searchText":"List Connector Actions List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors. Connectors Connectors GET /api/connectors/actions "},{"slug":"api-reference/connectors/upload-file","title":"Upload Connector File","description":"Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action).","category":"Connectors","group":"Connectors","source":"api-reference/connectors/upload-file.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors/files","spec":"social.json"},"searchText":"Upload Connector File Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action). Connectors Connectors POST /api/connectors/files "},{"slug":"api-reference/connectors/execute-action","title":"Execute Connector Action","description":"Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor.","category":"Connectors","group":"Connectors","source":"api-reference/connectors/execute-action.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/connectors/actions","spec":"social.json"},"searchText":"Execute Connector Action Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor. Connectors Connectors POST /api/connectors/actions "},{"slug":"api-reference/publishing/create","title":"Create Post","description":"Create post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/posts","spec":"social.json"},"searchText":"Create Post Create post Connectors Publishing POST /api/posts "},{"slug":"api-reference/publishing/list","title":"List Posts","description":"List posts","category":"Connectors","group":"Publishing","source":"api-reference/publishing/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/posts","spec":"social.json"},"searchText":"List Posts List posts Connectors Publishing GET /api/posts "},{"slug":"api-reference/publishing/get","title":"Get Post","description":"Get post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/posts/{id}","spec":"social.json"},"searchText":"Get Post Get post Connectors Publishing GET /api/posts/{id} "},{"slug":"api-reference/publishing/stats","title":"Get Post Stats","description":"Get post stats","category":"Connectors","group":"Publishing","source":"api-reference/publishing/stats.mdx","body":"## Data coverage\n\nLinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds.\n","headings":[{"title":"Data coverage","id":"data-coverage"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n h2: \"h2\",\n p: \"p\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.h2, {\n id: \"data-coverage\",\n children: \"Data coverage\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"LinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","api":{"method":"GET","path":"/api/posts/{id}/stats","spec":"social.json"},"searchText":"Get Post Stats Get post stats Connectors Publishing GET /api/posts/{id}/stats ## Data coverage LinkedIn reports organic activity only, within a rolling 12-month window; a post older than 12 months returns what LinkedIn still holds. "},{"slug":"api-reference/publishing/cancel","title":"Cancel Post","description":"Cancel post","category":"Connectors","group":"Publishing","source":"api-reference/publishing/cancel.mdx","body":"","headings":[],"api":{"method":"DELETE","path":"/api/posts/{id}","spec":"social.json"},"searchText":"Cancel Post Cancel post Connectors Publishing DELETE /api/posts/{id} "},{"slug":"api-reference/applications/validate-registration","title":"Check an application proposal","description":"Validate proposed app addresses in your workspace without registering or activating an application.","category":"Sites","group":"Application proposals","source":"api-reference/applications/validate-registration.mdx","body":"\n Pending coordinated release. This checks a proposal; it does not register an\n app or make its origins trusted. Discover tool availability in your connected\n host before use.\n\n\nBefore connecting an external app, check its proposed name, environment, origins\nand return URLs. A successful result means those values passed validation for\nthe selected workspace. It does not prove domain ownership.\n\n## What happens\n\nThe preflight runs after normal Recoup authentication. First-time sign-in can\nperform normal account provisioning and send its welcome email. After that,\nthis validator does not persist an application or issue application credentials.\nIt does not edit provider callbacks, create fan identities or sessions, allocate\ncapacity, or authorize purchases and spending.\n\n`workspace_id` and `billing_owner_id` come from the authenticated account or an\norganization it can access. They describe the proposed owner only. Supplying\n`organization_id` does not grant workspace access. Do not submit account or\nbilling ownership overrides, secrets or tokens in the proposal.\n\nThe result is flat and includes `status: \"validated\"`, `persisted: false` and\n`origins_verified: false`. It contains no application ID or token to install.\n\n## Addresses and environments\n\n- Choose `development` or `production` explicitly for each proposal.\n- Use exact canonical origins such as `https://music.example`, without a trailing\n slash, wildcard, path, credentials, query or fragment. Different hosts and\n ports are different origins.\n- HTTPS is required. Development also accepts HTTP on `localhost`, `127.0.0.1`\n and `[::1]`; these loopback hosts are rejected in production.\n- A return URL must be an exact canonical URL on one of the proposed origins,\n without credentials or fragments. For a bare host use its canonical trailing\n slash, such as `https://music.example/`. Query strings are retained literally.\n- Each list takes 1–32 distinct addresses, each at most 2048 characters. The name\n is trimmed and must then contain 1–120 characters. These are input limits,\n not subscription or usage allowances.\n\nMatching a return URL to a caller-proposed origin does not establish that the\ncaller owns either address. No DNS check, URL fetch or domain proof is performed.\n\n## Standard MCP\n\nOn a standard API-key MCP connection that exposes `validate_application_registration`,\nuse the same proposal fields as HTTP. Account identity comes from the connection;\ndo not add `account_id` or extract a host-managed OAuth token.\n\n```json\n{\n \"name\": \"Release companion\",\n \"environment\": \"production\",\n \"allowed_origins\": [\"https://music.example\"],\n \"return_urls\": [\"https://music.example/listen?connected=spotify\"]\n}\n```\n\nDelegated OAuth excludes this tool, including connections with `mcp:tools`.\nHTTP and standard MCP share proposal validation; their transport-specific error\nenvelopes differ. HTTP authentication errors can use `error` or `message`, while\nhandled preflight errors use `status: \"error\"` and `error`. MCP failures are tool\nerrors or SDK input-validation errors. None confirms registration or activation.\n\nSee [authentication](/authentication) and [MCP connection guidance](/mcp).\nApplication persistence, origin proof/reverification, provider configuration,\nfan bootstrap, suspension and quota policy require their own completed contracts.\n","headings":[{"title":"What happens","id":"what-happens"},{"title":"Addresses and environments","id":"addresses-and-environments"},{"title":"Standard MCP","id":"standard-mcp"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n ul: \"ul\",\n ...props.components\n }, {Warning} = _components;\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Pending coordinated release. This checks a proposal; it does not register an\\napp or make its origins trusted. Discover tool availability in your connected\\nhost before use.\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before connecting an external app, check its proposed name, environment, origins\\nand return URLs. A successful result means those values passed validation for\\nthe selected workspace. It does not prove domain ownership.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-happens\",\n children: \"What happens\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The preflight runs after normal Recoup authentication. First-time sign-in can\\nperform normal account provisioning and send its welcome email. After that,\\nthis validator does not persist an application or issue application credentials.\\nIt does not edit provider callbacks, create fan identities or sessions, allocate\\ncapacity, or authorize purchases and spending.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"workspace_id\"\n }), \" and \", _jsx(_components.code, {\n children: \"billing_owner_id\"\n }), \" come from the authenticated account or an\\norganization it can access. They describe the proposed owner only. Supplying\\n\", _jsx(_components.code, {\n children: \"organization_id\"\n }), \" does not grant workspace access. Do not submit account or\\nbilling ownership overrides, secrets or tokens in the proposal.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The result is flat and includes \", _jsx(_components.code, {\n children: \"status: \\\"validated\\\"\"\n }), \", \", _jsx(_components.code, {\n children: \"persisted: false\"\n }), \" and\\n\", _jsx(_components.code, {\n children: \"origins_verified: false\"\n }), \". It contains no application ID or token to install.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"addresses-and-environments\",\n children: \"Addresses and environments\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Choose \", _jsx(_components.code, {\n children: \"development\"\n }), \" or \", _jsx(_components.code, {\n children: \"production\"\n }), \" explicitly for each proposal.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use exact canonical origins such as \", _jsx(_components.code, {\n children: \"https://music.example\"\n }), \", without a trailing\\nslash, wildcard, path, credentials, query or fragment. Different hosts and\\nports are different origins.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"HTTPS is required. Development also accepts HTTP on \", _jsx(_components.code, {\n children: \"localhost\"\n }), \", \", _jsx(_components.code, {\n children: \"127.0.0.1\"\n }), \"\\nand \", _jsx(_components.code, {\n children: \"[::1]\"\n }), \"; these loopback hosts are rejected in production.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"A return URL must be an exact canonical URL on one of the proposed origins,\\nwithout credentials or fragments. For a bare host use its canonical trailing\\nslash, such as \", _jsx(_components.code, {\n children: \"https://music.example/\"\n }), \". Query strings are retained literally.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Each list takes 1–32 distinct addresses, each at most 2048 characters. The name\\nis trimmed and must then contain 1–120 characters. These are input limits,\\nnot subscription or usage allowances.\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Matching a return URL to a caller-proposed origin does not establish that the\\ncaller owns either address. No DNS check, URL fetch or domain proof is performed.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"standard-mcp\",\n children: \"Standard MCP\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"On a standard API-key MCP connection that exposes \", _jsx(_components.code, {\n children: \"validate_application_registration\"\n }), \",\\nuse the same proposal fields as HTTP. Account identity comes from the connection;\\ndo not add \", _jsx(_components.code, {\n children: \"account_id\"\n }), \" or extract a host-managed OAuth token.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"name\\\": \\\"Release companion\\\",\\n \\\"environment\\\": \\\"production\\\",\\n \\\"allowed_origins\\\": [\\\"https://music.example\\\"],\\n \\\"return_urls\\\": [\\\"https://music.example/listen?connected=spotify\\\"]\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Delegated OAuth excludes this tool, including connections with \", _jsx(_components.code, {\n children: \"mcp:tools\"\n }), \".\\nHTTP and standard MCP share proposal validation; their transport-specific error\\nenvelopes differ. HTTP authentication errors can use \", _jsx(_components.code, {\n children: \"error\"\n }), \" or \", _jsx(_components.code, {\n children: \"message\"\n }), \", while\\nhandled preflight errors use \", _jsx(_components.code, {\n children: \"status: \\\"error\\\"\"\n }), \" and \", _jsx(_components.code, {\n children: \"error\"\n }), \". MCP failures are tool\\nerrors or SDK input-validation errors. None confirms registration or activation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/authentication\",\n children: \"authentication\"\n }), \" and \", _jsx(_components.a, {\n href: \"/mcp\",\n children: \"MCP connection guidance\"\n }), \".\\nApplication persistence, origin proof/reverification, provider configuration,\\nfan bootstrap, suspension and quota policy require their own completed contracts.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","api":{"method":"POST","path":"/api/applications/registration/validate","spec":"applications.json"},"searchText":"Check an application proposal Validate proposed app addresses in your workspace without registering or activating an application. Sites Application proposals POST /api/applications/registration/validate Pending coordinated release. This checks a proposal; it does not register an app or make its origins trusted. Discover tool availability in your connected host before use. Before connecting an external app, check its proposed name, environment, origins and return URLs. A successful result means those values passed validation for the selected workspace. It does not prove domain ownership. ## What happens The preflight runs after normal Recoup authentication. First-time sign-in can perform normal account provisioning and send its welcome email. After that, this validator does not persist an application or issue application credentials. It does not edit provider callbacks, create fan identities or sessions, allocate capacity, or authorize purchases and spending. `workspace_id` and `billing_owner_id` come from the authenticated account or an organization it can access. They describe the proposed owner only. Supplying `organization_id` does not grant workspace access. Do not submit account or billing ownership overrides, secrets or tokens in the proposal. The result is flat and includes `status: \"validated\"`, `persisted: false` and `origins_verified: false`. It contains no application ID or token to install. ## Addresses and environments - Choose `development` or `production` explicitly for each proposal. - Use exact canonical origins such as `https://music.example`, without a trailing slash, wildcard, path, credentials, query or fragment. Different hosts and ports are different origins. - HTTPS is required. Development also accepts HTTP on `localhost`, `127.0.0.1` and `[::1]`; these loopback hosts are rejected in production. - A return URL must be an exact canonical URL on one of the proposed origins, without credentials or fragments. For a bare host use its canonical trailing slash, such as `https://music.example/`. Query strings are retained literally. - Each list takes 1–32 distinct addresses, each at most 2048 characters. The name is trimmed and must then contain 1–120 characters. These are input limits, not subscription or usage allowances. Matching a return URL to a caller-proposed origin does not establish that the caller owns either address. No DNS check, URL fetch or domain proof is performed. ## Standard MCP On a standard API-key MCP connection that exposes `validate_application_registration`, use the same proposal fields as HTTP. Account identity comes from the connection; do not add `account_id` or extract a host-managed OAuth token. Delegated OAuth excludes this tool, including connections with `mcp:tools`. HTTP and standard MCP share proposal validation; their transport-specific error envelopes differ. HTTP authentication errors can use `error` or `message`, while handled preflight errors use `status: \"error\"` and `error`. MCP failures are tool errors or SDK input-validation errors. None confirms registration or activation. See [authentication](/authentication) and [MCP connection guidance](/mcp). Application persistence, origin proof/reverification, provider configuration, fan bootstrap, suspension and quota policy require their own completed contracts. "},{"slug":"api-reference/sites/overview","title":"Sites","description":"Create, generate, and publish fan experiences through the API or MCP.","category":"Sites","group":"Sites","source":"api-reference/sites/overview.mdx","body":"Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a **private draft**. Generation never publishes it automatically.\n\n## Authentication\n\nPrivate HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`.\nMCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection.\n\nThe caller is derived from authentication. Do not send an `account_id`. An optional `organizationId` selects a workspace the caller can access. Omit it for the authenticated account's workspace.\n\n## Endpoints and tools\n\n| HTTP | MCP tool | Result |\n| --- | --- | --- |\n| `GET /api/sites` | `list_sites` | `{ sites: [...] }` |\n| `POST /api/sites` | `create_site` | `{ site: ... }`, HTTP 201 |\n| `GET /api/sites/{id}` | `get_site` | `{ site: ... }` |\n| `PATCH /api/sites/{id}` action `concepts` | `propose_site_concepts` | Short pitches or missing context |\n| `PATCH /api/sites/{id}` action `generate` | `generate_site` | Generate from an optional customer-selected pitch; otherwise select a concept |\n| `PATCH /api/sites/{id}` action `generation` | `get_site_generation` | Status for the specified generation token |\n| `PATCH /api/sites/{id}` action `publish` | `publish_site` | Publish the saved draft or the playable build selected by `generationToken` |\n| `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained |\n| `PATCH /api/sites/{id}` action `delete` | `delete_site` | `{ \"deleted\": true, \"id\": \"...\" }` |\n| `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 |\n| `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` |\n\nListing accepts optional `organizationId` and `artistId` query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response.\n\n## Create and generate\n\nCreate a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL.\n\n```bash\ncurl https://api.recoupable.dev/api/sites \\\n -H \"x-api-key: $RECOUP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"releaseUrl\":\"https://open.spotify.com/track/TRACK_ID\",\"brief\":\"Build a maze game\"}'\n```\n\nOptional creation fields: `name` (120 characters), `brief` (6,000), `organizationId`, `artistId`, and `assets` (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used.\n\nRead `site.id` and `site.revision`, then start automatic generation:\n\n```json\n{\"action\":\"generate\",\"revision\":0}\n```\n\nFor Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused.\n\nTo choose a concept yourself before generation, optionally request pitches:\n\n```json\n{\"action\":\"concepts\",\"revision\":0}\n```\n\nSend this to `PATCH /api/sites/{id}`, or call MCP `propose_site_concepts` with `id` and `revision`. Optional `instruction` and `contextBriefId` apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft.\n\nThe response is `{ concepts: { status, candidates, reason }, revision }`. Status is `ready`, `needs-context`, or `no-good-concept`. Metadata and cover details alone return `needs-context`; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork.\n\nIn the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains `name`, `activity`, `fanMotivation`, `songOrArtistConnection`, and `friendHook`. Pass the selected object unchanged as `approvedConcept`:\n\n```json\n{\n \"action\": \"generate\",\n \"revision\": 0,\n \"approvedConcept\": {\n \"name\": \"CUSTOMER_SELECTED_NAME\",\n \"activity\": \"SELECTED_ACTIVITY\",\n \"fanMotivation\": \"SELECTED_MOTIVATION\",\n \"songOrArtistConnection\": \"SELECTED_CONNECTION\",\n \"friendHook\": \"SELECTED_HOOK\"\n }\n}\n```\n\nMCP `generate_site` accepts the same fields plus `id`, without `action`. A customer-authored concept is also accepted. The optional `approvedConcept` preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context.\n\nGeneration defaults to background execution and returns a generation token; poll `get_site_generation` (HTTP action `generation`) for the result. Set `background: false` only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked `needs-review`; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass.\n\nGeneration failures identify the stopped stage and leave the saved draft unchanged. A `409` means another edit changed the revision; read the site again before retrying.\n\n### Poll background generation\n\nSend this JSON body to `PATCH /api/sites/{id}` using the token returned by the\ngeneration request. MCP `get_site_generation` takes `id` and `token`, without `action`.\nPolling uses `token`; publishing and cancellation use `generationToken`.\n\n```json\n{\"action\":\"generation\",\"token\":\"TOKEN_FROM_GENERATION\"}\n```\n\nThe token is bound to its site and caller and expires. Invalid, expired or\nmismatched tokens return 404 during token verification; a missing or empty token\nis invalid input (400). A running job is not proof that a\nplayable build or a published page exists; read the returned status and progress.\n\n## Generate from saved Context Engine evidence\n\nSave a single-song `creative_direction` brief using the Context Engine `save_brief` action, then pass its snapshot ID when requesting pitches:\n\n```json\n{\n \"action\": \"concepts\",\n \"revision\": 0,\n \"contextBriefId\": \"SAVED_BRIEF_UUID\"\n}\n```\n\nPass the same `contextBriefId` with the selected `approvedConcept` to generation. It is available on both MCP `propose_site_concepts` and `generate_site`. Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied.\n\nThis path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial.\n\nGeneration still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response.\n\n## Publish\n\nAfter reviewing the intended draft or preview, publish through the same PATCH\nendpoint or MCP `publish_site`, using the site's current saved revision.\n\nPublishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports `fanConnection: \"enabled\"`.\n\nFor a custom hosted destination, HTTP callers may include `returnUrl` (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations.\n\nThe public page is `https://chat.recoupable.dev/s/{id}`.\n\n### Publish the saved draft\n\nUse the current revision from the saved site (3 in this example):\n\n```json\n{\"action\":\"publish\",\"revision\":3}\n```\n\nOmitting `generationToken` selects the saved draft, even when a background job has\na newer preview. MCP `publish_site` takes `id` and `revision`, without `action`.\n\n### Publish a working preview\n\nTo publish a specific working preview from a background generation, pass its\ntoken as `generationToken` and the site's current saved revision:\n\n```json\n{\"action\":\"publish\",\"revision\":3,\"generationToken\":\"TOKEN_FROM_GENERATION\"}\n```\n\nMCP `publish_site` uses the same fields plus `id`, without `action`. The token must\nmatch the site and caller. The selected build must contain a completed playable\nbuild step for the current site/workspace/revision; the whole generation job need\nnot already be completed. A preview that is not ready returns 400, a stale build\nreturns 409, and invalid or expired token access returns 404. A temporary saved-build\nfailure may return 503. Without `generationToken`, publication uses the saved draft;\nit does not automatically select the newest background preview.\n\n### Upgrade required\n\nAn ineligible workspace receives HTTP 402 with an error body, for example:\n\n```json\n{\"error\":\"An active paid Recoup subscription is required to publish a site. Subscribe in this site’s workspace, then publish again.\"}\n```\n\nSubscribe in the site's owning workspace before retrying the intended publish.\nThis response does not publish the site or create a checkout session.\n\n### Unpublish\n\nSend `PATCH /api/sites/{id}` with the current revision to remove the public\nsnapshot while retaining the draft. MCP `unpublish_site` takes `id` and `revision`.\n\n```json\n{\"action\":\"unpublish\",\"revision\":3}\n```\n\nAgents should publish, unpublish or delete only when explicitly instructed.\n\n## Delete and cancel generation\n\nDelete only when explicitly instructed. Send `PATCH /api/sites/{id}` with `action: \"delete\"` and the current `revision` in its JSON request body (Content-Type: application/json). Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.\n\nFor example, use the current saved revision and the token returned by a known generation:\n\n```json\n{\"action\":\"delete\",\"revision\":3,\"generationToken\":\"TOKEN_FROM_GENERATION\"}\n```\n\nOmit generationToken when no known generation needs cancellation.\n\nDeletion checks workspace access and revision, then returns `{ \"deleted\": true, \"id\": \"...\" }`. A stale revision returns 409; reload before retrying. Unpublish with `action: \"unpublish\"` when the draft should remain available.\n\n## Uploads\n\nHTTP uploads are multipart forms with a `file` field and optional `organizationId` query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature.\n\nMCP's `upload_site_asset` accepts `name`, `contentType`, `base64` file bytes, and optional `organizationId`. It uses the same validation and storage path as HTTP.\n\n## Public endpoints\n\n- `GET /api/sites/public/{id}` returns `{ snapshot: ... }` for a published site only. Drafts, account identifiers, and signup data are excluded.\n- `POST /api/sites/public/{id}/signup` accepts `{\"email\":\"fan@example.com\",\"consent\":\"yes\"}`. An optional `website` honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups.\n\nPublic pages and the browser music player render in the chat app. The API provides\nsnapshots, generation, uploads, signup persistence and the fan-connection integration\nroutes listed below.\n\n## Route coverage\n\nThe lifecycle and public snapshot/signup operations above are documented here in\nprose; they are not a complete Sites OpenAPI specification. The following existing\nroutes are accounted for as integration surfaces, outside the copyable lifecycle\nexamples. Listing them does not establish live authorization or add an MCP tool.\n\n### Authenticated integration routes\n\n| HTTP | Purpose |\n| --- | --- |\n| `GET /api/sites/{id}/fan-connection` | Read fan-connection configuration |\n| `PUT /api/sites/{id}/fan-connection` | Configure the fan connection through the authenticated integration |\n| `GET /api/sites/{id}/fans` | Fan reporting |\n| `GET /api/sites/{id}/activity` | Activity reporting |\n\n### Browser integration routes\n\n| HTTP | Purpose |\n| --- | --- |\n| `GET /api/sites/apple/config` | Browser music configuration |\n| `POST /api/sites/public/{id}/activity` | Published-site activity collection |\n| `GET /api/sites/public/{id}/spotify` | Show the fan-connection acceptance page |\n| `POST /api/sites/public/{id}/spotify` | Begin Spotify authorization after acceptance |\n\nThese browser flows are not replacements for a private lifecycle request or proof\nof a completed fan connection. Email signup and Spotify connection are distinct.\n\n### Provider callback\n\n`GET /api/sites/spotify/callback` completes the provider redirect flow. It is\nintentionally excluded from agent lifecycle examples; do not invoke it as a\nstandalone operation. OPTIONS preflight handlers are also excluded from the\noperation tables because they serve browser CORS negotiation.\n\n## Errors\n\n- `402`: publication requires an eligible paid workspace.\n\n`400` invalid input; `401` missing/invalid authentication; `403` workspace or artist access denied; `404` missing/unpublished site; `409` stale revision; `422` Spotify metadata unavailable; `503` temporary operation failure.\n","headings":[{"title":"Authentication","id":"authentication"},{"title":"Endpoints and tools","id":"endpoints-and-tools"},{"title":"Create and generate","id":"create-and-generate"},{"title":"Generate from saved Context Engine evidence","id":"generate-from-saved-context-engine-evidence"},{"title":"Publish","id":"publish"},{"title":"Delete and cancel generation","id":"delete-and-cancel-generation"},{"title":"Uploads","id":"uploads"},{"title":"Public endpoints","id":"public-endpoints"},{"title":"Route coverage","id":"route-coverage"},{"title":"Errors","id":"errors"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n h3: \"h3\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a \", _jsx(_components.strong, {\n children: \"private draft\"\n }), \". Generation never publishes it automatically.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"authentication\",\n children: \"Authentication\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Private HTTP endpoints accept exactly one of \", _jsx(_components.code, {\n children: \"x-api-key: YOUR_API_KEY\"\n }), \" or \", _jsx(_components.code, {\n children: \"Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN\"\n }), \".\\nMCP uses the existing authenticated \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev/mcp\"\n }), \" connection.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The caller is derived from authentication. Do not send an \", _jsx(_components.code, {\n children: \"account_id\"\n }), \". An optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" selects a workspace the caller can access. Omit it for the authenticated account's workspace.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"endpoints-and-tools\",\n children: \"Endpoints and tools\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"MCP tool\"\n }), _jsx(_components.th, {\n children: \"Result\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"list_sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ sites: [...] }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"create_site\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"{ site: ... }\"\n }), \", HTTP 201\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ site: ... }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"concepts\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"propose_site_concepts\"\n })\n }), _jsx(_components.td, {\n children: \"Short pitches or missing context\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"generate\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"generate_site\"\n })\n }), _jsx(_components.td, {\n children: \"Generate from an optional customer-selected pitch; otherwise select a concept\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"generation\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site_generation\"\n })\n }), _jsx(_components.td, {\n children: \"Status for the specified generation token\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"publish\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"publish_site\"\n })\n }), _jsxs(_components.td, {\n children: [\"Publish the saved draft or the playable build selected by \", _jsx(_components.code, {\n children: \"generationToken\"\n })]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"unpublish\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"unpublish_site\"\n })\n }), _jsx(_components.td, {\n children: \"Public snapshot removed, draft retained\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" action \", _jsx(_components.code, {\n children: \"delete\"\n })]\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"delete_site\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ \\\"deleted\\\": true, \\\"id\\\": \\\"...\\\" }\"\n })\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/signups\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"get_site_signups\"\n })\n }), _jsxs(_components.td, {\n children: [_jsx(_components.code, {\n children: \"{ signups: [{ email, created_at }] }\"\n }), \", up to 10,000\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/assets\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"upload_site_asset\"\n })\n }), _jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"{ asset: { url, name, type } }\"\n })\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Listing accepts optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" and \", _jsx(_components.code, {\n children: \"artistId\"\n }), \" query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"create-and-generate\",\n children: \"Create and generate\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Create a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL.\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-bash\",\n children: \"curl https://api.recoupable.dev/api/sites \\\\\\n -H \\\"x-api-key: $RECOUP_API_KEY\\\" \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"releaseUrl\\\":\\\"https://open.spotify.com/track/TRACK_ID\\\",\\\"brief\\\":\\\"Build a maze game\\\"}'\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Optional creation fields: \", _jsx(_components.code, {\n children: \"name\"\n }), \" (120 characters), \", _jsx(_components.code, {\n children: \"brief\"\n }), \" (6,000), \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \", \", _jsx(_components.code, {\n children: \"artistId\"\n }), \", and \", _jsx(_components.code, {\n children: \"assets\"\n }), \" (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Read \", _jsx(_components.code, {\n children: \"site.id\"\n }), \" and \", _jsx(_components.code, {\n children: \"site.revision\"\n }), \", then start automatic generation:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"generate\\\",\\\"revision\\\":0}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"For Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"To choose a concept yourself before generation, optionally request pitches:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"concepts\\\",\\\"revision\\\":0}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send this to \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \", or call MCP \", _jsx(_components.code, {\n children: \"propose_site_concepts\"\n }), \" with \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \". Optional \", _jsx(_components.code, {\n children: \"instruction\"\n }), \" and \", _jsx(_components.code, {\n children: \"contextBriefId\"\n }), \" apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The response is \", _jsx(_components.code, {\n children: \"{ concepts: { status, candidates, reason }, revision }\"\n }), \". Status is \", _jsx(_components.code, {\n children: \"ready\"\n }), \", \", _jsx(_components.code, {\n children: \"needs-context\"\n }), \", or \", _jsx(_components.code, {\n children: \"no-good-concept\"\n }), \". Metadata and cover details alone return \", _jsx(_components.code, {\n children: \"needs-context\"\n }), \"; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"In the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"activity\"\n }), \", \", _jsx(_components.code, {\n children: \"fanMotivation\"\n }), \", \", _jsx(_components.code, {\n children: \"songOrArtistConnection\"\n }), \", and \", _jsx(_components.code, {\n children: \"friendHook\"\n }), \". Pass the selected object unchanged as \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"action\\\": \\\"generate\\\",\\n \\\"revision\\\": 0,\\n \\\"approvedConcept\\\": {\\n \\\"name\\\": \\\"CUSTOMER_SELECTED_NAME\\\",\\n \\\"activity\\\": \\\"SELECTED_ACTIVITY\\\",\\n \\\"fanMotivation\\\": \\\"SELECTED_MOTIVATION\\\",\\n \\\"songOrArtistConnection\\\": \\\"SELECTED_CONNECTION\\\",\\n \\\"friendHook\\\": \\\"SELECTED_HOOK\\\"\\n }\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP \", _jsx(_components.code, {\n children: \"generate_site\"\n }), \" accepts the same fields plus \", _jsx(_components.code, {\n children: \"id\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \". A customer-authored concept is also accepted. The optional \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \" preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Generation defaults to background execution and returns a generation token; poll \", _jsx(_components.code, {\n children: \"get_site_generation\"\n }), \" (HTTP action \", _jsx(_components.code, {\n children: \"generation\"\n }), \") for the result. Set \", _jsx(_components.code, {\n children: \"background: false\"\n }), \" only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked \", _jsx(_components.code, {\n children: \"needs-review\"\n }), \"; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Generation failures identify the stopped stage and leave the saved draft unchanged. A \", _jsx(_components.code, {\n children: \"409\"\n }), \" means another edit changed the revision; read the site again before retrying.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"poll-background-generation\",\n children: \"Poll background generation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send this JSON body to \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" using the token returned by the\\ngeneration request. MCP \", _jsx(_components.code, {\n children: \"get_site_generation\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"token\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \".\\nPolling uses \", _jsx(_components.code, {\n children: \"token\"\n }), \"; publishing and cancellation use \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"generation\\\",\\\"token\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"The token is bound to its site and caller and expires. Invalid, expired or\\nmismatched tokens return 404 during token verification; a missing or empty token\\nis invalid input (400). A running job is not proof that a\\nplayable build or a published page exists; read the returned status and progress.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"generate-from-saved-context-engine-evidence\",\n children: \"Generate from saved Context Engine evidence\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Save a single-song \", _jsx(_components.code, {\n children: \"creative_direction\"\n }), \" brief using the Context Engine \", _jsx(_components.code, {\n children: \"save_brief\"\n }), \" action, then pass its snapshot ID when requesting pitches:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"action\\\": \\\"concepts\\\",\\n \\\"revision\\\": 0,\\n \\\"contextBriefId\\\": \\\"SAVED_BRIEF_UUID\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Pass the same \", _jsx(_components.code, {\n children: \"contextBriefId\"\n }), \" with the selected \", _jsx(_components.code, {\n children: \"approvedConcept\"\n }), \" to generation. It is available on both MCP \", _jsx(_components.code, {\n children: \"propose_site_concepts\"\n }), \" and \", _jsx(_components.code, {\n children: \"generate_site\"\n }), \". Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Generation still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"publish\",\n children: \"Publish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"After reviewing the intended draft or preview, publish through the same PATCH\\nendpoint or MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \", using the site's current saved revision.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Publishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports \", _jsx(_components.code, {\n children: \"fanConnection: \\\"enabled\\\"\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For a custom hosted destination, HTTP callers may include \", _jsx(_components.code, {\n children: \"returnUrl\"\n }), \" (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The public page is \", _jsx(_components.code, {\n children: \"https://chat.recoupable.dev/s/{id}\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"publish-the-saved-draft\",\n children: \"Publish the saved draft\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the current revision from the saved site (3 in this example):\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"publish\\\",\\\"revision\\\":3}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Omitting \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" selects the saved draft, even when a background job has\\na newer preview. MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"publish-a-working-preview\",\n children: \"Publish a working preview\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To publish a specific working preview from a background generation, pass its\\ntoken as \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" and the site's current saved revision:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"publish\\\",\\\"revision\\\":3,\\\"generationToken\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP \", _jsx(_components.code, {\n children: \"publish_site\"\n }), \" uses the same fields plus \", _jsx(_components.code, {\n children: \"id\"\n }), \", without \", _jsx(_components.code, {\n children: \"action\"\n }), \". The token must\\nmatch the site and caller. The selected build must contain a completed playable\\nbuild step for the current site/workspace/revision; the whole generation job need\\nnot already be completed. A preview that is not ready returns 400, a stale build\\nreturns 409, and invalid or expired token access returns 404. A temporary saved-build\\nfailure may return 503. Without \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \", publication uses the saved draft;\\nit does not automatically select the newest background preview.\"]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"upgrade-required\",\n children: \"Upgrade required\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"An ineligible workspace receives HTTP 402 with an error body, for example:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"error\\\":\\\"An active paid Recoup subscription is required to publish a site. Subscribe in this site’s workspace, then publish again.\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Subscribe in the site's owning workspace before retrying the intended publish.\\nThis response does not publish the site or create a checkout session.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"unpublish\",\n children: \"Unpublish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" with the current revision to remove the public\\nsnapshot while retaining the draft. MCP \", _jsx(_components.code, {\n children: \"unpublish_site\"\n }), \" takes \", _jsx(_components.code, {\n children: \"id\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"unpublish\\\",\\\"revision\\\":3}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Agents should publish, unpublish or delete only when explicitly instructed.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"delete-and-cancel-generation\",\n children: \"Delete and cancel generation\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Delete only when explicitly instructed. Send \", _jsx(_components.code, {\n children: \"PATCH /api/sites/{id}\"\n }), \" with \", _jsx(_components.code, {\n children: \"action: \\\"delete\\\"\"\n }), \" and the current \", _jsx(_components.code, {\n children: \"revision\"\n }), \" in its JSON request body (Content-Type: application/json). Include \", _jsx(_components.code, {\n children: \"generationToken\"\n }), \" when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"For example, use the current saved revision and the token returned by a known generation:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\\"action\\\":\\\"delete\\\",\\\"revision\\\":3,\\\"generationToken\\\":\\\"TOKEN_FROM_GENERATION\\\"}\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Omit generationToken when no known generation needs cancellation.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Deletion checks workspace access and revision, then returns \", _jsx(_components.code, {\n children: \"{ \\\"deleted\\\": true, \\\"id\\\": \\\"...\\\" }\"\n }), \". A stale revision returns 409; reload before retrying. Unpublish with \", _jsx(_components.code, {\n children: \"action: \\\"unpublish\\\"\"\n }), \" when the draft should remain available.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"uploads\",\n children: \"Uploads\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"HTTP uploads are multipart forms with a \", _jsx(_components.code, {\n children: \"file\"\n }), \" field and optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP's \", _jsx(_components.code, {\n children: \"upload_site_asset\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"contentType\"\n }), \", \", _jsx(_components.code, {\n children: \"base64\"\n }), \" file bytes, and optional \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \". It uses the same validation and storage path as HTTP.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"public-endpoints\",\n children: \"Public endpoints\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{id}\"\n }), \" returns \", _jsx(_components.code, {\n children: \"{ snapshot: ... }\"\n }), \" for a published site only. Drafts, account identifiers, and signup data are excluded.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/signup\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{\\\"email\\\":\\\"fan@example.com\\\",\\\"consent\\\":\\\"yes\\\"}\"\n }), \". An optional \", _jsx(_components.code, {\n children: \"website\"\n }), \" honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Public pages and the browser music player render in the chat app. The API provides\\nsnapshots, generation, uploads, signup persistence and the fan-connection integration\\nroutes listed below.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"route-coverage\",\n children: \"Route coverage\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"The lifecycle and public snapshot/signup operations above are documented here in\\nprose; they are not a complete Sites OpenAPI specification. The following existing\\nroutes are accounted for as integration surfaces, outside the copyable lifecycle\\nexamples. Listing them does not establish live authorization or add an MCP tool.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"authenticated-integration-routes\",\n children: \"Authenticated integration routes\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"Purpose\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/fan-connection\"\n })\n }), _jsx(_components.td, {\n children: \"Read fan-connection configuration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"PUT /api/sites/{id}/fan-connection\"\n })\n }), _jsx(_components.td, {\n children: \"Configure the fan connection through the authenticated integration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/fans\"\n })\n }), _jsx(_components.td, {\n children: \"Fan reporting\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/{id}/activity\"\n })\n }), _jsx(_components.td, {\n children: \"Activity reporting\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.h3, {\n id: \"browser-integration-routes\",\n children: \"Browser integration routes\"\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"HTTP\"\n }), _jsx(_components.th, {\n children: \"Purpose\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/apple/config\"\n })\n }), _jsx(_components.td, {\n children: \"Browser music configuration\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/activity\"\n })\n }), _jsx(_components.td, {\n children: \"Published-site activity collection\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"GET /api/sites/public/{id}/spotify\"\n })\n }), _jsx(_components.td, {\n children: \"Show the fan-connection acceptance page\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"POST /api/sites/public/{id}/spotify\"\n })\n }), _jsx(_components.td, {\n children: \"Begin Spotify authorization after acceptance\"\n })]\n })]\n })]\n }), \"\\n\", _jsx(_components.p, {\n children: \"These browser flows are not replacements for a private lifecycle request or proof\\nof a completed fan connection. Email signup and Spotify connection are distinct.\"\n }), \"\\n\", _jsx(_components.h3, {\n id: \"provider-callback\",\n children: \"Provider callback\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/spotify/callback\"\n }), \" completes the provider redirect flow. It is\\nintentionally excluded from agent lifecycle examples; do not invoke it as a\\nstandalone operation. OPTIONS preflight handlers are also excluded from the\\noperation tables because they serve browser CORS negotiation.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"errors\",\n children: \"Errors\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"402\"\n }), \": publication requires an eligible paid workspace.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"400\"\n }), \" invalid input; \", _jsx(_components.code, {\n children: \"401\"\n }), \" missing/invalid authentication; \", _jsx(_components.code, {\n children: \"403\"\n }), \" workspace or artist access denied; \", _jsx(_components.code, {\n children: \"404\"\n }), \" missing/unpublished site; \", _jsx(_components.code, {\n children: \"409\"\n }), \" stale revision; \", _jsx(_components.code, {\n children: \"422\"\n }), \" Spotify metadata unavailable; \", _jsx(_components.code, {\n children: \"503\"\n }), \" temporary operation failure.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Sites Create, generate, and publish fan experiences through the API or MCP. Sites Sites Sites uses the same backend operations from the web app, HTTP API, and MCP. A new site is a **private draft**. Generation never publishes it automatically. ## Authentication Private HTTP endpoints accept exactly one of `x-api-key: YOUR_API_KEY` or `Authorization: Bearer YOUR_PRIVY_ACCESS_TOKEN`. MCP uses the existing authenticated `https://api.recoupable.dev/mcp` connection. The caller is derived from authentication. Do not send an `account_id`. An optional `organizationId` selects a workspace the caller can access. Omit it for the authenticated account's workspace. ## Endpoints and tools | HTTP | MCP tool | Result | | --- | --- | --- | | `GET /api/sites` | `list_sites` | `{ sites: [...] }` | | `POST /api/sites` | `create_site` | `{ site: ... }`, HTTP 201 | | `GET /api/sites/{id}` | `get_site` | `{ site: ... }` | | `PATCH /api/sites/{id}` action `concepts` | `propose_site_concepts` | Short pitches or missing context | | `PATCH /api/sites/{id}` action `generate` | `generate_site` | Generate from an optional customer-selected pitch; otherwise select a concept | | `PATCH /api/sites/{id}` action `generation` | `get_site_generation` | Status for the specified generation token | | `PATCH /api/sites/{id}` action `publish` | `publish_site` | Publish the saved draft or the playable build selected by `generationToken` | | `PATCH /api/sites/{id}` action `unpublish` | `unpublish_site` | Public snapshot removed, draft retained | | `PATCH /api/sites/{id}` action `delete` | `delete_site` | `{ \"deleted\": true, \"id\": \"...\" }` | | `GET /api/sites/{id}/signups` | `get_site_signups` | `{ signups: [{ email, created_at }] }`, up to 10,000 | | `POST /api/sites/assets` | `upload_site_asset` | `{ asset: { url, name, type } }` | Listing accepts optional `organizationId` and `artistId` query parameters. All private reads and writes verify workspace access. Signup emails are never part of the public response. ## Create and generate Create a draft with a Spotify track, album, or playlist URL. Recoup retrieves its title and artwork. The brief is optional; without it, Recoup uses the available song and artist context to propose activities. Alternatively, supply both a name and a brief without a release URL. Optional creation fields: `name` (120 characters), `brief` (6,000), `organizationId`, `artistId`, and `assets` (up to eight workspace-owned assets returned by the upload endpoint). An artist must be accessible to the caller and belong to the selected organization when one is used. Read `site.id` and `site.revision`, then start automatic generation: For Spotify tracks, the background workflow saves metadata, acquires and verifies full audio, saves Music Flamingo lyrics and musical analysis, collects artwork observations and public artist research, compiles a saved brief, selects a concept, and builds and reviews the site. No separate collector calls are required. Audio acquisition requires a Spotify preview for waveform verification and stops if no matching full recording is found. Completed accepted context is reused. To choose a concept yourself before generation, optionally request pitches: Send this to `PATCH /api/sites/{id}`, or call MCP `propose_site_concepts` with `id` and `revision`. Optional `instruction` and `contextBriefId` apply to pitching too. This can use credits for context collection and a pitch call, but does not create images, site code or change the draft. The response is `{ concepts: { status, candidates, reason }, revision }`. Status is `ready`, `needs-context`, or `no-good-concept`. Metadata and cover details alone return `needs-context`; provide usable song analysis or sourced artist context rather than forcing an activity out of the artwork. In the explicit-selection flow, show the short pitches to the customer and wait for their choice. Each candidate contains `name`, `activity`, `fanMotivation`, `songOrArtistConnection`, and `friendHook`. Pass the selected object unchanged as `approvedConcept`: MCP `generate_site` accepts the same fields plus `id`, without `action`. A customer-authored concept is also accepted. The optional `approvedConcept` preserves a caller-selected activity. When omitted, the engine selects from its proposed concepts after collecting context. Generation defaults to background execution and returns a generation token; poll `get_site_generation` (HTTP action `generation`) for the result. Set `background: false` only for a synchronous client that supports a long timeout. If review rejects the concept, the draft is marked `needs-review`; the system does not silently substitute a new activity. Asset and implementation repairs retain their bounded pass. Generation failures identify the stopped stage and leave the saved draft unchanged. A `409` means another edit changed the revision; read the site again before retrying. ### Poll background generation Send this JSON body to `PATCH /api/sites/{id}` using the token returned by the generation request. MCP `get_site_generation` takes `id` and `token`, without `action`. Polling uses `token`; publishing and cancellation use `generationToken`. The token is bound to its site and caller and expires. Invalid, expired or mismatched tokens return 404 during token verification; a missing or empty token is invalid input (400). A running job is not proof that a playable build or a published page exists; read the returned status and progress. ## Generate from saved Context Engine evidence Save a single-song `creative_direction` brief using the Context Engine `save_brief` action, then pass its snapshot ID when requesting pitches: Pass the same `contextBriefId` with the selected `approvedConcept` to generation. It is available on both MCP `propose_site_concepts` and `generate_site`. Without a saved brief, track generation automatically collects and saves context, reusing compatible accepted module results. The brief must belong to the site's workspace and match its Spotify track. Sites rejects unavailable or superseded snapshots before generation. Revisions reuse the draft's selected brief unless a new ID is supplied. This path reuses accepted song summaries, artwork observations, public artist research and release/artist metadata instead of collecting them again. The creative director and generator receive attribution, coverage and missing-topic information. Supported evidence includes public Spotify metadata/artwork, YouTube-attributed audio analysis and saved public-search research. Private uploads, customer assertions and raw lyrics are excluded. Matching saved machine transcripts inform paraphrased themes but are not forwarded to the site. Partial evidence stays partial. Generation still uses credits for creative direction, assets, implementation and review. It saves a private draft, never publishes automatically. Snapshot availability is checked again before saving and publishing. Later source withdrawal does not automatically retract an already published site. Internal evidence and source identifiers are excluded from the public site response. ## Publish After reviewing the intended draft or preview, publish through the same PATCH endpoint or MCP `publish_site`, using the site's current saved revision. Publishing automatically prepares Spotify fan connection for an active paid workspace. The standard agreement uses the attributed artist's name; the customer does not need a separate setup step. Missing artist attribution or unavailable Spotify configuration stops paid publication with an actionable error. Publication requires an eligible paid workspace. The gate checks the site's owning workspace for an active subscription with a positive-priced item; a trial or Pro entitlement alone does not establish eligibility. Unpaid publication returns HTTP 402 before publishing. Successful paid setup reports `fanConnection: \"enabled\"`. For a custom hosted destination, HTTP callers may include `returnUrl` (an HTTPS URL without credentials or fragment) in the publish body. Otherwise an existing connection destination is preserved, or the configured Sites public origin is used. The Recoup editor supplies its actual published URL. The authenticated fan-connection API remains available for external integrations. The public page is `https://chat.recoupable.dev/s/{id}`. ### Publish the saved draft Use the current revision from the saved site (3 in this example): Omitting `generationToken` selects the saved draft, even when a background job has a newer preview. MCP `publish_site` takes `id` and `revision`, without `action`. ### Publish a working preview To publish a specific working preview from a background generation, pass its token as `generationToken` and the site's current saved revision: MCP `publish_site` uses the same fields plus `id`, without `action`. The token must match the site and caller. The selected build must contain a completed playable build step for the current site/workspace/revision; the whole generation job need not already be completed. A preview that is not ready returns 400, a stale build returns 409, and invalid or expired token access returns 404. A temporary saved-build failure may return 503. Without `generationToken`, publication uses the saved draft; it does not automatically select the newest background preview. ### Upgrade required An ineligible workspace receives HTTP 402 with an error body, for example: Subscribe in the site's owning workspace before retrying the intended publish. This response does not publish the site or create a checkout session. ### Unpublish Send `PATCH /api/sites/{id}` with the current revision to remove the public snapshot while retaining the draft. MCP `unpublish_site` takes `id` and `revision`. Agents should publish, unpublish or delete only when explicitly instructed. ## Delete and cancel generation Delete only when explicitly instructed. Send `PATCH /api/sites/{id}` with `action: \"delete\"` and the current `revision` in its JSON request body (Content-Type: application/json). Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job. For example, use the current saved revision and the token returned by a known generation: Omit generationToken when no known generation needs cancellation. Deletion checks workspace access and revision, then returns `{ \"deleted\": true, \"id\": \"...\" }`. A stale revision returns 409; reload before retrying. Unpublish with `action: \"unpublish\"` when the draft should remain available. ## Uploads HTTP uploads are multipart forms with a `file` field and optional `organizationId` query parameter. Supported formats: JPEG, PNG, WebP, MP3, and WAV, up to 4 MB per file. Images are re-encoded to WebP. Audio is checked for its file signature. MCP's `upload_site_asset` accepts `name`, `contentType`, `base64` file bytes, and optional `organizationId`. It uses the same validation and storage path as HTTP. ## Public endpoints - `GET /api/sites/public/{id}` returns `{ snapshot: ... }` for a published site only. Drafts, account identifiers, and signup data are excluded. - `POST /api/sites/public/{id}/signup` accepts `{\"email\":\"fan@example.com\",\"consent\":\"yes\"}`. An optional `website` honeypot must be empty. Duplicate submissions succeed without disclosing list membership. Unpublished sites reject signups. Public pages and the browser music player render in the chat app. The API provides snapshots, generation, uploads, signup persistence and the fan-connection integration routes listed below. ## Route coverage The lifecycle and public snapshot/signup operations above are documented here in prose; they are not a complete Sites OpenAPI specification. The following existing routes are accounted for as integration surfaces, outside the copyable lifecycle examples. Listing them does not establish live authorization or add an MCP tool. ### Authenticated integration routes | HTTP | Purpose | | --- | --- | | `GET /api/sites/{id}/fan-connection` | Read fan-connection configuration | | `PUT /api/sites/{id}/fan-connection` | Configure the fan connection through the authenticated integration | | `GET /api/sites/{id}/fans` | Fan reporting | | `GET /api/sites/{id}/activity` | Activity reporting | ### Browser integration routes | HTTP | Purpose | | --- | --- | | `GET /api/sites/apple/config` | Browser music configuration | | `POST /api/sites/public/{id}/activity` | Published-site activity collection | | `GET /api/sites/public/{id}/spotify` | Show the fan-connection acceptance page | | `POST /api/sites/public/{id}/spotify` | Begin Spotify authorization after acceptance | These browser flows are not replacements for a private lifecycle request or proof of a completed fan connection. Email signup and Spotify connection are distinct. ### Provider callback `GET /api/sites/spotify/callback` completes the provider redirect flow. It is intentionally excluded from agent lifecycle examples; do not invoke it as a standalone operation. OPTIONS preflight handlers are also excluded from the operation tables because they serve browser CORS negotiation. ## Errors - `402`: publication requires an eligible paid workspace. `400` invalid input; `401` missing/invalid authentication; `403` workspace or artist access denied; `404` missing/unpublished site; `409` stale revision; `422` Spotify metadata unavailable; `503` temporary operation failure. "},{"slug":"essentials/site-fan-connection","title":"Connect Spotify fans to a site","description":"Configure paid fan connection from an artist agent and retrieve fans attributed to its site.","category":"Sites","group":"Sites","source":"essentials/site-fan-connection.mdx","body":"Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: `https://api.recoupable.dev`.\n\nPrivate calls use `x-api-key: $RECOUP_API_KEY` (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key.\n\n## Customer and site\n\n- `GET /api/accounts/id`: verify the current credential.\n- `POST /api/agents/signup` with `{ \"email\": \"customer@example.com\" }`: request email verification.\n- `POST /api/agents/verify` with `{ \"email\": \"customer@example.com\", \"code\": \"123456\" }`: receive `api_key`; never echo it.\n- `GET /api/artists`: inspect the caller's roster and choose the artist's account ID.\n- `GET /api/sites`: inspect existing site records.\n- `POST /api/sites` with `{ \"name\": \"Release experience\", \"artistId\": \"ARTIST_ACCOUNT_UUID\", \"releaseUrl\": \"https://open.spotify.com/track/TRACK_ID\" }`: register a site. Add `organizationId` only for a selected authorized workspace. Read the returned `site.id`. Omit owner/account ID fields; ownership comes from authentication.\n\n## Configure\n\n`GET /api/sites/{siteId}/fan-connection` returns:\n\n```json\n{\n \"siteId\": \"SITE_UUID\",\n \"ownerId\": \"WORKSPACE_ACCOUNT_UUID\",\n \"artistId\": \"ARTIST_ACCOUNT_UUID\",\n \"config\": null,\n \"connectUrl\": null\n}\n```\n\nExisting `config` contains `site_id`, `return_url`, `marketing_text`, `enabled` and `revision`. Update with `PUT /api/sites/{siteId}/fan-connection`:\n\n```json\n{\n \"returnUrl\": \"https://artist.example/release\",\n \"marketingText\": \"I agree to receive release announcements and offers by email from Example Artist.\",\n \"enabled\": true,\n \"revision\": 0\n}\n```\n\nUse the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public `connectUrl`; always use that returned URL.\n\n- 400: invalid input or missing artist attribution.\n- 401/403: reconnect the customer or select an authorized workspace.\n- 402: no eligible paid subscription for the site's owning account.\n- 404: missing site or API not deployed; inspect the actual response.\n- 409: another configuration update won; reload and reconcile before retry.\n- 503: provider, billing or storage unavailable; surface the dependency.\n\nSpotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing `POST /api/subscriptions/sessions` accepts `{plan: \"starter\" | \"pro\", successUrl, cancelUrl?}` and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature.\n\n## Public fan journey\n\n`GET /api/sites/public/{siteId}/spotify` displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's `/api/sites/spotify/callback`; Recoup then returns to the configured site URL with `recoup_spotify=connected`, `cancelled` or `failed`.\n\nOnly a successful provider exchange with `user-read-email` and `user-read-private` creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site.\n\n## Read fans\n\n`GET /api/sites/{siteId}/fans?offset=0&limit=50` (private):\n\n```json\n{\n \"fans\": [],\n \"total\": 0,\n \"offset\": 0,\n \"limit\": 50\n}\n```\n\nEach fan has `id`, `site_id`, `spotify_id`, `display_name`, `email`, first/last connection timestamps and nested `site_fan_connections` with `site_fan_permissions` and `site_fan_marketing_consents`. Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data.\n\nStarter Checkout can return HTTP 400 `starter_unavailable` when its price is not\nconfigured. Explain the unavailable option and use a configured plan; do not retry\nit as a transient provider failure.\n\n## Recoup operator setup\n\nOperators must apply `20260928010000_site_fan_connections.sql`, configure `SITES_SPOTIFY_CLIENT_ID`, register an HTTPS callback ending `/api/sites/spotify/callback`, set `SITES_FAN_SPOTIFY_REDIRECT_URI`. This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate.\n\n## Activity reporting\n\n`GET /api/sites/{siteId}/activity` returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. `POST /api/sites/public/{siteId}/activity` accepts `{id: EVENT_UUID, visitId: VISIT_UUID, event: \"visit\" | \"start\" | \"complete\" | \"replay\" | \"share\"}`. Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history.\n\nRecoup-hosted generated sites use the trusted host bridge: `window.recoup.track(event)` reports approved events; `window.recoup.join()` reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server.\n\n## Playback for Premium and Free listeners\n\nThe hosted player reads the connected Spotify profile's `product` field. Premium listeners use the Spotify Web Playback SDK. Free (`free` or `open`) listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording.\n\n`GET /api/sites/public/{siteId}` includes `playbackAudioUrl`, a fresh signed audio URL valid for one hour, or `null` when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans.\n\nFile playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable.\n","headings":[{"title":"Customer and site","id":"customer-and-site"},{"title":"Configure","id":"configure"},{"title":"Public fan journey","id":"public-fan-journey"},{"title":"Read fans","id":"read-fans"},{"title":"Recoup operator setup","id":"recoup-operator-setup"},{"title":"Activity reporting","id":"activity-reporting"},{"title":"Playback for Premium and Free listeners","id":"playback-for-premium-and-free-listeners"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: \", _jsx(_components.code, {\n children: \"https://api.recoupable.dev\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Private calls use \", _jsx(_components.code, {\n children: \"x-api-key: $RECOUP_API_KEY\"\n }), \" (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"customer-and-site\",\n children: \"Customer and site\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/accounts/id\"\n }), \": verify the current credential.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/agents/signup\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"email\\\": \\\"customer@example.com\\\" }\"\n }), \": request email verification.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/agents/verify\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"email\\\": \\\"customer@example.com\\\", \\\"code\\\": \\\"123456\\\" }\"\n }), \": receive \", _jsx(_components.code, {\n children: \"api_key\"\n }), \"; never echo it.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/artists\"\n }), \": inspect the caller's roster and choose the artist's account ID.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites\"\n }), \": inspect existing site records.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"POST /api/sites\"\n }), \" with \", _jsx(_components.code, {\n children: \"{ \\\"name\\\": \\\"Release experience\\\", \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\", \\\"releaseUrl\\\": \\\"https://open.spotify.com/track/TRACK_ID\\\" }\"\n }), \": register a site. Add \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" only for a selected authorized workspace. Read the returned \", _jsx(_components.code, {\n children: \"site.id\"\n }), \". Omit owner/account ID fields; ownership comes from authentication.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"configure\",\n children: \"Configure\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/fan-connection\"\n }), \" returns:\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"siteId\\\": \\\"SITE_UUID\\\",\\n \\\"ownerId\\\": \\\"WORKSPACE_ACCOUNT_UUID\\\",\\n \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\",\\n \\\"config\\\": null,\\n \\\"connectUrl\\\": null\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Existing \", _jsx(_components.code, {\n children: \"config\"\n }), \" contains \", _jsx(_components.code, {\n children: \"site_id\"\n }), \", \", _jsx(_components.code, {\n children: \"return_url\"\n }), \", \", _jsx(_components.code, {\n children: \"marketing_text\"\n }), \", \", _jsx(_components.code, {\n children: \"enabled\"\n }), \" and \", _jsx(_components.code, {\n children: \"revision\"\n }), \". Update with \", _jsx(_components.code, {\n children: \"PUT /api/sites/{siteId}/fan-connection\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"returnUrl\\\": \\\"https://artist.example/release\\\",\\n \\\"marketingText\\\": \\\"I agree to receive release announcements and offers by email from Example Artist.\\\",\\n \\\"enabled\\\": true,\\n \\\"revision\\\": 0\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public \", _jsx(_components.code, {\n children: \"connectUrl\"\n }), \"; always use that returned URL.\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"400: invalid input or missing artist attribution.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"401/403: reconnect the customer or select an authorized workspace.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"402: no eligible paid subscription for the site's owning account.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"404: missing site or API not deployed; inspect the actual response.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"409: another configuration update won; reload and reconcile before retry.\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"503: provider, billing or storage unavailable; surface the dependency.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Spotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing \", _jsx(_components.code, {\n children: \"POST /api/subscriptions/sessions\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{plan: \\\"starter\\\" | \\\"pro\\\", successUrl, cancelUrl?}\"\n }), \" and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"public-fan-journey\",\n children: \"Public fan journey\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{siteId}/spotify\"\n }), \" displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's \", _jsx(_components.code, {\n children: \"/api/sites/spotify/callback\"\n }), \"; Recoup then returns to the configured site URL with \", _jsx(_components.code, {\n children: \"recoup_spotify=connected\"\n }), \", \", _jsx(_components.code, {\n children: \"cancelled\"\n }), \" or \", _jsx(_components.code, {\n children: \"failed\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Only a successful provider exchange with \", _jsx(_components.code, {\n children: \"user-read-email\"\n }), \" and \", _jsx(_components.code, {\n children: \"user-read-private\"\n }), \" creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"read-fans\",\n children: \"Read fans\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/fans?offset=0&limit=50\"\n }), \" (private):\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"fans\\\": [],\\n \\\"total\\\": 0,\\n \\\"offset\\\": 0,\\n \\\"limit\\\": 50\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each fan has \", _jsx(_components.code, {\n children: \"id\"\n }), \", \", _jsx(_components.code, {\n children: \"site_id\"\n }), \", \", _jsx(_components.code, {\n children: \"spotify_id\"\n }), \", \", _jsx(_components.code, {\n children: \"display_name\"\n }), \", \", _jsx(_components.code, {\n children: \"email\"\n }), \", first/last connection timestamps and nested \", _jsx(_components.code, {\n children: \"site_fan_connections\"\n }), \" with \", _jsx(_components.code, {\n children: \"site_fan_permissions\"\n }), \" and \", _jsx(_components.code, {\n children: \"site_fan_marketing_consents\"\n }), \". Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Starter Checkout can return HTTP 400 \", _jsx(_components.code, {\n children: \"starter_unavailable\"\n }), \" when its price is not\\nconfigured. Explain the unavailable option and use a configured plan; do not retry\\nit as a transient provider failure.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"recoup-operator-setup\",\n children: \"Recoup operator setup\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Operators must apply \", _jsx(_components.code, {\n children: \"20260928010000_site_fan_connections.sql\"\n }), \", configure \", _jsx(_components.code, {\n children: \"SITES_SPOTIFY_CLIENT_ID\"\n }), \", register an HTTPS callback ending \", _jsx(_components.code, {\n children: \"/api/sites/spotify/callback\"\n }), \", set \", _jsx(_components.code, {\n children: \"SITES_FAN_SPOTIFY_REDIRECT_URI\"\n }), \". This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"activity-reporting\",\n children: \"Activity reporting\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/{siteId}/activity\"\n }), \" returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. \", _jsx(_components.code, {\n children: \"POST /api/sites/public/{siteId}/activity\"\n }), \" accepts \", _jsx(_components.code, {\n children: \"{id: EVENT_UUID, visitId: VISIT_UUID, event: \\\"visit\\\" | \\\"start\\\" | \\\"complete\\\" | \\\"replay\\\" | \\\"share\\\"}\"\n }), \". Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Recoup-hosted generated sites use the trusted host bridge: \", _jsx(_components.code, {\n children: \"window.recoup.track(event)\"\n }), \" reports approved events; \", _jsx(_components.code, {\n children: \"window.recoup.join()\"\n }), \" reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"playback-for-premium-and-free-listeners\",\n children: \"Playback for Premium and Free listeners\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The hosted player reads the connected Spotify profile's \", _jsx(_components.code, {\n children: \"product\"\n }), \" field. Premium listeners use the Spotify Web Playback SDK. Free (\", _jsx(_components.code, {\n children: \"free\"\n }), \" or \", _jsx(_components.code, {\n children: \"open\"\n }), \") listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"GET /api/sites/public/{siteId}\"\n }), \" includes \", _jsx(_components.code, {\n children: \"playbackAudioUrl\"\n }), \", a fresh signed audio URL valid for one hour, or \", _jsx(_components.code, {\n children: \"null\"\n }), \" when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"File playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"Connect Spotify fans to a site Configure paid fan connection from an artist agent and retrieve fans attributed to its site. Sites Sites Release dependency: these routes require the site fan connection API release and its database migration. The skill alone does not enable them. Base URL: `https://api.recoupable.dev`. Private calls use `x-api-key: $RECOUP_API_KEY` (or the platform's existing bearer authentication). Customer credentials stay with the agent/server. Public connection entry and callback use browser-bound OAuth state, not the customer API key. ## Customer and site - `GET /api/accounts/id`: verify the current credential. - `POST /api/agents/signup` with `{ \"email\": \"customer@example.com\" }`: request email verification. - `POST /api/agents/verify` with `{ \"email\": \"customer@example.com\", \"code\": \"123456\" }`: receive `api_key`; never echo it. - `GET /api/artists`: inspect the caller's roster and choose the artist's account ID. - `GET /api/sites`: inspect existing site records. - `POST /api/sites` with `{ \"name\": \"Release experience\", \"artistId\": \"ARTIST_ACCOUNT_UUID\", \"releaseUrl\": \"https://open.spotify.com/track/TRACK_ID\" }`: register a site. Add `organizationId` only for a selected authorized workspace. Read the returned `site.id`. Omit owner/account ID fields; ownership comes from authentication. ## Configure `GET /api/sites/{siteId}/fan-connection` returns: Existing `config` contains `site_id`, `return_url`, `marketing_text`, `enabled` and `revision`. Update with `PUT /api/sites/{siteId}/fan-connection`: Use the real artist's approved text, not the example unchanged. Return URL must be HTTPS, at most 2048 characters, without credentials or fragments. Text length is 20–1000 characters. Pass the last read revision, or 0 for initial configuration. The response has the same envelope with persisted config and the public `connectUrl`; always use that returned URL. - 400: invalid input or missing artist attribution. - 401/403: reconnect the customer or select an authorized workspace. - 402: no eligible paid subscription for the site's owning account. - 404: missing site or API not deployed; inspect the actual response. - 409: another configuration update won; reload and reconcile before retry. - 503: provider, billing or storage unavailable; surface the dependency. Spotify fan connection is included in an active paid Recoup subscription owned by the site's workspace. No separate add-on is required. Existing `POST /api/subscriptions/sessions` accepts `{plan: \"starter\" | \"pro\", successUrl, cancelUrl?}` and returns the customer checkout URL. Let the customer complete payment; then retry activation. Fans do not buy this feature. ## Public fan journey `GET /api/sites/public/{siteId}/spotify` displays the site's agreement. Its own form POST binds acceptance to that browser and configuration revision, then redirects to Spotify PKCE authorization. Do not handcraft this POST or bypass the page. Spotify returns to Recoup's `/api/sites/spotify/callback`; Recoup then returns to the configured site URL with `recoup_spotify=connected`, `cancelled` or `failed`. Only a successful provider exchange with `user-read-email` and `user-read-private` creates records. Actual granted scopes and the exact accepted marketing text are retained separately from the successful connection. Email may be absent. No tokens or profile details are passed to the public site. ## Read fans `GET /api/sites/{siteId}/fans?offset=0&limit=50` (private): Each fan has `id`, `site_id`, `spotify_id`, `display_name`, `email`, first/last connection timestamps and nested `site_fan_connections` with `site_fan_permissions` and `site_fan_marketing_consents`. Paginate up to 100 fans per page. Records are private to authorized workspace members. Read access remains available after paid eligibility expires. Repeated connection updates the existing fan for that site and adds a connection history entry. The site's owner and artist supply attribution. These records are separate from email-only signups and other artist audience data. Starter Checkout can return HTTP 400 `starter_unavailable` when its price is not configured. Explain the unavailable option and use a configured plan; do not retry it as a transient provider failure. ## Recoup operator setup Operators must apply `20260928010000_site_fan_connections.sql`, configure `SITES_SPOTIFY_CLIENT_ID`, register an HTTPS callback ending `/api/sites/spotify/callback`, set `SITES_FAN_SPOTIFY_REDIRECT_URI`. This is Recoup service configuration, not work to impose on each artist. The existing browser playback callback remains separate. ## Activity reporting `GET /api/sites/{siteId}/activity` returns 30-day counts for visits, starts, completions, replays and shares to authorized workspace members. `POST /api/sites/public/{siteId}/activity` accepts `{id: EVENT_UUID, visitId: VISIT_UUID, event: \"visit\" | \"start\" | \"complete\" | \"replay\" | \"share\"}`. Reuse the event UUID when retrying. Use a site-scoped visit ID. Never send emails, profile data or arbitrary page contents to this endpoint. These are browser-reported interactions, not verified Spotify listening or a named fan activity history. Recoup-hosted generated sites use the trusted host bridge: `window.recoup.track(event)` reports approved events; `window.recoup.join()` reveals the trusted signup controls. External sites should implement the equivalent fixed-event transport and keep account credentials on the server. ## Playback for Premium and Free listeners The hosted player reads the connected Spotify profile's `product` field. Premium listeners use the Spotify Web Playback SDK. Free (`free` or `open`) listeners use the site's saved, verified recording through the same play/pause, seek and volume controls. If the profile cannot be read, its subscription remains unknown; available artist audio keeps playback usable. The player also handles a Spotify SDK account rejection by switching to the recording. `GET /api/sites/public/{siteId}` includes `playbackAudioUrl`, a fresh signed audio URL valid for one hour, or `null` when no matching verified recording is available. It is resolved from the published site's workspace-owned context request and matching Spotify track; private research and analysis are excluded. Fetch a fresh public response when reloading rather than storing this URL permanently. Publish only audio you have permission to serve to fans. File playback is not a Spotify stream. Spotify playback subscription, Recoup's paid fan-connection entitlement, and fan capture are separate concerns. A missing audio file must show an honest unavailable state while keeping the game playable. "},{"slug":"essentials/release-player","title":"One player for every release","description":"Create a listening page or embed Spotify and Apple Music playback on your artist website.","category":"Players","group":"Release players","source":"essentials/release-player.mdx","body":"Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.\n\n## Create and publish\n\nUse the [Recoup API](/api-reference/players/create) or the `create_release_player` MCP tool. Choose an artist you can access, name the player, and provide a `spotifyUrl`, an `appleUrl`, or both. Use `organizationId` to create it in your organization workspace.\n\nFor website embeds, add the exact website origins to `allowedOrigins`. An origin includes the scheme, hostname and any non-default port, such as `https://artist.example:8443`. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.\n\nExample create request:\n\n```json\n{\n \"artistId\": \"ARTIST_ACCOUNT_UUID\",\n \"organizationId\": \"ORGANIZATION_UUID\",\n \"name\": \"Release title\",\n \"spotifyUrl\": \"https://open.spotify.com/album/ALBUM_ID\",\n \"appleUrl\": \"https://music.apple.com/us/album/release/APPLE_ID\",\n \"allowedOrigins\": [\"https://artist.example\", \"https://www.artist.example\"]\n}\n```\n\nNew players start unpublished. Review the music links, then publish with `update_release_player`, passing `id`, the current `revision`, and `enabled: true`. Publishing requires an active paid Recoup workspace.\n\nUse the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.\n\nSee [update a release player](/api-reference/players/update) for the REST request and fields.\n\n## Share a listening page\n\nUse the returned `listenUrl` as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.\n\nTo track campaign traffic, add `source`, `medium`, `campaign`, and `content` query parameters. The listening page also accepts `utm_source`, `utm_medium`, `utm_campaign`, and `utm_content`. Use campaign labels, such as `instagram` and `release`; keep personal information out of links.\n\n## Embed on your website\n\nUse the returned `spotifyEmbedUrl` or `appleEmbedUrl` for each configured service. The `parent` parameter must match an approved website origin.\n\n```html\n\n```\n\nKeep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.\n\nFor Spotify Free handoffs, the embed sends a `recoup:open-dsp` message with `provider: \"spotify\"`. Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.\n\n## What fans can play\n\nSpotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.\n\nSpotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.\n\nApple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.\n\n## Optional uploaded audio for Spotify Free fans\n\nYou can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set `freePlayback: \"audio\"` and provide `audioUrl`. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.\n\nUpload an MP3 or WAV through `POST /api/sites/assets` in the same workspace, then use the returned `asset.url`. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.\n\nMCP arguments for `update_release_player`:\n\n```json\n{\n \"id\": \"PLAYER_UUID\",\n \"revision\": 1,\n \"freePlayback\": \"audio\",\n \"audioUrl\": \"WORKSPACE_UPLOADED_ASSET_URL\"\n}\n```\n\nFor REST, send `PATCH /api/players/PLAYER_UUID` with the same body except `id`; the player ID belongs in the URL.\n\nAudio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.\n\nTo restore the Spotify handoff, set `freePlayback: \"spotify\"`. You can also clear `audioUrl` by setting it to `null`.\n\n## Fan contacts belong to your workspace\n\nSpotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.\n\nIf that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.\n\n- Use `get_workspace_player_fans` or [read workspace player fans](/api-reference/players/workspace-fans) to list contacts and their artist relationships.\n- Use `get_release_player_fans` or [read artist player fans](/api-reference/players/fans) to list fan relationships across that artist's players in the workspace.\n\n`contact_id` identifies the workspace contact. Each artist relationship has its own `id`; activity records refer to that relationship as `fan_id`.\n\nSpotify sign-in does **not** grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.\n\n## Measure listening activity\n\nUse `get_release_player_activity` or [read listening activity](/api-reference/players/activity) for 30-day campaign totals and individual track, play, pause and skip events.\n\nThese reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are **not confirmed music-service stream counts** and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.\n\n## Check your fan journey\n\nBefore promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.\n","headings":[{"title":"Create and publish","id":"create-and-publish"},{"title":"Share a listening page","id":"share-a-listening-page"},{"title":"Embed on your website","id":"embed-on-your-website"},{"title":"What fans can play","id":"what-fans-can-play"},{"title":"Optional uploaded audio for Spotify Free fans","id":"optional-uploaded-audio-for-spotify-free-fans"},{"title":"Fan contacts belong to your workspace","id":"fan-contacts-belong-to-your-workspace"},{"title":"Measure listening activity","id":"measure-listening-activity"},{"title":"Check your fan journey","id":"check-your-fan-journey"}],"compiled":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n h2: \"h2\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n strong: \"strong\",\n ul: \"ul\",\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"create-and-publish\",\n children: \"Create and publish\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the \", _jsx(_components.a, {\n href: \"/api-reference/players/create\",\n children: \"Recoup API\"\n }), \" or the \", _jsx(_components.code, {\n children: \"create_release_player\"\n }), \" MCP tool. Choose an artist you can access, name the player, and provide a \", _jsx(_components.code, {\n children: \"spotifyUrl\"\n }), \", an \", _jsx(_components.code, {\n children: \"appleUrl\"\n }), \", or both. Use \", _jsx(_components.code, {\n children: \"organizationId\"\n }), \" to create it in your organization workspace.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For website embeds, add the exact website origins to \", _jsx(_components.code, {\n children: \"allowedOrigins\"\n }), \". An origin includes the scheme, hostname and any non-default port, such as \", _jsx(_components.code, {\n children: \"https://artist.example:8443\"\n }), \". Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Example create request:\"\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"artistId\\\": \\\"ARTIST_ACCOUNT_UUID\\\",\\n \\\"organizationId\\\": \\\"ORGANIZATION_UUID\\\",\\n \\\"name\\\": \\\"Release title\\\",\\n \\\"spotifyUrl\\\": \\\"https://open.spotify.com/album/ALBUM_ID\\\",\\n \\\"appleUrl\\\": \\\"https://music.apple.com/us/album/release/APPLE_ID\\\",\\n \\\"allowedOrigins\\\": [\\\"https://artist.example\\\", \\\"https://www.artist.example\\\"]\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"New players start unpublished. Review the music links, then publish with \", _jsx(_components.code, {\n children: \"update_release_player\"\n }), \", passing \", _jsx(_components.code, {\n children: \"id\"\n }), \", the current \", _jsx(_components.code, {\n children: \"revision\"\n }), \", and \", _jsx(_components.code, {\n children: \"enabled: true\"\n }), \". Publishing requires an active paid Recoup workspace.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"See \", _jsx(_components.a, {\n href: \"/api-reference/players/update\",\n children: \"update a release player\"\n }), \" for the REST request and fields.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"share-a-listening-page\",\n children: \"Share a listening page\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the returned \", _jsx(_components.code, {\n children: \"listenUrl\"\n }), \" as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To track campaign traffic, add \", _jsx(_components.code, {\n children: \"source\"\n }), \", \", _jsx(_components.code, {\n children: \"medium\"\n }), \", \", _jsx(_components.code, {\n children: \"campaign\"\n }), \", and \", _jsx(_components.code, {\n children: \"content\"\n }), \" query parameters. The listening page also accepts \", _jsx(_components.code, {\n children: \"utm_source\"\n }), \", \", _jsx(_components.code, {\n children: \"utm_medium\"\n }), \", \", _jsx(_components.code, {\n children: \"utm_campaign\"\n }), \", and \", _jsx(_components.code, {\n children: \"utm_content\"\n }), \". Use campaign labels, such as \", _jsx(_components.code, {\n children: \"instagram\"\n }), \" and \", _jsx(_components.code, {\n children: \"release\"\n }), \"; keep personal information out of links.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"embed-on-your-website\",\n children: \"Embed on your website\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use the returned \", _jsx(_components.code, {\n children: \"spotifyEmbedUrl\"\n }), \" or \", _jsx(_components.code, {\n children: \"appleEmbedUrl\"\n }), \" for each configured service. The \", _jsx(_components.code, {\n children: \"parent\"\n }), \" parameter must match an approved website origin.\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-html\",\n children: \"\\n\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For Spotify Free handoffs, the embed sends a \", _jsx(_components.code, {\n children: \"recoup:open-dsp\"\n }), \" message with \", _jsx(_components.code, {\n children: \"provider: \\\"spotify\\\"\"\n }), \". Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"what-fans-can-play\",\n children: \"What fans can play\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup.\"\n }), \"\\n\", _jsx(_components.h2, {\n id: \"optional-uploaded-audio-for-spotify-free-fans\",\n children: \"Optional uploaded audio for Spotify Free fans\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set \", _jsx(_components.code, {\n children: \"freePlayback: \\\"audio\\\"\"\n }), \" and provide \", _jsx(_components.code, {\n children: \"audioUrl\"\n }), \". This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Upload an MP3 or WAV through \", _jsx(_components.code, {\n children: \"POST /api/sites/assets\"\n }), \" in the same workspace, then use the returned \", _jsx(_components.code, {\n children: \"asset.url\"\n }), \". The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"MCP arguments for \", _jsx(_components.code, {\n children: \"update_release_player\"\n }), \":\"]\n }), \"\\n\", _jsx(_components.pre, {\n children: _jsx(_components.code, {\n className: \"language-json\",\n children: \"{\\n \\\"id\\\": \\\"PLAYER_UUID\\\",\\n \\\"revision\\\": 1,\\n \\\"freePlayback\\\": \\\"audio\\\",\\n \\\"audioUrl\\\": \\\"WORKSPACE_UPLOADED_ASSET_URL\\\"\\n}\\n\"\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"For REST, send \", _jsx(_components.code, {\n children: \"PATCH /api/players/PLAYER_UUID\"\n }), \" with the same body except \", _jsx(_components.code, {\n children: \"id\"\n }), \"; the player ID belongs in the URL.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To restore the Spotify handoff, set \", _jsx(_components.code, {\n children: \"freePlayback: \\\"spotify\\\"\"\n }), \". You can also clear \", _jsx(_components.code, {\n children: \"audioUrl\"\n }), \" by setting it to \", _jsx(_components.code, {\n children: \"null\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"fan-contacts-belong-to-your-workspace\",\n children: \"Fan contacts belong to your workspace\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans.\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_workspace_player_fans\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/workspace-fans\",\n children: \"read workspace player fans\"\n }), \" to list contacts and their artist relationships.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_release_player_fans\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/fans\",\n children: \"read artist player fans\"\n }), \" to list fan relationships across that artist's players in the workspace.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"contact_id\"\n }), \" identifies the workspace contact. Each artist relationship has its own \", _jsx(_components.code, {\n children: \"id\"\n }), \"; activity records refer to that relationship as \", _jsx(_components.code, {\n children: \"fan_id\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Spotify sign-in does \", _jsx(_components.strong, {\n children: \"not\"\n }), \" grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"measure-listening-activity\",\n children: \"Measure listening activity\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use \", _jsx(_components.code, {\n children: \"get_release_player_activity\"\n }), \" or \", _jsx(_components.a, {\n href: \"/api-reference/players/activity\",\n children: \"read listening activity\"\n }), \" for 30-day campaign totals and individual track, play, pause and skip events.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are \", _jsx(_components.strong, {\n children: \"not confirmed music-service stream counts\"\n }), \" and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance.\"]\n }), \"\\n\", _jsx(_components.h2, {\n id: \"check-your-fan-journey\",\n children: \"Check your fan journey\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || ({});\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","searchText":"One player for every release Create a listening page or embed Spotify and Apple Music playback on your artist website. Players Release players Create a player for a song, album or Spotify playlist. Share its listening page or embed it on your website. Recoup handles music-service sign-in, supported browser playback and fan activity reporting. ## Create and publish Use the [Recoup API](/api-reference/players/create) or the `create_release_player` MCP tool. Choose an artist you can access, name the player, and provide a `spotifyUrl`, an `appleUrl`, or both. Use `organizationId` to create it in your organization workspace. For website embeds, add the exact website origins to `allowedOrigins`. An origin includes the scheme, hostname and any non-default port, such as `https://artist.example:8443`. Embed origins must use HTTPS. Include both the www and non-www origins if fans can visit either. You can omit this field when sharing only the hosted listening page. Example create request: New players start unpublished. Review the music links, then publish with `update_release_player`, passing `id`, the current `revision`, and `enabled: true`. Publishing requires an active paid Recoup workspace. Use the same tool to change the music links, title, artwork or approved website origins. Pass the current revision returned by Recoup with each update. The player stays assigned to its original artist and workspace. Updating it ends existing player sessions, so fans may need to reconnect. See [update a release player](/api-reference/players/update) for the REST request and fields. ## Share a listening page Use the returned `listenUrl` as your bio or campaign link. No custom website is needed. Fans choose from the music services configured for that player. To track campaign traffic, add `source`, `medium`, `campaign`, and `content` query parameters. The listening page also accepts `utm_source`, `utm_medium`, `utm_campaign`, and `utm_content`. Use campaign labels, such as `instagram` and `release`; keep personal information out of links. ## Embed on your website Use the returned `spotifyEmbedUrl` or `appleEmbedUrl` for each configured service. The `parent` parameter must match an approved website origin. Keep music-service sign-in inside the Recoup player. Your website does not need Spotify or Apple credentials. Include a direct music-service link as a fallback when browser playback is unavailable. For Spotify Free handoffs, the embed sends a `recoup:open-dsp` message with `provider: \"spotify\"`. Your website must verify that the message comes from the Recoup player origin and that iframe's window, then open the Spotify destination configured for the player. Do not use a destination URL supplied by a message. ## What fans can play Spotify Premium fans can stream through the browser player after connecting. Spotify playlist players show a selectable song list and highlight the current song. Selecting a song starts playback at its position in the playlist. Unavailable entries cannot be selected. If the list fails to load, fans can retry or open the playlist in Spotify. Spotify Free fans are sent to the configured song, album or playlist in Spotify after connecting. Spotify controls whether that opens in its app or website and which playback options the fan has. If Recoup cannot confirm the account's subscription, it does not assume the account is Free. Apple Music playback uses the fan's Apple Music authorization and subscription. Apple sessions do not capture email or create an identified fan contact in Recoup. ## Optional uploaded audio for Spotify Free fans You can choose to let Spotify Free fans play an uploaded audio file in Recoup instead of sending them to Spotify. Set `freePlayback: \"audio\"` and provide `audioUrl`. This setting belongs to the player owner; fans cannot change it. Premium fans continue to stream from Spotify. Upload an MP3 or WAV through `POST /api/sites/assets` in the same workspace, then use the returned `asset.url`. The current upload limit is 4 MB. Audio mode requires a Spotify destination as a fallback. MCP arguments for `update_release_player`: For REST, send `PATCH /api/players/PLAYER_UUID` with the same body except `id`; the player ID belongs in the URL. Audio mode plays one uploaded file per player. It does not support an uploaded playlist or generate Spotify streams. Uploaded-file playback is excluded from the player's music-service playback reports; fan connections are still recorded. If the file is missing, fans are sent to Spotify. If it fails to load, the player offers an Open in Spotify link. To restore the Spotify handoff, set `freePlayback: \"spotify\"`. You can also clear `audioUrl` by setting it to `null`. ## Fan contacts belong to your workspace Spotify sign-in captures the profile information and email that Spotify makes available. A returning Spotify account reuses its contact in the same workspace. If that fan connects to another artist in your workspace, Recoup adds an artist relationship to the same contact. If they connect in another organization, that organization gets a separate contact. Your contact and listening history stay in your workspace. Matching names or email addresses alone do not merge fans. - Use `get_workspace_player_fans` or [read workspace player fans](/api-reference/players/workspace-fans) to list contacts and their artist relationships. - Use `get_release_player_fans` or [read artist player fans](/api-reference/players/fans) to list fan relationships across that artist's players in the workspace. `contact_id` identifies the workspace contact. Each artist relationship has its own `id`; activity records refer to that relationship as `fan_id`. Spotify sign-in does **not** grant email marketing consent. Use a separate, optional signup before sending marketing emails. Apple Music sessions remain anonymous and are not linked to Spotify contacts. ## Measure listening activity Use `get_release_player_activity` or [read listening activity](/api-reference/players/activity) for 30-day campaign totals and individual track, play, pause and skip events. These reports describe activity observed while the Recoup player is open. Playback after a fan leaves for Spotify or Apple Music is outside these reports. Player events and reported listening time are **not confirmed music-service stream counts** and do not prove that a campaign caused additional streams. Compare them with catalog stream measurements to evaluate campaign performance. ## Check your fan journey Before promoting the link, test it on the phones and social browsers your fans use. Confirm that sign-in works, the correct music opens, playlist songs can be selected, and the Spotify Free fallback works. Then check fan and activity reports in the intended workspace. "},{"slug":"api-reference/players/create","title":"Create a release player","description":"Create a release player","category":"Players","group":"Release players","source":"api-reference/players/create.mdx","body":"","headings":[],"api":{"method":"POST","path":"/api/players","spec":"players.json"},"searchText":"Create a release player Create a release player Players Release players POST /api/players "},{"slug":"api-reference/players/list","title":"List release players","description":"List release players","category":"Players","group":"Release players","source":"api-reference/players/list.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players","spec":"players.json"},"searchText":"List release players List release players Players Release players GET /api/players "},{"slug":"api-reference/players/get","title":"Read a release player","description":"Read a release player","category":"Players","group":"Release players","source":"api-reference/players/get.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}","spec":"players.json"},"searchText":"Read a release player Read a release player Players Release players GET /api/players/{id} "},{"slug":"api-reference/players/update","title":"Update a release player","description":"Update a release player","category":"Players","group":"Release players","source":"api-reference/players/update.mdx","body":"","headings":[],"api":{"method":"PATCH","path":"/api/players/{id}","spec":"players.json"},"searchText":"Update a release player Update a release player Players Release players PATCH /api/players/{id} "},{"slug":"api-reference/players/activity","title":"Read listening activity","description":"Read player listening activity","category":"Players","group":"Release players","source":"api-reference/players/activity.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}/activity","spec":"players.json"},"searchText":"Read listening activity Read player listening activity Players Release players GET /api/players/{id}/activity "},{"slug":"api-reference/players/fans","title":"Read artist player fans","description":"Read artist player fans","category":"Players","group":"Release players","source":"api-reference/players/fans.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/{id}/fans","spec":"players.json"},"searchText":"Read artist player fans Read artist player fans Players Release players GET /api/players/{id}/fans "},{"slug":"api-reference/players/workspace-fans","title":"Read workspace player fans","description":"Read workspace player fans","category":"Players","group":"Release players","source":"api-reference/players/workspace-fans.mdx","body":"","headings":[],"api":{"method":"GET","path":"/api/players/fans","spec":"players.json"},"searchText":"Read workspace player fans Read workspace player fans Players Release players GET /api/players/fans "},{"slug":"api-reference/complete/content/post-content-packs","title":"POST /api/content/packs","description":"Release rollout pending; discover current host capabilities before execution. Prepare a resumable pack brief. No artist profile or GitHub repository required; no paid generation.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs","spec":"content.json"},"searchText":"POST /api/content/packs Release rollout pending; discover current host capabilities before execution. Prepare a resumable pack brief. No artist profile or GitHub repository required; no paid generation."},{"slug":"api-reference/complete/content/get-content-packs-id","title":"GET /api/content/packs/{id}","description":"Release rollout pending; discover current host capabilities before execution. Read current owned job, assets, gaps and next action.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"GET","path":"/api/content/packs/{id}","spec":"content.json"},"searchText":"GET /api/content/packs/{id} Release rollout pending; discover current host capabilities before execution. Read current owned job, assets, gaps and next action."},{"slug":"api-reference/complete/content/patch-content-packs-id","title":"PATCH /api/content/packs/{id}","description":"Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"PATCH","path":"/api/content/packs/{id}","spec":"content.json"},"searchText":"PATCH /api/content/packs/{id} Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes."},{"slug":"api-reference/complete/content/post-content-packs-id-estimate","title":"POST /api/content/packs/{id}/estimate","description":"Release rollout pending; discover current host capabilities before execution. Quote complete scope at existing house image/video rates. Caption, inspection and composition are included at no additional customer charge.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/estimate","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/estimate Release rollout pending; discover current host capabilities before execution. Quote complete scope at existing house image/video rates. Caption, inspection and composition are included at no additional customer charge."},{"slug":"api-reference/complete/content/post-content-packs-id-generate","title":"POST /api/content/packs/{id}/generate","description":"Release rollout pending; discover current host capabilities before execution. Approve the current quote and budget ceiling. Start or resume the same job without duplicate submission.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/generate","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/generate Release rollout pending; discover current host capabilities before execution. Approve the current quote and budget ceiling. Start or resume the same job without duplicate submission."},{"slug":"api-reference/complete/content/post-content-packs-id-retry","title":"POST /api/content/packs/{id}/retry","description":"Release rollout pending; discover current host capabilities before execution. Retry only the selected failed asset within approved scope and ceiling; retain successful work.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/{id}/retry","spec":"content.json"},"searchText":"POST /api/content/packs/{id}/retry Release rollout pending; discover current host capabilities before execution. Retry only the selected failed asset within approved scope and ceiling; retain successful work."},{"slug":"api-reference/complete/content/post-content-packs-assets","title":"POST /api/content/packs/assets","description":"Release rollout pending; discover current host capabilities before execution. Upload explicitly selected audio or reference artwork to owned private storage; return a temporary locator.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"POST","path":"/api/content/packs/assets","spec":"content.json"},"searchText":"POST /api/content/packs/assets Release rollout pending; discover current host capabilities before execution. Upload explicitly selected audio or reference artwork to owned private storage; return a temporary locator."},{"slug":"api-reference/complete/content/get-content-packs-id-export","title":"GET /api/content/packs/{id}/export","description":"Release rollout pending; discover current host capabilities before execution. Retrieve an authenticated JSON manifest with captions, gaps and refreshed signed file URLs. Does not publish.","category":"Additional endpoints","group":"content","source":"api-reference/openapi/content.json","body":"","headings":[],"api":{"method":"GET","path":"/api/content/packs/{id}/export","spec":"content.json"},"searchText":"GET /api/content/packs/{id}/export Release rollout pending; discover current host capabilities before execution. Retrieve an authenticated JSON manifest with captions, gaps and refreshed signed file URLs. Does not publish."},{"slug":"api-reference/complete/players/get-players-public-id","title":"Read public player metadata without creating a session","description":"Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"GET","path":"/api/players/public/{id}","spec":"players.json"},"searchText":"GET /api/players/public/{id} Read public player metadata without creating a session Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials."},{"slug":"api-reference/complete/players/post-players-events","title":"Record reported listening","description":"Internal trusted Recoup player transport. Requires its Origin plus signed flow; browser-facing same-origin app proxy forwards to API. Provider and fan attribution come from the stored session. Event UUID makes retries idempotent, listenedMs is capped at 30 seconds and checked against elapsed server time. Recording failures do not stop music.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/events","spec":"players.json"},"searchText":"POST /api/players/events Record reported listening Internal trusted Recoup player transport. Requires its Origin plus signed flow; browser-facing same-origin app proxy forwards to API. Provider and fan attribution come from the stored session. Event UUID makes retries idempotent, listenedMs is capped at 30 seconds and checked against elapsed server time. Recording failures do not stop music."},{"slug":"api-reference/complete/players/post-players-spotify-session","title":"Exchange player Spotify authorization","description":"Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/spotify/session","spec":"players.json"},"searchText":"POST /api/players/spotify/session Exchange player Spotify authorization Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent."},{"slug":"api-reference/complete/players/post-players-public-id-session","title":"Acquire or resume a registered player session","description":"Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.","category":"Additional endpoints","group":"players","source":"api-reference/openapi/players.json","body":"","headings":[],"api":{"method":"POST","path":"/api/players/public/{id}/session","spec":"players.json"},"searchText":"POST /api/players/public/{id}/session Acquire or resume a registered player session Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials."}] \ No newline at end of file diff --git a/content/docs/source/api-reference/openapi/research.json b/content/docs/source/api-reference/openapi/research.json index 184bde1..99699e4 100644 --- a/content/docs/source/api-reference/openapi/research.json +++ b/content/docs/source/api-reference/openapi/research.json @@ -509,7 +509,7 @@ "/api/chats/{id}/messages/trailing": { "delete": { "operationId": "deleteChatsByIdMessagesTrailing", - "description": "Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override.\n\nThe caller must ensure there are no concurrent or outstanding message writers, including queued persistence and other edits. Any observed nonnull workflow slot returns `409` without cancelling work or clearing the slot. A null slot or a successful Stop does not prove that outstanding writers have finished. Concurrent edit/resend is unsupported.\n\nThe delete is scoped to this chat and includes the anchor, messages with a later timestamp, and messages at the same timestamp whose UUID sorts at or after the anchor UUID. Earlier UUIDs at the same timestamp survive; timestamp precision is preserved.\n\n`200` means the delete statement succeeded, possibly affecting zero rows. It does not report a deleted-row count or guarantee durable absence or prevent later message recreation. A transport failure can leave the commit outcome unknown: refresh authoritative history before deciding what to do next, rather than blindly resending a turn.", + "description": "Delete a message in a Workflow chat and every message after it, ordered by `created_at` then `id`. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns `409`. `200` means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending.", "parameters": [ { "name": "id", diff --git a/content/docs/source/llms-full.txt b/content/docs/source/llms-full.txt index b066a0e..62cf33d 100644 --- a/content/docs/source/llms-full.txt +++ b/content/docs/source/llms-full.txt @@ -7510,7 +7510,7 @@ The supplied specification does not declare an OpenAPI security object for this Source: https://docs.recoupable.dev/api-reference/chat/messages-trailing-delete -Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override. +Delete a message in a Workflow chat and every message after it, ordered by `created_at` then `id`. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns `409`. `200` means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending. ## DELETE /api/chats/{id}/messages/trailing @@ -7544,7 +7544,7 @@ This operation requires one of the security alternatives in the specification be "/api/chats/{id}/messages/trailing": { "delete": { "operationId": "deleteChatsByIdMessagesTrailing", - "description": "Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override.\n\nThe caller must ensure there are no concurrent or outstanding message writers, including queued persistence and other edits. Any observed nonnull workflow slot returns `409` without cancelling work or clearing the slot. A null slot or a successful Stop does not prove that outstanding writers have finished. Concurrent edit/resend is unsupported.\n\nThe delete is scoped to this chat and includes the anchor, messages with a later timestamp, and messages at the same timestamp whose UUID sorts at or after the anchor UUID. Earlier UUIDs at the same timestamp survive; timestamp precision is preserved.\n\n`200` means the delete statement succeeded, possibly affecting zero rows. It does not report a deleted-row count or guarantee durable absence or prevent later message recreation. A transport failure can leave the commit outcome unknown: refresh authoritative history before deciding what to do next, rather than blindly resending a turn.", + "description": "Delete a message in a Workflow chat and every message after it, ordered by `created_at` then `id`. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns `409`. `200` means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending.", "parameters": [ { "name": "id", diff --git a/scripts/test_chat_trailing_contracts.py b/scripts/test_chat_trailing_contracts.py index 82824ab..fa52add 100644 --- a/scripts/test_chat_trailing_contracts.py +++ b/scripts/test_chat_trailing_contracts.py @@ -1,5 +1,6 @@ """Freeze the bounded trailing-delete reference without claiming writer serialization.""" import json +import re import subprocess from response_contract_test_case import ResponseContractTestCase @@ -21,6 +22,8 @@ def test_status_schemas_and_authored_operation_survive_export(self): 'Chat has an active workflow reservation; retry after it clears') self.assertIn('possibly affecting zero rows', operation['description']) self.assertIn('Concurrent edit/resend is unsupported', operation['description']) + sentences = re.split(r'(?<=[.!?])\s+(?=[A-Z`])', operation['description'].strip()) + self.assertLessEqual(len(sentences), 3, 'KISS: keep the operation description to 2-3 sentences') def test_export_reads_authored_narrative_and_examples(self): path = self.marketing / 'content/docs/source/api-reference/openapi/research.json'