recoup-platform-api-access

Recoup — API 访问

平台访问层：进行身份验证、调用 Recoup REST API，以及调用外部连接器。基础 URL：https://api.recoupable.dev/api；文档：https://docs.recoupable.dev（/llms.txt、/llms-full.txt、OpenAPI JSON）。

优先使用经过身份验证的 MCP 工具

先发现宿主的 Recoup MCP 工具目录。若某个工具的实际架构和结果能够满足所请求的操作，请使用该工具。不同宿主使用的前缀可能不同。使用 list_artists 发现艺人名单，并将后续请求绑定到返回的 ID。不要推断所有 REST 端点或外部连接器都有对应的 MCP 工具。

宿主负责管理 OAuth。不要提取其令牌、向用户索取令牌，或将令牌放入 REST 请求。MCP 连接可正常工作，不需要环境变量。 如果只有受限的工具目录，请使用 mcp:tools 授权重新连接，并刷新宿主的工具。不要仅仅因为工具可用就发起发送、发布、删除或付费操作。

对于 MCP 中没有的操作，请沿用下方记录的 REST 工作流。 如果缺少 REST 凭据，请说明具体限制；不要声称整个 Recoup 连接已中断，也不要创建临时账号。

REST 回退 — 一个 Bearer 标头，直接内联

每次 REST 调用都使用相同的标头，直接放入 curl（无需设置步骤）： 沙盒会设置两个变量中的一个，API 接受 recoup_sk_ 密钥或通过 Bearer 传递的 Privy JWT。

curl -sS -H "Authorization: Bearer ${RECOUP_API_KEY:-$RECOUP_ACCESS_TOKEN}" \
  "https://api.recoupable.dev/api/artists/{id}/socials"

如果两个变量都未设置，请使用适用的已连接 MCP 工具，或针对缺少的功能请求单独设置 REST。不要在未进行身份验证的情况下重试。

先选择艺术家模式（猜测会凭空捏造艺术家）

• A — 任意艺术家研究（提供名称；不查询名册）→ 研究端点。
• B — 浏览我的名册 → 名册发现（见下文）。
• C — 指定名册中的某位艺术家 → 名册发现，匹配名称，并获取 艺术家的 account_id（当前列表中的 id 是它的别名）。
• D — 添加艺术家 → 使用 recoup-roster-add-artist。

名册发现： GET /accounts/id → GET /artists（你的名册；org_id 为可选参数——组织列表通常为空，因此即使 organizations 为 [] 也不要停止）。

所有 /artists/{id}/* 子资源都必须使用艺术家的账户 UUID。 当前名册记录会在 account_id 和 id 中返回该 UUID。不要使用内部档案行键、 Spotify ID 或不透明的研究 ID。请使用当前已认证的名册核对之前保存的 ID。 社交信息已嵌入 /artists 响应中的 account_socials （username、followerCount、profile_url）——先在这里读取，再决定是否调用 /artists/{account_id}/socials。

**停止规则——绝不编造名册：**如果 GET /accounts/id 解析出的邮箱是 agent+…@recoupable.com， 那就是一次性密钥——请说明这一点，并要求提供真实账户密钥（或使用 recoup-platform-connect-account）。不要为了继续操作而捏造艺术家或名册。

**停止规则——绝不编造指标/数据：**只报告本次运行中通过成功调用获取的数字。如果调用报错或返回空结果，或者没有相应指标的连接器（GET /connectors/actions → 检查 isConnected），请说明情况并省略该数据——绝不要估算、使用“行业平均值”或用示例/占位数字填补空缺。简短准确的报告胜过冗长却捏造的报告。

**放弃缺失数据前——先获取数据，或提供连接链接。**如果指标的数据源未连接，请先按以下顺序处理，再考虑省略：

1. 抓取可获取的公开数据——POST /api/socials/{social_id}/scrape （单个个人主页），或 POST /api/artist/socials/scrape（某位艺术家的所有社交账号）。适用于 TikTok / Instagram / X / YouTube / Threads / Facebook。报告这些真实的公开数据。
2. 检查连接状态——GET /api/connectors → 检查每个连接器的 isConnected。
3. 生成连接链接——POST /api/connectors {"connector":"youtube"} 会返回 { redirectUrl }（Composio OAuth URL）。将其提供给调用者，让用户自行连接：“CPM/收入数据需要 YouTube Analytics——请在此连接：{redirectUrl}”。

返回真实公开数据 以及 连接链接——这比捏造报告或返回空结果/省略数据都好。

文档索引（按需提取相关章节；不要猜测路径）

账户与身份 · 艺术家与内容 · 研究（Songstats + Web）· 社交 集成 · 聊天与 Agent · 开发者/基础设施。通过搜索 llms-full.txt 或获取对应领域的 OpenAPI JSON，查找确切路径/参数，例如：

curl -s https://docs.recoupable.dev/llms-full.txt | grep -A 30 -i "similar artists"
curl -s https://docs.recoupable.dev/api-reference/openapi/research.json | jq '.paths | keys'

地域信息来自 audience；发现信息来自 similar + web。

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

对于 Recoup 之外的读取/写入操作：

• GET /connectors/actions — 操作目录（包含每个操作的 slug、parameters 架构、connectorSlug、isConnected）。
• POST /connectors/actions {actionSlug, parameters} — 执行一项操作。

Slug 使用 UPPERCASE_SNAKE_CASE（例如 GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN、 GMAIL_FETCH_EMAILS）。执行前务必从目录中获取参数架构——不同操作的结构各不相同。触发判断：用户粘贴了 docs.google.com/drive.google.com/sheets.google.com URL，或提出“编辑这份文档”、 “发送邮件”、“在 TikTok 上发布”等要求。

发送邮件（通过 Recoup）

POST /api/emails 会通过 Recoup，以 Agent by Recoup <[email protected]> 的身份发送邮件 —— 只需使用你的 API 密钥即可无头运行，无需 Gmail 连接器。可用于发送报告、提醒和定时任务输出。

使用 bash 运行（不要用 web_fetch — 它会隐藏响应，你无法确认收件人）：

curl -sS -X POST -H "Authorization: Bearer ${RECOUP_API_KEY:-$RECOUP_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"to":["[email protected]"],"subject":"Weekly report","text":"# Summary\n…"}' \
  "https://api.recoupable.dev/api/emails"
# → {"success":true,"message":"Email sent successfully … to [email protected].","id":"<resend-id>"}

to 是电子邮件字符串组成的 JSON 数组（["[email protected]"] — 不能是纯字符串，也不能是 [{"email":…}]）。唯一支持的键是 to、cc、subject、text、html、 chat_id、account_id；未知键（例如 recipients）会被丢弃，而 to 随后会默认为 你自己的账户邮箱 — 导致邮件被悄悄发错。subject 是可选的。读取响应，确认 message 中列出的是你预期的收件人。账户未绑定付款方式 → to/cc 仅限账户自己的邮箱（403）。 若要以用户身份从其自己的 Gmail 发送邮件，请使用 GMAIL_SEND_EMAIL。

故障排除

401 = 缺少令牌或令牌已过期（检查凭据）。403 = 无权访问该组织/艺术家。404 = 重新检查 Docs 地图（端点已移动/重命名）。5xx = 重试一次，然后报告状态。

不要在以下情况下使用

• 沙盒内的文件 → 文件系统工具。
• 为艺术家配置或管理工作区 → recoup-roster-* 技能。
• 领域任务（研究/内容/发布/交易/歌曲）→ 对应领域技能，该技能会自行调用。