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

Prefer authenticated MCP tools

Discover the host's Recoup MCP catalog first. Use a matching tool when its actual schema and results cover the requested operation. Prefixes vary by host. Use list_artists for roster discovery and bind subsequent requests to returned IDs. Do not infer that every REST endpoint or external connector has an MCP equivalent.

The host manages OAuth. Do not extract its token, ask for it, or put it into REST requests. A working MCP connection does not require environment variables. If only the limited catalog is available, reconnect with mcp:tools consent and refresh the host's tools. Do not initiate sends, publication, deletion or paid work merely because the tools are available.

For an operation absent from MCP, retain the documented REST workflow below. If REST credentials are missing, explain that specific limitation; do not claim the entire Recoup connection is broken or create a throwaway account.

REST fallback — one Bearer header, inline

Every REST 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 variable is set, use an applicable connected MCP tool or request separate REST setup for the missing capability. Do not retry unauthenticated.

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 the artist account_id (the current list id is its alias).
• 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 the artist account UUID for every /artists/{id}/* sub-resource. Current roster rows return that UUID in both account_id and id. Do not use an internal profile-row key, a Spotify ID or an opaque research ID. Verify older saved IDs against the current authenticated roster. 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, 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.