Back to Details

recoup-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Recoupable API

Recoupable API

Call the Recoupable production API to fetch artist data, social metrics, org context, research, and to trigger platform operations.
  • Base URL: 
    https://recoup-api.vercel.app/api
  • LLM-readable docs: 
    https://developers.recoupable.com
    — Mintlify site. Use 
    /llms.txt
    for the endpoint index, 
    /llms-full.txt
    for full content, and the OpenAPI JSONs listed below for machine-readable schemas.
调用Recoupable生产环境API，获取艺术家数据、社交指标、机构上下文、研究资料，并触发平台操作。
  • 基础URL：
    https://recoup-api.vercel.app/api
  • LLM可读文档：
    https://developers.recoupable.com
    — Mintlify站点。使用
    /llms.txt
    获取端点索引，
    /llms-full.txt
    获取完整内容，使用下方列出的OpenAPI JSON获取机器可读的 schema。

Authentication

认证

Your sandbox receives a short-lived access token in 
RECOUP_ACCESS_TOKEN
. Use it as a 
Bearer
token on every request:
bash
curl -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  https://recoup-api.vercel.app/api/artists/{artistId}/socials
If 
RECOUP_ACCESS_TOKEN
is empty, the user is not authenticated — tell them to sign in rather than retrying.
你的沙箱会在
RECOUP_ACCESS_TOKEN
中获取一个短期访问令牌。请在每个请求中以
Bearer
令牌的形式使用它：
bash
curl -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  https://recoup-api.vercel.app/api/artists/{artistId}/socials
如果
RECOUP_ACCESS_TOKEN
为空，说明用户未认证——请告知用户登录而非重试。

Org scoping (
RECOUP_ORG_ID
)

组织范围（
RECOUP_ORG_ID
）

When running inside a sandbox, the environment also exposes 
RECOUP_ORG_ID
— the organization the sandbox was opened for. The access token is account-scoped (it covers every org the account belongs to), so when you use it with unscoped list endpoints like 
GET /api/artists
you will get results from all of that account's orgs, not just the one this sandbox represents. That mismatch surprises accounts.
When 
RECOUP_ORG_ID
is set, scope list/query endpoints to it:
bash
undefined
在沙箱内运行时，环境还会暴露
RECOUP_ORG_ID
——即打开沙箱对应的组织。访问令牌是账号级别的（覆盖该账号所属的所有组织），因此当你将其用于未限定范围的列表端点（如
GET /api/artists
）时，你将获取该账号所有组织的结果，而非当前沙箱对应的单个组织。这种不一致会让用户感到困惑。
当
RECOUP_ORG_ID
已设置时，请将列表/查询端点限定到该组织：
bash
undefined

Artists for this sandbox's org only

仅获取当前沙箱所属组织的艺术家

curl -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN"
"https://recoup-api.vercel.app/api/organizations/$RECOUP_ORG_ID/artists"

For the Recoup CLI, pass `--org "$RECOUP_ORG_ID"` on commands that accept it. If `RECOUP_ORG_ID` is unset, you are not in an open-agents sandbox — fall back to account-scoped calls as normal.

**Sandbox-inventory shortcut:** for bare "what artists / orgs do I have" questions, prefer reading the local `artists/*/RECOUP.md` tree instead of calling the API at all — the filesystem is authoritative for this sandbox. See the `artist-workspace` skill for the walkthrough.
curl -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN"
"https://recoup-api.vercel.app/api/organizations/$RECOUP_ORG_ID/artists"

对于Recoup CLI，在接受该参数的命令中传递`--org "$RECOUP_ORG_ID"`。如果`RECOUP_ORG_ID`未设置，说明你不在开放代理沙箱中——请正常回退到账号级别的调用。

**沙箱清单快捷方式**：对于简单的“我有哪些艺术家/组织”这类问题，优先读取本地`artists/*/RECOUP.md`目录结构，而非调用API——文件系统是当前沙箱的权威数据源。请查看`artist-workspace`技能获取详细指南。

Docs Map

文档地图

The full endpoint surface is organized into the sections below. Use this map to pick the right area, then pull the detailed docs for just that area (see Finding an endpoint) instead of fetching everything.
完整的端点范围分为以下几个部分。使用此地图选择正确的区域，然后仅获取该区域的详细文档（参见查找端点），而非获取全部内容。

Account & Identity

