recoup-api

What this skill does

# Recoupable API

Call the Recoupable production API to fetch artist data, social metrics, org context, research, and to trigger platform operations.

- **Base URL:** `https://api.recoupable.com/api`
- **LLM-readable docs:** `https://developers.recoupable.com` — Mintlify site. Use `/llms.txt` for the endpoint index, `/llms-full.txt` for full content, and the OpenAPI JSONs listed below for machine-readable schemas.

## Authentication

Recoup accepts **either** credential — prefer the API key when both are present:

| Credential | Header | Where it comes from |
| --- | --- | --- |
| `RECOUP_API_KEY` (`recoup_sk_…`) | `-H "x-api-key: $RECOUP_API_KEY"` | API-key install (`recoup-setup`) / agent signup |
| `RECOUP_ACCESS_TOKEN` | `-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN"` | short-lived open-agents sandbox token |

Build an `AUTH` array once and reuse it on every call:

```bash
if [ -n "$RECOUP_API_KEY" ]; then
  AUTH=(-H "x-api-key: $RECOUP_API_KEY")
elif [ -n "$RECOUP_ACCESS_TOKEN" ]; then
  AUTH=(-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN")
else
  echo "No Recoup credential set — ask the user to authenticate; do not retry blindly." >&2
fi
# Use as:  curl -sS "${AUTH[@]}" "https://api.recoupable.com/api/artists/{id}/socials"
```

If neither is set, the user is not authenticated — tell them to sign in rather than retrying. (Examples further down use `Authorization: Bearer $RECOUP_ACCESS_TOKEN` directly; swap in `"${AUTH[@]}"` when you have an API key instead.)

## Working with an artist — pick the mode first

Before any artist task, decide **which of these the user means.** Guessing here is exactly what makes an agent fabricate an artist that doesn't exist (or invent a persona for one that does).

| Mode | The user means… | Trigger phrases | What to do |
| --- | --- | --- | --- |
| **A · Any artist (research)** | Look up *any* artist — not necessarily one of theirs | "research X", "how's X doing", "compare X and Y" | Use the **Research** endpoints (or the `recoup-artist-research` skill). Works off a name — no roster lookup needed. |
| **B · Browse my roster** | List the artists on *their* account | "my roster", "my artists", "who do I have", "pick one of my artists" | Run **Roster discovery** below, then present the list. |
| **C · A specific roster artist** | Act on one of *their* artists | "make content for `<name>`", "update `<name>`'s brand" | Run **Roster discovery**, match the name, capture `account_id` + row `id`. No match → they're not on the roster yet (offer Mode D). |
| **D · Add an artist** | Onboard a brand-new artist | "add / onboard / create artist X", "set up a new artist" | Use the `recoup-create-artist` skill (8-call chain). |

### Roster discovery (Modes B & C)

In an open-agents **sandbox with a populated `artists/` tree**, that filesystem is authoritative — use the `recoup-artist-workspace` skill instead of the API. Otherwise (an API-key install, or no `artists/` directory), enumerate from the API:

```bash
BASE="https://api.recoupable.com/api"   # AUTH set per the Authentication section above

# 1. Whose account is this credential? Sanity-check BEFORE trusting the roster.
curl -sS "${AUTH[@]}" "$BASE/accounts/id"            # -> {"accountId":"…"}

# 2. Organizations on the account
curl -sS "${AUTH[@]}" "$BASE/organizations" \
  | jq -r '.organizations[] | [.organization_id, .organization_name] | @tsv'

# 3a. Artists for one org (preferred when you know the org)
curl -sS "${AUTH[@]}" "$BASE/artists?org_id=$ORG_ID" \
  | jq -r '.artists[] | [.name, .account_id, .id] | @tsv'

# 3b. …or every artist the account can see (account-wide)
curl -sS "${AUTH[@]}" "$BASE/artists" \
  | jq -r '.artists[] | [.name, .account_id, .id] | @tsv'
```

