Recoup — API Access

Recoup — API Access

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).

Auth — one Bearer header, inline

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.

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.

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 /​artists (your roster; org_id optional — orgs are often empty, so don't stop when organizations is []).

Use account_id, not the list id, for every /​artists/​{id}/​* sub-resource (socials/​posts/​fans key on account_id; the list's top-level id 404s). And socials are embedded in the /​artists response as account_socials (username, followerCount, profile_url) — read them there before calling /​artists/​{account_id}/​socials at all.

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.

Stop rule — never invent metrics/​data: report only figures you retrieved from a successful call this run. If a call errors or returns empty, or no connector exists for a metric (GET /​connectors/​actions → check isConnected), say so and omit it — never estimate, use "industry averages", or fill gaps with sample/​placeholder numbers. A short accurate report beats a padded, invented one.

Before you give up on missing data — get it, or hand back a connect link. When a metric's source isn't connected, work down this list before omitting:

1. Scrape the public data you can get — POST /​api/​socials/​{social_id}/​scrape (one profile) or POST /​api/​artist/​socials/​scrape (all of an artist's). Works for TikTok / Instagram / X / YouTube / Threads / Facebook. Report those real public numbers.
2. Check connection status — GET /​api/​connectors → each connector's isConnected.
3. Mint a connect link — POST /​api/​connectors {"connector":"youtube"} returns { redirectUrl } (a Composio OAuth URL). Surface it to the caller so the user can self-connect: "CPM/​revenue needs YouTube Analytics — connect here: {redirectUrl}".

Return the real public data plus the connect link — that beats both a fabricated report and an empty/​omitted one.

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.:

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.

Connector actions (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".

Send an email (from Recoup)

POST /​api/​emails sends an email from Agent by Recoup <[email protected]> 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):

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 is a JSON array of email strings (["[email protected]"] — 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.

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.

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.