账号与身份

  • Accounts — create/get/update accounts, add artists to account
  • Organizations — create/list orgs, add artists to org
  • Workspaces — create workspaces
  • Subscriptions — get subscriptions, create Stripe checkout session
  • Agents — agent signup, email verification
  • Admins — admin-only: agent sign-ups, coding/content agent Slack tags, Resend emails, Privy logins, sandbox stats, org repo commit stats
  • Accounts（账号）——创建/获取/更新账号，为账号添加艺术家
  • Organizations（组织）——创建/列出组织，为组织添加艺术家
  • Workspaces（工作区）——创建工作区
  • Subscriptions（订阅）——获取订阅信息，创建Stripe结账会话
  • Agents（代理）——代理注册，邮箱验证
  • Admins（管理员）——仅管理员可用：代理注册、编码/内容代理Slack标签、Resend邮件、Privy登录、沙箱统计、组织仓库提交统计

Artists & Content

艺术家与内容

  • Artists — create/get/delete, get socials, pin/unpin, get profile (across all platforms), trigger socials scrape
  • Posts — get artist posts across platforms
  • Comments — get comments for an artist or a specific post
  • Fans — get social profiles of an artist's fans
  • Songs — create/get songs by ISRC, manage catalogs (CRUD + add/remove songs), analyze songs via audio LM, list analyze presets
  • Content Creation — pipeline trigger, video/image/caption generation, ffmpeg edits, video analysis, upscale, cost estimate, audio transcription, templates
  • Artists（艺术家）——创建/获取/删除，获取社交账号信息，固定/取消固定，获取跨平台资料，触发社交账号数据抓取
  • Posts（帖子）——获取艺术家在各平台的帖子
  • Comments（评论）——获取艺术家或特定帖子的评论
  • Fans（粉丝）——获取艺术家粉丝的社交资料
  • Songs（歌曲）——通过ISRC创建/获取歌曲，管理目录（增删改查 + 添加/移除歌曲），通过音频LM分析歌曲，列出分析预设
  • Content Creation（内容创作）——触发流水线，生成视频/图片/文案，ffmpeg编辑，视频分析，画质提升，成本估算，音频转录，模板

Research (Chartmetric + Web)

研究（Chartmetric + 网页）

One section covering most music-industry lookup work:
  • Discovery: search, profile, similar artists, discover by criteria, people search, lookup by URL
  • Catalog: albums, tracks, track playlists
  • Metrics: artist rank, platform metrics (14 platforms), audience demographics, career timeline, listener cities, milestones, charts
  • Surface: playlist, playlist placements, venues, radio stations, festivals, genres, curator
  • Insights: AI insights, social URLs, instagram posts
  • Web: enrich, extract URL, deep research, web search
涵盖大多数音乐行业查询工作的板块：
  • Discovery（发现）：搜索、资料查询、相似艺术家、按条件发现、人物搜索、通过链接查询
  • Catalog（目录）：专辑、曲目、曲目播放列表
  • Metrics（指标）：艺术家排名、平台指标（14个平台）、受众 demographics、职业 timeline、听众所在城市、里程碑、榜单
  • Surface（曝光渠道）：播放列表、播放列表占位、场馆、电台、音乐节、流派、策展人
  • Insights（洞察）：AI洞察、社交链接、Instagram帖子
  • Web（网页）：丰富内容、提取链接深度研究、网页搜索

Social Integrations

社交集成

  • Social Media — get social posts from a profile, trigger scrape
  • Instagram Integration — comments, profiles (bulk)
  • Spotify Integration — search, artist, artist albums, artist top tracks, album
  • Twitter/X Integration — search tweets, get trends
  • Connectors — list/authorize/disconnect third-party OAuth integrations
  • Connector actions — execute external operations (Google Docs/Sheets/Drive edits, Gmail, TikTok, Instagram) via shared connections. See the section below.
  • Apify Integration — scraper run results
  • Transcription — Whisper audio transcription
  • Social Media（社交媒体）——获取社交资料的帖子，触发抓取
  • Instagram Integration（Instagram集成）——评论、资料（批量）
  • Spotify Integration（Spotify集成）——搜索、艺术家、艺术家专辑、艺术家热门曲目、专辑
  • Twitter/X Integration（Twitter/X集成）——搜索推文、获取趋势
  • Connectors（连接器）——列出/授权/断开第三方OAuth集成
  • Connector actions（连接器操作）——通过共享连接执行外部操作（Google Docs/Sheets/Drive编辑、Gmail、TikTok、Instagram）。参见下方板块。
  • Apify Integration（Apify集成）——抓取器运行结果
  • Transcription（转录）——Whisper音频转录

