Back to Details

recoup-platform-api-access

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Recoup — API Access

Recoup — API 访问

The platform access layer: authenticate, talk to the Recoup REST API, and invoke external connectors. Base 
https://api.recoupable.dev/api
; docs 
https://docs.recoupable.dev
(
/llms.txt
, 
/llms-full.txt
, OpenAPI JSONs).
平台访问层：完成认证、调用Recoup REST API并触发外部连接器。基础地址为
https://api.recoupable.dev/api
；文档地址为
https://docs.recoupable.dev
（包含
/llms.txt
、
/llms-full.txt
及OpenAPI JSON文件）。

Auth — one Bearer header, inline

认证 — 单个Bearer头部，直接嵌入

Every call uses the same header, dropped straight into the 
curl
(no setup step): the sandbox sets one of the two vars, and the API accepts a 
recoup_sk_
key or a Privy JWT over 
Bearer
.
bash
curl -sS -H "Authorization: Bearer ${RECOUP_API_KEY:-$RECOUP_ACCESS_TOKEN}" \
  "https://api.recoupable.dev/api/artists/{id}/socials"
If neither var is set, ask the user to authenticate — don't retry blindly.
每次调用都使用同一个头部，直接写入
curl
命令（无需设置步骤）：沙箱会设置两个变量之一，API接受
recoup_sk_
密钥或通过
Bearer
传递的Privy JWT。
bash
curl -sS -H "Authorization: Bearer ${RECOUP_API_KEY:-$RECOUP_ACCESS_TOKEN}" \
  "https://api.recoupable.dev/api/artists/{id}/socials"
如果两个变量均未设置，请请求用户完成认证——不要盲目重试。

Pick the artist mode first (guessing here fabricates artists)

首先选择艺人模式（此处猜测会生成虚构艺人）

  • A — any-artist research (a name; no roster lookup) → Research endpoints.
  • B — browse my roster → Roster discovery (below).
  • C — a specific roster artist → Roster discovery, match the name, capture 
    account_id
    + row 
    id
    .
  • D — add an artist → use recoup-roster-add-artist.
Roster discovery: 
GET /accounts/id
→ 
GET /organizations
→ 
GET /artists?org_id=…
(each artist row has 
name
, 
account_id
, and a row 
id
— capture both ids).
Stop rule — never invent a roster: if 
GET /accounts/id
resolves to an 
agent+…@recoupable.com
email, or 
organizations
and 
artists
both return 
[]
, it's a throwaway key — say so and ask for a real-account key (or recoup-platform-connect-account). Don't fabricate an artist/roster to keep moving.
  • A — 任意艺人调研（仅需姓名；无需查询艺人名单）→ 调用调研类端点。
  • B — 浏览我的艺人名单 → 艺人名单发现（见下文）。
  • C — 指定名单内的艺人 → 艺人名单发现，匹配姓名，获取
    account_id
    及行
    id
    。
  • D — 添加艺人 → 使用recoup-roster-add-artist技能。
艺人名单发现流程： 
GET /accounts/id
→ 
GET /organizations
→ 
GET /artists?org_id=…
（每个艺人条目包含
name
、
account_id
和行
id
——需同时获取两个ID）。
停止规则 — 切勿虚构艺人名单： 如果
GET /accounts/id
返回
agent+…@recoupable.com
格式的邮箱，或
organizations
与
artists
均返回
[]
，说明当前密钥为临时测试密钥——请告知用户并请求提供真实账号密钥（或使用recoup-platform-connect-account技能）。切勿为推进流程而虚构艺人/名单。

