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

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.

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.

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

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 <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"
# → {"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

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.

recoup-platform-api-access

NPX Install

Tags

SKILL.md Content

Recoup — API Access

Auth — one Bearer header, inline

Pick the artist mode first (guessing here fabricates artists)

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

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

Send an email (from Recoup)

Troubleshooting

When NOT to use