Skip to content

Update research docs for provider-neutral IDs #232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 8 commits into from
Jun 4, 2026
Merged

Update research docs for provider-neutral IDs #232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a491c79
Update research docs for provider-neutral IDs
sidneyswift Jun 3, 2026
2ef5fb7
Document unsupported research data responses
sidneyswift Jun 3, 2026
dd794ff
fix: align research OpenAPI review feedback
sidneyswift Jun 3, 2026
ee29c13
docs: include SongStats radio metric sources
sidneyswift Jun 3, 2026
5e356ce
docs: clarify related artist research
sidneyswift Jun 3, 2026
65855af
docs: document research metrics refresh pending
sidneyswift Jun 3, 2026
985be19
docs: remove Chartmetric-only research endpoints (SongStats-only)
sweetmantech Jun 4, 2026
531de15
docs: drop dead beta/platforms search params (Chartmetric-only)
sweetmantech Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1,781 changes: 497 additions & 1,284 deletions api-reference/openapi/research.json
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 0 additions & 4 deletions api-reference/research/charts.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/cities.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/curator.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/discover.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/festivals.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/genres.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/instagram-posts.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/playlist.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/radio.mdx
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/research/venues.mdx
View file
Open in desktop

This file was deleted.

24 changes: 2 additions & 22 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,6 @@
"pages": [
"api-reference/research/metrics",
"api-reference/research/audience",
"api-reference/research/cities",
"api-reference/research/genres",
"api-reference/research/insights",
"api-reference/research/career",
"api-reference/research/milestones",
Expand All @@ -125,33 +123,15 @@
]
},
{
"group": "Playlists & curators",
"group": "Playlists",
"pages": [
"api-reference/research/playlists",
"api-reference/research/playlist",
"api-reference/research/track-playlists",
"api-reference/research/curator"
]
},
{
"group": "Charts & radio",
"pages": [
"api-reference/research/charts",
"api-reference/research/radio",
"api-reference/research/discover"
]
},
{
"group": "Touring & live",
"pages": [
"api-reference/research/festivals",
"api-reference/research/venues"
"api-reference/research/track-playlists"
]
},
{
"group": "Web & social",
"pages": [
"api-reference/research/instagram-posts",
"api-reference/research/web",
"api-reference/research/deep",
"api-reference/research/people",
Expand Down
24 changes: 12 additions & 12 deletions workflows/create-artist.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The chain is 8 sequential API calls. Long deterministic chains executed from pro
The flow has three phases, run from a 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 (Chartmetric profile/career/playlists) plus a web search for narrative context and additional socials
2. **Enrich** — `PATCH` the artist with image/label/socials, then run structured research (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
Comment on lines +19 to 20

@coderabbitai coderabbitai Bot Jun 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Persist the label you now promise to enrich.

The updated phase summary says this workflow patches image, label, and socials, but the only later PATCH examples still write image/Spotify URL in step 3 and socials in step 7. The label discovered from /api/research/profile never gets written back to the artist, so the workflow doesn't actually reach the documented end state.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@workflows/create-artist.mdx` around lines 19 - 20, The workflow describes
enriching and patching image/label/socials but never persists the discovered
label; update the documentation examples (the PATCH shown in step 3 and/or the
later PATCH in step 7) to include writing the label field returned by
/api/research/profile back to the artist (e.g., add "label" or "recordLabel" in
the PATCH payload alongside image and Spotify URL), and ensure the synthesized
knowledge persistence (knowledges array update) also references the label where
appropriate so the workflow's end state reflects the documented enrichment.


## Step 0: Scaffold the workspace BEFORE any API call
Expand All @@ -36,7 +36,7 @@ artistId:
spotifyArtistId:
spotifyProfileUrl:
imageUrl:
cmArtistId:
researchArtistId:
---

# $ARTIST_NAME
Expand All @@ -46,7 +46,7 @@ cmArtistId:
- [ ] 1. Create the artist (\`POST /api/artists\`) — capture \`account_id\` → \`artistId\`
- [ ] 2. Find canonical Spotify match (\`GET /api/spotify/search\`) — capture \`id\`, \`external_urls.spotify\`, \`images[0].url\`
- [ ] 3. PATCH artist with image + Spotify profile URL
- [ ] 4. Structured research — \`/research/lookup\` (capture \`cmArtistId\`) → \`/research/profile\` + \`/research/career\` + \`/research/playlists\` + \`/research/web\`. Save responses under \`## Research\` in this file.
- [ ] 4. Structured research — \`/research/lookup\` (capture \`researchArtistId\`) → \`/research/profile\` + \`/research/career\` + \`/research/playlists\` + \`/research/web\`. Save responses under \`## Research\` in this file.
- [ ] 5. Pull Spotify catalog → write \`releases/{album-slug}/RELEASE.md\` per album + \`releases/top-tracks.md\`
- [ ] 6. Web search for additional socials (instagram / tiktok / twitter / youtube)
- [ ] 7. PATCH artist with discovered socials
Expand Down Expand Up @@ -141,21 +141,21 @@ This single endpoint replaces what the chat tool chain runs as four separate MCP

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.

### 4a: Look up the Chartmetric `artist_id`
### 4a: Look up the research artist ID

Most of the structured research endpoints take a Chartmetric `artist_id`, not the Spotify ID. Resolve it once and reuse it for the rest of step 4.
Most structured research endpoints can take the provider artist ID, not the Spotify ID. Resolve it once and reuse it for the rest of step 4.

```bash
LOOKUP=$(curl -sS -G "https://api.recoupable.com/api/research/lookup" \
-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
--data-urlencode "spotifyId=$SPOTIFY_ARTIST_ID")

CM_ARTIST_ID=$(echo "$LOOKUP" | jq -r '.artist.id // empty')
RESEARCH_ARTIST_ID=$(echo "$LOOKUP" | jq -r '.id // .artist.id // .data.id // empty')

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

If the lookup fails (rare — most Spotify-discoverable artists have a Chartmetric profile), skip 4b–4d and just run 4e (web search). See [Artist Lookup](/api-reference/research/lookup) for the request/response schema.
If the lookup fails, skip 4b–4d and just run 4e (web search). See [Artist Lookup](/api-reference/research/lookup) for the request/response schema.
Comment on lines +155 to +158

@coderabbitai coderabbitai Bot Jun 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Make the “skip 4b–4d” path executable.

Right now the doc says to skip 4b-4d when lookup returns no RESEARCH_ARTIST_ID, but the next three snippets still unconditionally call /research/profile, /research/career, and /research/playlists with an empty id. That turns the documented fallback into a guaranteed run of 400s for agents following the page linearly.

Suggested guard 
 RESEARCH_ARTIST_ID=$(echo "$LOOKUP" | jq -r '.id // .artist.id // .data.id // empty')

-[ -n "$RESEARCH_ARTIST_ID" ] || { echo "No structured research match for Spotify ID $SPOTIFY_ARTIST_ID — skipping structured research"; }
+if [ -z "$RESEARCH_ARTIST_ID" ]; then
+  echo "No structured research match for Spotify ID $SPOTIFY_ARTIST_ID — skipping 4b-4d"
+else
+  PROFILE=$(curl -sS -G "https://api.recoupable.com/api/research/profile" \
+    -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
+    --data-urlencode "id=$RESEARCH_ARTIST_ID")
+
+  CAREER=$(curl -sS -G "https://api.recoupable.com/api/research/career" \
+    -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
+    --data-urlencode "id=$RESEARCH_ARTIST_ID")
+
+  PLAYLISTS=$(curl -sS -G "https://api.recoupable.com/api/research/playlists" \
+    -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
+    --data-urlencode "id=$RESEARCH_ARTIST_ID")
+fi
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
[ -n "$RESEARCH_ARTIST_ID" ] || { echo "No structured research match for Spotify ID $SPOTIFY_ARTIST_ID — skipping structured research"; }
```
If the lookup fails (rare — most Spotify-discoverable artists have a Chartmetric profile), skip 4b–4d and just run 4e (web search). See [Artist Lookup](/api-reference/research/lookup) for the request/response schema.
If the lookup fails, skip 4b–4d and just run 4e (web search). See [Artist Lookup](/api-reference/research/lookup) for the request/response schema.
RESEARCH_ARTIST_ID=$(echo "$LOOKUP" | jq -r '.id // .artist.id // .data.id // empty')
if [ -z "$RESEARCH_ARTIST_ID" ]; then
echo "No structured research match for Spotify ID $SPOTIFY_ARTIST_ID — skipping 4b-4d"
else
PROFILE=$(curl -sS -G "https://api.recoupable.com/api/research/profile" \
-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
--data-urlencode "id=$RESEARCH_ARTIST_ID")
CAREER=$(curl -sS -G "https://api.recoupable.com/api/research/career" \
-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
--data-urlencode "id=$RESEARCH_ARTIST_ID")
PLAYLISTS=$(curl -sS -G "https://api.recoupable.com/api/research/playlists" \
-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
--data-urlencode "id=$RESEARCH_ARTIST_ID")
fi
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@workflows/create-artist.mdx` around lines 155 - 158, The docs currently
instruct skipping steps 4b–4d when RESEARCH_ARTIST_ID is empty but the snippets
still call /research/profile, /research/career, and /research/playlists
unconditionally; guard those API calls so they only run when RESEARCH_ARTIST_ID
is set. Wrap the three calls to /research/profile, /research/career, and
/research/playlists in a conditional that checks [ -n "$RESEARCH_ARTIST_ID" ]
(or equivalent) and otherwise jump directly to step 4e (web search) so agents
won’t send empty-id requests.


### 4b: Pull the artist profile

Expand All @@ -164,7 +164,7 @@ Returns bio, genres, social URLs, label, career stage, and basic metrics — mos
```bash
PROFILE=$(curl -sS -G "https://api.recoupable.com/api/research/profile" \
-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
--data-urlencode "id=$CM_ARTIST_ID")
--data-urlencode "id=$RESEARCH_ARTIST_ID")
```

See [Artist Profile](/api-reference/research/profile) for the response schema.
Expand All @@ -176,7 +176,7 @@ Career milestones, trajectory, and career-stage classification — covers the "n
```bash
CAREER=$(curl -sS -G "https://api.recoupable.com/api/research/career" \
-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
--data-urlencode "id=$CM_ARTIST_ID")
--data-urlencode "id=$RESEARCH_ARTIST_ID")
```

See [Career Timeline](/api-reference/research/career) for the response schema.
Expand All @@ -188,7 +188,7 @@ Replaces the "playlists / radio rotations / editorial features" portion of the d
```bash
PLAYLISTS=$(curl -sS -G "https://api.recoupable.com/api/research/playlists" \
-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
--data-urlencode "id=$CM_ARTIST_ID")
--data-urlencode "id=$RESEARCH_ARTIST_ID")
```

See [Artist Playlists](/api-reference/research/playlists) for the response schema.
Expand All @@ -207,7 +207,7 @@ RESEARCH_WEB=$(curl -sS -X POST "https://api.recoupable.com/api/research/web" \

See [Web Search](/api-reference/research/web) for the request/response schema.

**After this step:** persist `cmArtistId: $CM_ARTIST_ID` into the frontmatter, save the four response payloads (profile, career, playlists, web) into a new `## Research` section of `RECOUP.md` — one subsection per endpoint, each with the raw JSON or a tight markdown summary so step 8 can compose from it. Tick `- [ ] 4.` → `- [x] 4.`.
**After this step:** persist `researchArtistId: $RESEARCH_ARTIST_ID` into the frontmatter, save the four response payloads (profile, career, playlists, web) into a new `## Research` section of `RECOUP.md` — one subsection per endpoint, each with the raw JSON or a tight markdown summary so step 8 can compose from it. Tick `- [ ] 4.` → `- [x] 4.`.

## Step 5: Pull the Spotify catalog

Expand Down