Docs map (pull the section you need; don't guess paths)

文档映射（按需获取对应章节；切勿猜测路径）

Account & Identity · Artists & Content · Research (Songstats + Web) · Social Integrations · Chat & Agents · Developer/Infra. Find the exact path/params by grepping 
llms-full.txt
or pulling the OpenAPI JSON for the area, e.g.:
bash
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'
Geography comes from 
audience
; discovery from 
similar
+ 
web
.
账号与身份 · 艺人和内容 · 调研（Songstats + 网络） · 社交集成 · 聊天与Agent · 开发者/基础设施。可通过搜索
llms-full.txt
或获取对应领域的OpenAPI JSON文件来找到准确的路径/参数，例如：
bash
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
字段。

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

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

For reads/writes outside Recoup:
  • GET /connectors/actions
    — catalog (each action's 
    slug
    , 
    parameters
    schema, 
    connectorSlug
    , 
    isConnected
    ).
  • POST /connectors/actions
    {actionSlug, parameters}
    — execute one.
Slugs are 
UPPERCASE_SNAKE_CASE
(e.g. 
GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN
, 
GMAIL_FETCH_EMAILS
). Always pull the parameters schema from the catalog before executing — shapes vary per action. Trigger heuristic: a pasted 
docs.google.com
/
drive.google.com
/
sheets.google.com
URL, or "edit this doc", "send an email", "post on TikTok".
如需在Recoup外部进行读写操作：
  • GET /connectors/actions
    — 获取操作目录（包含每个操作的
    slug
    、
    parameters
    schema、
    connectorSlug
    、
    isConnected
    ）。
  • POST /connectors/actions
    {actionSlug, parameters}
    — 执行指定操作。
操作标识（Slugs）采用
大写蛇形命名法
（例如
GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN
、
GMAIL_FETCH_EMAILS
）。执行操作前务必从目录中获取参数schema——不同操作的参数结构不同。触发判断依据：粘贴的
docs.google.com
/
drive.google.com
/
sheets.google.com
链接，或类似"编辑此文档"、"发送邮件"、"在TikTok发布内容"的指令。

Send an email (from Recoup)

发送邮件（通过Recoup）

POST /api/emails
sends an email from 
Agent by Recoup <agent@recoupable.com>
via Recoup — works headless with your API key, no Gmail connector needed. Use it for reports, alerts, and scheduled-task output.
Run it with 
bash
(not 
web_fetch
— that hides the response and you can't confirm the recipient):
bash
curl -sS -X POST -H "Authorization: Bearer ${RECOUP_API_KEY:-$RECOUP_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"to":["someone@example.com"],"subject":"Weekly report","text":"# Summary\n…"}' \
  "https://api.recoupable.dev/api/emails"
POST /api/emails
可通过Recoup从
Agent by Recoup <agent@recoupable.com>
发送邮件——无需Gmail连接器，仅需API密钥即可无界面运行。适用于发送报告、告警及定时任务输出。
请使用
bash
执行（不要使用
web_fetch
——该方式会隐藏响应，无法确认收件人）：
bash
curl -sS -X POST -H "Authorization: Bearer ${RECOUP_API_KEY:-$RECOUP_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"to":["someone@example.com"],"subject":"Weekly report","text":"# Summary\n…"}' \
  "https://api.recoupable.dev/api/emails"

→ {"success":true,"message":"Email sent successfully … to someone@example.com.","id":"<resend-id>"}

→ {"success":true,"message":"Email sent successfully … to someone@example.com.","id":"<resend-id>"}


`to` is a JSON array of email strings (`["a@b.com"]` — not a bare string, not
`[{"email":…}]`). The only keys are `to`, `cc`, `subject`, `text`, `html`,
`chat_id`, `account_id`; an unknown key (e.g. `recipients`) is dropped, and `to`
then defaults to your own account email — silently misrouting the message. `subject`
is optional. Read the response and check `message` names the recipient you intended.
No payment method on file → `to`/`cc` are limited to the account's own email (403).
To send as the user from their own Gmail instead, use `GMAIL_SEND_EMAIL`.

`to`为邮箱字符串组成的JSON数组（格式为`["a@b.com"]`——不能是单个字符串，也不能是`[{"email":…}]`）。仅支持以下键：`to`、`cc`、`subject`、`text`、`html`、`chat_id`、`account_id`；未知键（如`recipients`）会被忽略，此时`to`会默认设为当前账号邮箱——导致邮件被静默误发。`subject`为可选字段。请读取响应并确认`message`中显示的收件人为预期对象。若账号未绑定支付方式→`to`/`cc`仅能设置为当前账号邮箱（返回403错误）。如需以用户自身身份通过Gmail发送，请使用`GMAIL_SEND_EMAIL`操作。

Troubleshooting

故障排查

401 = token missing/expired (check the credential). 403 = no access to the org/artist. 404 = re-check the Docs map (endpoint moved/renamed). 5xx = retry once, then surface the status.
401 = 令牌缺失/过期（请检查凭证）。403 = 无权限访问该机构/艺人。404 = 请重新查阅文档映射（端点已迁移/重命名）。5xx = 重试一次，然后反馈状态码。

When NOT to use

不适用于以下场景

  • Files inside the sandbox → filesystem tools.
  • Onboarding/operating an artist's workspace → the recoup-roster-* skills.
  • A domain task (research/content/release/deal/song) → that domain skill, which makes its own calls.
  • 沙箱内的文件 → 使用文件系统工具。
  • 入驻或管理艺人工作区 → 使用recoup-roster-*系列技能。
  • 领域任务（调研/内容/发布/交易/歌曲） → 使用对应领域的技能，该类技能会自行完成调用。