Chat & Agents

聊天与代理

  • Chat — create/get/delete chats, messages, AI generate/stream (Vercel AI SDK compatible), update, copy, compact
  • Content Agent — Slack webhook + task callback (internal)
  • Pulses — list/update pulses
  • Notifications — send notification email to the authenticated account
  • Tasks — create/get/update/delete scheduled tasks, get task run history
  • Image Generation — standalone AI image gen (also available scoped under Content Creation)
  • Chat（聊天）——创建/获取/删除聊天、消息、AI生成/流式传输（兼容Vercel AI SDK）、更新、复制、压缩
  • Content Agent（内容代理）——Slack webhook + 任务回调（内部）
  • Pulses（动态）——列出/更新动态
  • Notifications（通知）——向已认证账号发送通知邮件
  • Tasks（任务）——创建/获取/更新/删除定时任务，获取任务运行历史
  • Image Generation（图片生成）——独立AI图片生成（也可在内容创作板块下使用）

Developer & Infrastructure

开发者与基础设施

  • Sandboxes — create/setup/list/delete sandboxes, get file contents, upload files, update snapshot
  • Sandboxes（沙箱）——创建/设置/列出/删除沙箱，获取文件内容，上传文件，更新快照

Guides (non-endpoint pages)

指南（非端点页面）

Authentication · CLI · MCP · Quickstart.
认证 · CLI · MCP · 快速入门。

OpenAPI specs

OpenAPI规范

Machine-readable schemas for the major sections: 
accounts.json
, 
social.json
, 
releases.json
, 
research.json
, 
content.json
(served at 
https://developers.recoupable.com/<name>.json
).
各主要板块的机器可读schema：
accounts.json
、
social.json
、
releases.json
、
research.json
、
content.json
（托管于
https://developers.recoupable.com/<name>.json
）。

Finding an endpoint

查找端点

Once you know the section, pull just that section's docs instead of the whole index. Example patterns:
bash
undefined
确定板块后，仅获取该板块的文档，而非整个索引。示例模式：
bash
undefined

Find the exact path + params for a specific endpoint

查找特定端点的准确路径 + 参数

curl -s https://developers.recoupable.com/llms-full.txt | grep -A 30 -i "similar artists"
curl -s https://developers.recoupable.com/llms-full.txt | grep -A 30 -i "similar artists"

Pull the OpenAPI schema for one area

获取某一板块的OpenAPI schema

curl -s https://developers.recoupable.com/research.json | jq '.paths | keys'

Do **not** guess exact paths, parameter names, or response shapes — fetch the relevant section first.
curl -s https://developers.recoupable.com/research.json | jq '.paths | keys'

**请勿**猜测准确路径、参数名称或响应格式——请先获取相关板块的内容。

Example request

示例请求

bash
undefined
bash
undefined

Get all socials for an artist

获取某艺术家的所有社交账号信息

curl -sS -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN"
"https://recoup-api.vercel.app/api/artists/{artistId}/socials" | jq

`jq` is preinstalled in the sandbox.
curl -sS -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN"
"https://recoup-api.vercel.app/api/artists/{artistId}/socials" | jq

沙箱中已预安装`jq`。

Multi-step workflows

多步骤工作流

