docs: add Research API and CLI reference (#85)

sidneyswift · sweetmantech · claude · web-flow · commit 6c6d19918158 · 2026-04-03T19:45:38.000-05:00
* docs: add Research API endpoints and CLI commands

Documentation-first spec for the `recoup research` primitive —
16 API endpoints under /api/research/ covering artist search,
metrics (14 platforms), audience demographics, cities, similar
artists, playlists, discography, career, insights, discovery,
genres, festivals, web search, and deep research.

CLI docs cover all subcommands with flags, workflow examples,
and links to the API reference. Provider-agnostic — no mention
of underlying data sources.

Made-with: Cursor

* fix: remove credit mentions, clean up ID descriptions

Follow the same pattern as other API endpoints — no credit
costs in descriptions. Remove "music industry database"
references. ID params just say "returned by the search
endpoint" without exposing the underlying provider.

Made-with: Cursor

* fix: name-based lookups — no IDs exposed to users

All research endpoints now accept an artist name, Recoup artist
ID (UUID), or numeric ID. The API resolves the artist internally.
Users never need to know about underlying provider IDs.

CLI docs updated to show name-based examples throughout.

Made-with: Cursor

* feat: add 6 missing research endpoints from chartmetric skill

Lookup by URL, Social URLs, Instagram Posts, Track details,
Playlist details, Curator details. Now at full parity with
every script in the chartmetric skill — 22 endpoints total.

Made-with: Cursor

* feat: add research templates — pre-built multi-step workflows

11 templates matching the chartmetric skill's advanced workflows:
full-report, playlist-pitching, tiktok-pipeline, tour-routing,
discovery, catalog-optimization, competitive-analysis,
viral-autopsy, market-expansion, collaboration-finder, and
release-timing.

Two new endpoints: GET /api/research/templates (list them) and
POST /api/research/run (execute one against an artist by name).
CLI: recoup research templates + recoup research run &lt;template&gt; "Artist"

Made-with: Cursor

* fix: scope artist name/ID rule to artist-scoped subcommands only

Per CodeRabbit review — discover, genres, festivals, and web
don't take an artist identifier.

Made-with: Cursor

* revert: remove templates and run endpoints

Templates belong in the skill layer, not the API. The research
API provides primitives — the skill teaches the agent how to
chain them for specific workflows.

Made-with: Cursor

* refactor: flat routes with query params to match Recoup API pattern

Replaced nested path params (/api/research/artist/{id}/stat/{source})
with flat routes and query params (/api/research/metrics?artist=Drake&amp;source=spotify).

Now consistent with how every other Recoup endpoint works. The
artist param accepts a name or UUID — the API resolves internally.

Made-with: Cursor

* fix: address CodeRabbit review feedback

- Genre description now points to GET /api/research/discover
- Added callbackSecret to securitySchemes (pre-existing gap)
- Added security: [] override for Slack webhook endpoint
- Documented valid --platform values for audience command
- Fixed all CLI endpoint references to use flat route format

Made-with: Cursor

* docs: clarify ResearchProxyResponse is intentionally untyped

Response shapes come from a third-party provider and vary by
endpoint. Concrete schemas will be added after the API
implementation is complete and response shapes are known.

Made-with: Cursor

* feat: add concrete response schemas for all research endpoints

35 typed schemas derived from Chartmetric API response analysis.
Responses are normalized — no provider-specific obj wrapper,
clean field names, typed properties.

Endpoints with known fields (search, cities, similar, playlists,
albums, tracks, insights, curator, discover, genres, festivals)
have concrete schemas. Endpoints with variable shapes (profile,
metrics, audience, career, instagram posts) have descriptions
with additionalProperties for flexibility.

Made-with: Cursor

* fix: consolidate repeated artist-ID guidance per review nitpick

Made-with: Cursor

* fix: add missing descriptions to required platform params

Made-with: Cursor

* feat: add people, extract, and enrich endpoints to docs

3 new POST endpoints:
- /api/research/people — search for music industry professionals
- /api/research/extract — scrape URLs into clean markdown
- /api/research/enrich — structured data enrichment with JSON schema

8 new response schemas, 3 MDX pages, CLI docs updated.
Total documented: 25 research endpoints.

Made-with: Cursor

* feat: add milestones, venues, rank, charts, radio to docs

5 new endpoints with OpenAPI schemas + MDX pages + CLI docs.
Total documented: 30 research endpoints.

Made-with: Cursor

* fix: replace Kaash Paige examples with Drake

Made-with: Cursor

* fix: address review feedback — CLI/spec mismatches and empty schemas

1. Fix track endpoint reference: GET /api/research/track (query param),
   not GET /api/research/track/{id} (path param)
2. Remove undocumented --tiktok-followers flag from discover CLI docs
3. Add missing --latest flag to charts CLI docs
4. Add missing --limit flag to discover CLI docs
5. Populate 8 empty response schemas with representative fields:
   ResearchProfileResponse, ResearchMetricsResponse,
   ResearchAudienceResponse, ResearchCareerResponse,
   ResearchTrackResponse, ResearchLookupResponse,
   ResearchInstagramPostsResponse, ResearchPlaylistResponse

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

* fix: tighten discover endpoint description to match actual params

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

* fix: add missing API reference links and correct path notation in CLI docs

- Add See link for search, discography, and reference data sections
- Fix playlist/curator references to use query params, not path params

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Sweets Sweetman &lt;sweetmantech@gmail.com&gt;
Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/api-reference/openapi.json b/api-reference/openapi.json
diff --git a/api-reference/research/albums.mdx b/api-reference/research/albums.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Albums'
+openapi: 'GET /api/research/albums'
+---
diff --git a/api-reference/research/audience.mdx b/api-reference/research/audience.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Audience Demographics'
+openapi: 'GET /api/research/audience'
+---
diff --git a/api-reference/research/career.mdx b/api-reference/research/career.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Career Timeline'
+openapi: 'GET /api/research/career'
+---
diff --git a/api-reference/research/charts.mdx b/api-reference/research/charts.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Charts'
+openapi: 'GET /api/research/charts'
+---
diff --git a/api-reference/research/cities.mdx b/api-reference/research/cities.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Listener Cities'
+openapi: 'GET /api/research/cities'
+---
diff --git a/api-reference/research/curator.mdx b/api-reference/research/curator.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Curator'
+openapi: 'GET /api/research/curator'
+---
diff --git a/api-reference/research/deep.mdx b/api-reference/research/deep.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Deep Research'
+openapi: 'POST /api/research/deep'
+---
diff --git a/api-reference/research/discover.mdx b/api-reference/research/discover.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Discover Artists'
+openapi: 'GET /api/research/discover'
+---
diff --git a/api-reference/research/enrich.mdx b/api-reference/research/enrich.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Enrich'
+openapi: 'POST /api/research/enrich'
+---
diff --git a/api-reference/research/extract.mdx b/api-reference/research/extract.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Extract URL'
+openapi: 'POST /api/research/extract'
+---
diff --git a/api-reference/research/festivals.mdx b/api-reference/research/festivals.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Festivals'
+openapi: 'GET /api/research/festivals'
+---
diff --git a/api-reference/research/genres.mdx b/api-reference/research/genres.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Genres'
+openapi: 'GET /api/research/genres'
+---
diff --git a/api-reference/research/insights.mdx b/api-reference/research/insights.mdx
@@ -0,0 +1,4 @@
+---
+title: 'AI Insights'
+openapi: 'GET /api/research/insights'
+---
diff --git a/api-reference/research/instagram-posts.mdx b/api-reference/research/instagram-posts.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Instagram Posts'
+openapi: 'GET /api/research/instagram-posts'
+---
diff --git a/api-reference/research/lookup.mdx b/api-reference/research/lookup.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Lookup by URL'
+openapi: 'GET /api/research/lookup'
+---
diff --git a/api-reference/research/metrics.mdx b/api-reference/research/metrics.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Platform Metrics'
+openapi: 'GET /api/research/metrics'
+---
diff --git a/api-reference/research/milestones.mdx b/api-reference/research/milestones.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Milestones'
+openapi: 'GET /api/research/milestones'
+---
diff --git a/api-reference/research/people.mdx b/api-reference/research/people.mdx
@@ -0,0 +1,4 @@
+---
+title: 'People Search'
+openapi: 'POST /api/research/people'
+---
diff --git a/api-reference/research/playlist.mdx b/api-reference/research/playlist.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Playlist'
+openapi: 'GET /api/research/playlist'
+---
diff --git a/api-reference/research/playlists.mdx b/api-reference/research/playlists.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Playlist Placements'
+openapi: 'GET /api/research/playlists'
+---
diff --git a/api-reference/research/profile.mdx b/api-reference/research/profile.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Artist Profile'
+openapi: 'GET /api/research/profile'
+---
diff --git a/api-reference/research/radio.mdx b/api-reference/research/radio.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Radio Stations'
+openapi: 'GET /api/research/radio'
+---
diff --git a/api-reference/research/rank.mdx b/api-reference/research/rank.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Artist Rank'
+openapi: 'GET /api/research/rank'
+---
diff --git a/api-reference/research/search.mdx b/api-reference/research/search.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Search'
+openapi: 'GET /api/research'
+---
diff --git a/api-reference/research/similar.mdx b/api-reference/research/similar.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Similar Artists'
+openapi: 'GET /api/research/similar'
+---
diff --git a/api-reference/research/track.mdx b/api-reference/research/track.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Track'
+openapi: 'GET /api/research/track'
+---
diff --git a/api-reference/research/tracks.mdx b/api-reference/research/tracks.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Tracks'
+openapi: 'GET /api/research/tracks'
+---
diff --git a/api-reference/research/urls.mdx b/api-reference/research/urls.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Social URLs'
+openapi: 'GET /api/research/urls'
+---
diff --git a/api-reference/research/venues.mdx b/api-reference/research/venues.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Venues'
+openapi: 'GET /api/research/venues'
+---
diff --git a/api-reference/research/web.mdx b/api-reference/research/web.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Web Search'
+openapi: 'POST /api/research/web'
+---
diff --git a/cli.mdx b/cli.mdx
diff --git a/docs.json b/docs.json

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +title: 'Albums'
 +openapi: 'GET /api/research/albums'
 +---