**Verified field shapes** (live, 2026-06-07): each **org** row has `organization_id`, `organization_name`, and its own row `id` — pass the `organization_id` value as `org_id`. Each **artist** row has `name`, `account_id`, and a row `id`. Capture both artist ids: `account_id` is what content endpoints and `/api/artists/{…}/socials` want; the row `id` is the artist's primary key.

### Stop rule — never invent a roster

If `GET /accounts/id` resolves to an account whose email is `agent+…@recoupable.com` (check `GET /api/accounts/{accountId}`), **or** `organizations` and `artists` both come back empty (`[]`), you are almost certainly on a throwaway / agent-signup key — **not** the user's real account. **Stop and say so:** name the resolved `accountId` and ask the user for a key tied to their real account (or to run `recoup-setup`). Do **not** fabricate an artist, persona, EP, or roster to keep the task moving — an empty roster is a credential problem to surface, not a blank canvas to fill.

## Org scoping (`RECOUP_ORG_ID`)

When running inside a sandbox, the environment also exposes `RECOUP_ORG_ID` — the organization the sandbox was opened for. The access token is account-scoped (it covers every org the account belongs to), so when you use it with unscoped list endpoints like `GET /api/artists` you will get results from **all** of that account's orgs, not just the one this sandbox represents. That mismatch surprises accounts.

When `RECOUP_ORG_ID` is set, scope list/query endpoints to it:

```bash
# Artists for this sandbox's org only
curl -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  "https://api.recoupable.com/api/organizations/$RECOUP_ORG_ID/artists"
```

For the Recoup CLI, pass `--org "$RECOUP_ORG_ID"` on commands that accept it. If `RECOUP_ORG_ID` is unset, you are not in an open-agents sandbox — fall back to account-scoped calls as normal.

**Inventory — filesystem first, API fallback:** inside an open-agents sandbox that has a populated `artists/` tree, prefer reading that local tree instead of calling the API — the filesystem is authoritative for the sandbox (see the `recoup-artist-workspace` skill). **But if there is no `artists/` directory** — e.g. an API-key install outside a sandbox — the filesystem can't answer, so fall back to **Roster discovery** above. Never conclude "the roster is empty" from an empty/missing filesystem; confirm against the API first.

## Docs Map

The full endpoint surface is organized into the sections below. Use this map to pick the right area, then pull the detailed docs for just that area (see [Finding an endpoint](#finding-an-endpoint)) instead of fetching everything.

### Account & Identity

- **Accounts** — create/get/update accounts, add artists to account
- **Organizations** — create/list orgs, add artists to org
- **Workspaces** — create workspaces
- **Subscriptions** — get subscriptions, create Stripe checkout session
- **Agents** — agent signup, email verification
- **Admins** — admin-only: agent sign-ups, coding/content agent Slack tags, Resend emails, Privy logins, sandbox stats, org repo commit stats

### Artists & Content

- **Artists** — create/get/delete, get socials, pin/unpin, get profile (across all platforms), trigger socials scrape
- **Posts** — get artist posts across platforms
- **Comments** — get comments for an artist or a specific post
- **Fans** — get social profiles of an artist's fans
- **Songs** — create/get songs by ISRC, manage catalogs (CRUD + add/remove songs), analyze songs via audio LM, list analyze presets
- **Content Creation** — pipeline trigger, video/image/caption generation, ffmpeg edits, video analysis, upscale, cost estimate, audio transcription, templates

### Research (Songstats + Web)

One section covering most music-industry lookup work. Backed by **Songstats** — entity IDs are short alphanumeric strings (e.g. `wjcgfd9i`), not numeric Chartmetric IDs:

- **Discovery**: search (`type=artists|tracks|labels`), profile, similar artists, people search, lookup by URL
- **Catalog**: albums, tracks, track detail, track playlists
- **Metrics**: platform metrics (16 sources), audience demographics, career timeline, milestones
- **Surface**: playlist placements
- **Insights**: AI insights, social URLs
- **Web**: enric