For multi-endpoint sequences that need a specific order, follow the published workflow guides instead of inventing the chain yourself. The guide tells you which endpoint to call at each step, what to capture for the next step, and which steps are intentionally skipped from a sandbox context.
WorkflowGuideDriver
Create + research a new artist (full enrichment chain — POST artist, Spotify match, profile/socials/knowledges, structured research via Chartmetric profile/career/playlists + web, KB synthesis)https://developers.recoupable.com/workflows/create-artist
artist-workspace
skill — scaffolds a 
RECOUP.md
checklist file, ticks each step on completion
Trigger to load a workflow guide: any phrase like "create a new artist", "onboard X", "add this artist", or any request that requires more than one endpoint to complete.
For the create-artist chain, invoke the 
artist-workspace
skill first — it scaffolds 
artists/{slug}/RECOUP.md
with one checkbox per workflow step, and the agent then drives execution from that file (tick + persist outputs to frontmatter after every step). The workflow guide above is the curl-by-curl reference for each step's request shape, but the checklist is the source of truth for what's done. The chain has 8 sequential calls and skipping any leaves the artist partially populated.
对于需要特定顺序的多端点序列，请遵循已发布的工作流指南，而非自行构建调用链。指南会告诉你每个步骤应调用哪个端点、为下一步捕获哪些内容，以及在沙箱环境中可跳过哪些步骤。
工作流指南驱动工具
创建并研究新艺术家（完整 enrichment 链——POST艺术家、Spotify匹配、资料/社交账号/知识库、通过Chartmetric资料/职业生涯/播放列表 + 网页进行结构化研究、KB合成）https://developers.recoupable.com/workflows/create-artist
artist-workspace
技能——生成
RECOUP.md
checklist文件，完成每个步骤后勾选
触发加载工作流指南的短语：任何类似“创建新艺术家”“入驻X”“添加此艺术家”的表述，或任何需要多个端点才能完成的请求。
对于创建艺术家的调用链，请先调用
artist-workspace
技能——它会在
artists/{slug}/RECOUP.md
中生成包含工作流每个步骤的复选框，代理随后会根据该文件驱动执行（完成每个步骤后勾选并将输出持久化到前置内容中）。上述工作流指南是每个步骤请求格式的curl参考，但checklist是已完成内容的权威来源。该调用链包含8个顺序调用，跳过任何一个都会导致艺术家信息不完整。

Connector actions (Google Docs/Sheets/Drive, Gmail, TikTok, Instagram)

连接器操作（Google Docs/Sheets/Drive、Gmail、TikTok、Instagram）

For reads/writes outside Recoup — editing a Google Doc by URL, syncing a sandbox file with Drive, sending an email, posting a TikTok — use the platform's shared third-party connections via two endpoints:
  • GET /api/connectors/actions
    — catalog of every available action with its 
    slug
    , 
    description
    , 
    parameters
    JSON Schema, 
    connectorSlug
    , and 
    isConnected
    . See docs.
  • POST /api/connectors/actions
    — execute one by 
    actionSlug
    with 
    parameters
    matching its schema. See docs.
Slugs are always UPPERCASE_SNAKE_CASE (e.g. 
GOOGLEDOCS_INSERT_TEXT_ACTION
, 
GMAIL_FETCH_EMAILS
). Auth is the same 
RECOUP_ACCESS_TOKEN
Bearer. Always pull the parameters schema from the catalog before executing — Composio's shapes vary per action.
对于Recoup外部的读取/写入操作——通过链接编辑Google Doc、将沙箱文件与Drive同步、发送邮件、在TikTok发布内容——请通过两个端点使用平台的共享第三方连接：
  • GET /api/connectors/actions
    ——所有可用操作的目录，包含
    slug
    、
    description
    、
    parameters
    JSON Schema、
    connectorSlug
    和
    isConnected
    。参见文档。
  • POST /api/connectors/actions
    ——通过
    actionSlug
    执行操作，
    parameters
    需匹配其schema。参见文档。
Slug始终为大写蛇形命名法（例如
GOOGLEDOCS_INSERT_TEXT_ACTION
、
GMAIL_FETCH_EMAILS
）。认证方式同样为
RECOUP_ACCESS_TOKEN
Bearer令牌。执行前请务必从目录获取参数schema——Composio的格式因操作而异。

Worked example: Google Doc ↔ sandbox file sync

示例：Google Doc ↔ 沙箱文件同步

