recoup-create-artist

What this skill does

# Create New Artist

The canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a brand-new artist account up to "researched + enriched" parity from a sandbox or any external agent.

The chain is **8 sequential API calls**. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. Drive the work from the `RECOUP.md` checklist file scaffolded by the [`recoup-artist-workspace`](https://github.com/recoupable/skills/tree/main/plugins/recoup-essentials/skills/recoup-artist-workspace) skill: tick each box and persist captured values back to the frontmatter as you go. The file IS the workflow state, and a fresh turn can resume by reading it.

## Prerequisites

- `$RECOUP_ACCESS_TOKEN` — Bearer token for `api.recoupable.com`
- `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes)
- An artist name to create (e.g. `ARTIST_NAME="The Weeknd"`)
- The artist's `RECOUP.md` already scaffolded (see `recoup-artist-workspace` skill, Step 0)

The flow has three phases, all driven from the single checklist file:

1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match
2. **Enrich** — `PATCH` the artist with image/label/socials, then run structured research (Songstats profile/career/playlists) plus a web search for narrative context and additional socials
3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array

**Don't run this chain under a throwaway `agent+` account.** Artist data created against an `[email protected]` email is permanently isolated to that account and can't be recovered if the API key is lost. Only run after the user has authenticated with their real email.

## Resuming a partial setup

If `$ARTIST_DIR/RECOUP.md` already exists, do not re-scaffold and do not re-run completed steps. Read the file, find the first unchecked item, and resume from there using the values already saved in the frontmatter:

```bash
# Show the next unchecked step
grep -n '^- \[ \]' "$ARTIST_DIR/RECOUP.md" | head -1
```

If every item is checked, the artist is fully set up — confirm with the user before doing anything else.

## Step 1: Create the artist

```bash
ARTIST_RESPONSE=$(curl -sS -X POST "https://api.recoupable.com/api/artists" \
  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg name "$ARTIST_NAME" --arg org "$RECOUP_ORG_ID" \
        '{name: $name, organization_id: $org}')")

ARTIST_ID=$(echo "$ARTIST_RESPONSE" | jq -r '.artist.account_id')
```

Capture `account_id` as `$ARTIST_ID` — every subsequent step needs it. `organization_id` is optional but should be included when running inside a sandbox so the artist is scoped to the right org.

Full request/response schema: `https://developers.recoupable.com/api-reference/artists/create`.

**After this step:** write `artistId: $ARTIST_ID` into the frontmatter and tick `- [ ] 1.` → `- [x] 1.` in `RECOUP.md`.

## Step 2: Find the canonical Spotify match

```bash
SPOTIFY=$(curl -sS -G "https://api.recoupable.com/api/spotify/search" \
  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  --data-urlencode "q=$ARTIST_NAME" \
  --data-urlencode "type=artist" \
  --data-urlencode "limit=10")
```

Pick the best match: prefer an exact case-insensitive name match; if multiple, prefer the highest popularity score. Export the fields the rest of the chain needs:

```bash
MATCH=$(echo "$SPOTIFY" | jq --arg name "$ARTIST_NAME" '
  .artists.items
  | (map(select((.name | ascii_downcase) == ($name | ascii_downcase))) | sort_by(-.popularity) | first)
    // (sort_by(-.popularity) | first)
')

SPOTIFY_ARTIST_ID=$(echo "$MATCH" | jq -r '.id // empty')
SPOTIFY_PROFILE_URL=$(echo "$MATCH" | jq -r '.external_urls.spotify // empty')
SPOTIFY_IMAGE_URL=$(echo "$MATCH" | jq -r '.images[0].url // empty')

[ -n "$SPOTIFY_ARTIST_ID" ] || { echo "No Spotify match for $ARTIST_NAME"; exit 1; }
```

Also keep `genres`, `followers.total`, and `popularity` from `$MATCH` for the KB report later.

Full schema: `https://developers.recoupable.com/api-reference/spotify/search`.

**After this step:** write `spotifyArtistId`, `spotifyProfileUrl`, and `imageUrl` into the frontmatter, save `genres` / `followers.total` / `popularity` to the `## Notes` section, and tick `- [ ] 2.` → `- [x] 2.`.

## Step 3: Set basic profile + Spotify URL

One `PATCH` covers the image and the Spotify social URL. Use **uppercase** platform keys in `profileUrls` (the API matches platforms case-sensitively — see the platform key reference at the bottom of this file).

```bash
curl -sS -X PATCH "https://api.recoupable.com/api/artists/$ARTIST_ID" \
  -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg image "$SPOTIFY_IMAGE_URL" --arg url "$SPOTIFY_PROFILE_URL" \
        '{image: $image, profileUrls: {SPOTIFY: $url}}')"
```

This single endpoint replaces what the chat tool chain runs as four separate MCP calls (`update_account_info` ×2, `update_artist_socials` ×2). Add `label` to the body if you discover one (e.g. from the step 4e web search or press) — the structured `profile` endpoint does **not** return a label field. Full body schema: `https://developers.recoupable.com/api-reference/artists/update`.

**After this step:** tick `- [ ] 3.` → `- [x] 3.`.

## Step 4: Run structured research

Don't use `POST /api/research/deep` here — it tends to hang in sandboxes and returns paraphrased prose. Instead, fan out across four bounded structured endpoints (one prerequisite lookup + three structured pulls + one web search). The outputs are typed JSON the agent can use directly without paraphrasing.

**Retry transient misses.** The research endpoints sit behind a cache/refresh layer — a *cold* call can come back `status: "error"` (or `202`) and then succeed on retry. Treat any non-`success` response as transient and retry once or twice before giving up, so a cold miss doesn't silently write empty research into the workspace. Use this helper for the GET pulls below:

```bash
research_get() {  # usage: research_get <endpoint> [curl -G args...]
  local ep="$1"; shift
  local out=""
  for attempt in 1 2 3; do
    out=$(curl -sS --max-time 90 -G "https://api.recoupable.com/api/research/$ep" \
      -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" "$@")
    [ "$(echo "$out" | jq -r '.status // "error"')" = "success" ] && { echo "$out"; return 0; }
    sleep 3
  done
  echo "$out"; return 1   # last non-success body; caller logs it and leaves the box unchecked
}
```

### 4a: Look up the provider `artist_id` (Songstats)

Most of the structured research endpoints take the research provider's `artist_id` — a short alphanumeric Songstats id like `wjcgfd9i`, **not** the Spotify ID. Resolve it once (from `artist_info.songstats_artist_id`) and reuse it for the rest of step 4.

```bash
LOOKUP=$(research_get lookup --data-urlencode "spotifyId=$SPOTIFY_ARTIST_ID")

PROVIDER_ARTIST_ID=$(echo "$LOOKUP" | jq -r '.artist_info.songstats_artist_id // empty')

[ -n "$PROVIDER_ARTIST_ID" ] || { echo "No provider match for Spotify ID $SPOTIFY_ARTIST_ID — skipping structured research"; }
```

If the lookup fails (rare — most Spotify-discoverable artists have a provider profile), skip 4b–4d and just run 4e (web search). Full schema: `https://developers.recoupable.com/api-reference/research/lookup`.

### 4b: Pull the artist profile

Returns bio, genres, country, social/streaming URLs (`links`), related artists, and avatar. Note: it does **not** return label, career stage, or follower/listener metrics — pull those from `/api/research/metrics` or the web search if you need them.

```bash
PROFILE=$(research_get profile --data-urlencode "id=$PROVIDER_ARTIST_ID")
```

Full schema: `https://developers.recoupable.com/api-reference/research