When the user pastes a 
docs.google.com/document/d/{ID}/edit
URL, extract the ID and pick the right Google Docs action — 
GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT
to read, 
GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN
to replace the whole doc, 
GOOGLEDOCS_INSERT_TEXT_ACTION
to insert at an index, 
GOOGLEDOCS_REPLACE_ALL_TEXT
for find-replace:
bash
DOC_ID=$(echo "$DOC_URL" | sed -nE 's|.*/document/d/([^/]+).*|\1|p')
EXEC="https://recoup-api.vercel.app/api/connectors/actions"
AUTH=(-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" -H "Content-Type: application/json")
当用户粘贴
docs.google.com/document/d/{ID}/edit
链接时，提取ID并选择合适的Google Docs操作——
GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT
用于读取，
GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN
用于替换整个文档内容，
GOOGLEDOCS_INSERT_TEXT_ACTION
用于在指定位置插入内容，
GOOGLEDOCS_REPLACE_ALL_TEXT
用于查找替换：
bash
DOC_ID=$(echo "$DOC_URL" | sed -nE 's|.*/document/d/([^/]+).*|\1|p')
EXEC="https://recoup-api.vercel.app/api/connectors/actions"
AUTH=(-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" -H "Content-Type: application/json")

Read the doc into a local file.

将文档内容读取到本地文件。

curl -sS -X POST "${AUTH[@]}" "$EXEC"
-d "$(jq -n --arg id "$DOC_ID" '{actionSlug:"GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT", parameters:{document_id:$id}}')"
| jq -r '.result.data.text' > artists/$ARTIST_SLUG/notes.md
curl -sS -X POST "${AUTH[@]}" "$EXEC"
-d "$(jq -n --arg id "$DOC_ID" '{actionSlug:"GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT", parameters:{document_id:$id}}')"
| jq -r '.result.data.text' > artists/$ARTIST_SLUG/notes.md

(edit notes.md locally — agent edits, git diff, etc.)

（在本地编辑notes.md——代理编辑、git diff等）

Push it back, replacing the doc's content.

将编辑后的内容推回，替换文档内容。

curl -sS -X POST "${AUTH[@]}" "$EXEC"
-d "$(jq -n --arg id "$DOC_ID" --rawfile md artists/$ARTIST_SLUG/notes.md
'{actionSlug:"GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN", parameters:{document_id:$id, markdown_content:$md}}')"

The Google Doc and the local file are two views of the same content — commit the local copy with the artist's other workspace files.

**Trigger heuristic:** external URLs (`docs.google.com`, `drive.google.com`, `sheets.google.com`), or phrases like "edit this doc", "send an email", "post on TikTok". Internal Recoup resources (artists, socials, research) use the dedicated endpoints in the Docs Map above.
curl -sS -X POST "${AUTH[@]}" "$EXEC"
-d "$(jq -n --arg id "$DOC_ID" --rawfile md artists/$ARTIST_SLUG/notes.md
'{actionSlug:"GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN", parameters:{document_id:$id, markdown_content:$md}}')"

Google Doc和本地文件是同一内容的两个视图——请将本地副本与艺术家的其他工作区文件一起提交。

**触发规则**：外部链接（`docs.google.com`、`drive.google.com`、`sheets.google.com`），或类似“编辑此文档”“发送邮件”“在TikTok发布内容”的表述。Recoup内部资源（艺术家、社交账号、研究资料）请使用上方文档地图中的专用端点。

Troubleshooting

故障排除

ErrorMeaningFix
401Token missing, invalid, or expiredCheck 
RECOUP_ACCESS_TOKEN
is set; if the prompt has been running a long time, ask the user to resend
403User lacks access to the resourceConfirm the user has permission for the org/artist being queried
404Endpoint not foundRe-check the Docs Map above; the endpoint may have moved or been renamed
5xxServer errorRetry once; if persistent, surface the status to the user
错误含义修复方法
401令牌缺失、无效或过期检查
RECOUP_ACCESS_TOKEN
是否已设置；如果会话运行时间较长，请要求用户重新发送
403用户缺乏资源访问权限确认用户对所查询的组织/艺术家拥有权限
404端点未找到重新检查上方文档地图；该端点可能已迁移或重命名
5xx服务器错误重试一次；如果问题持续，请将状态告知用户

When NOT to use this skill

何时不使用此技能

  • Reading/writing files inside the sandbox — use the filesystem tools.
  • Calling Chartmetric, Spotify, or other third-party APIs directly — prefer the Recoup Research endpoints above (they wrap Chartmetric with our auth), or use the dedicated skill if one exists (e.g. 
    chartmetric
    ).
  • Reading the user's git repo contents — that's already mounted in the working directory.
  • 读取/写入沙箱内的文件——使用文件系统工具。
  • 直接调用Chartmetric、Spotify或其他第三方API——优先使用上方Recoup的Research端点（它们通过我们的认证封装了Chartmetric），或使用专用技能（如
    chartmetric
    ）。
  • 读取用户的git仓库内容——该内容已挂载到工作目录中。