Open
Conversation
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
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a new "research" API namespace with multiple GET/POST endpoints and related OpenAPI schemas, two content-agent endpoints including a callback guarded by a Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant ResearchAPI as Research API
participant WebProxy as External Web / Proxy
participant AIService as AI / Analysis
participant DB as Database
Client->>ResearchAPI: POST /api/research/web (ResearchWebRequest)
ResearchAPI->>WebProxy: fetch/crawl URLs
WebProxy-->>ResearchAPI: raw content / extracted text
ResearchAPI->>AIService: analyze & synthesize content
AIService-->>ResearchAPI: ResearchWebResponse
ResearchAPI->>DB: store result (optional)
ResearchAPI-->>Client: 200 ResearchWebResponse
alt deep research flow
Client->>ResearchAPI: POST /api/research/deep (ResearchDeepRequest)
ResearchAPI->>WebProxy: multi-source aggregation
WebProxy-->>ResearchAPI: aggregated data
ResearchAPI->>AIService: multi-step analysis
AIService-->>ResearchAPI: ResearchDeepResponse
ResearchAPI-->>Client: 200 ResearchDeepResponse
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
api-reference/openapi.json (1)
11740-11857:⚠️ Potential issue | 🔴 CriticalMove the
Research*schemas undercomponents.schemasand restorecallbackSecrettocomponents.securitySchemes.All six
Research*schema definitions are currently direct children ofcomponentsinstead of nested undercomponents.schemas, causing their$refpointers (#/components/schemas/Research*) to fail resolution. Additionally,callbackSecretis missing fromcomponents.securitySchemes, butPOST /api/content-agent/callbackstill references it. This breaks OpenAPI spec validation and prevents the research pages from rendering correctly.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 11740 - 11857, The Research* schemas (ResearchSearchResponse, ResearchProxyResponse, ResearchWebRequest, ResearchWebResponse, ResearchDeepRequest, ResearchDeepResponse) are placed directly under components; move all six schema objects into components.schemas so their $ref paths (`#/components/schemas/Research`*) resolve, and re-add the callbackSecret definition under components.securitySchemes (matching the existing scheme shape used by POST /api/content-agent/callback) so the referenced security scheme is present.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 5249-5252: Update the description for the OpenAPI path
"/api/research/genre" to point to the actual discover operation: replace the
reference to the nonexistent "/api/research/discover" with the real route
"/api/research/artist/list/filter" so users know to use genre IDs with GET
/api/research/artist/list/filter; ensure the description text still mentions
credits and purpose (list genre IDs/names) but references
"/api/research/artist/list/filter" as the intended discover surface.
- Around line 5055-5073: Remove the meaningless "default" fields from the
required path parameter definitions for "platform" and "status" in the OpenAPI
spec: locate the parameter objects named "platform" and "status" (each has "in":
"path", "required": true and an "enum") and delete their "default" entries so
the parameters remain required without providing a default value.
In `@cli.mdx`:
- Around line 194-214: Update the Playlists CLI docs to match the OpenAPI spec:
remove the unsupported `--editorial` and `--since` examples and table rows, and
change the example `recoup research playlists <id> --status past --since
2025-01-01` to just `recoup research playlists <id> --status past`; ensure the
remaining flags table only lists `--platform <p>` (path handled), `--status <s>`
(path handled), `--sort <field>`, and `--limit <n>` so examples and the
description for the Playlists section align with the API which only supports
`limit` and `sort` as query parameters.
- Around line 178-182: Update the "audience <id>" CLI docs to explicitly
document the --platform flag and its allowed values; state that the default is
instagram and list the valid options as `instagram`, `tiktok`, and `youtube`
(the same tokens used in the API path `{platform}-audience-stats`), and add a
short note beside the API endpoint row clarifying the default behavior when
--platform is omitted.
---
Outside diff comments:
In `@api-reference/openapi.json`:
- Around line 11740-11857: The Research* schemas (ResearchSearchResponse,
ResearchProxyResponse, ResearchWebRequest, ResearchWebResponse,
ResearchDeepRequest, ResearchDeepResponse) are placed directly under components;
move all six schema objects into components.schemas so their $ref paths
(`#/components/schemas/Research`*) resolve, and re-add the callbackSecret
definition under components.securitySchemes (matching the existing scheme shape
used by POST /api/content-agent/callback) so the referenced security scheme is
present.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 53ccdfdd-3172-458d-aad8-c8ad46634499
📒 Files selected for processing (19)
api-reference/openapi.jsonapi-reference/research/albums.mdxapi-reference/research/audience.mdxapi-reference/research/career.mdxapi-reference/research/cities.mdxapi-reference/research/deep.mdxapi-reference/research/discover.mdxapi-reference/research/festivals.mdxapi-reference/research/genres.mdxapi-reference/research/insights.mdxapi-reference/research/metrics.mdxapi-reference/research/playlists.mdxapi-reference/research/profile.mdxapi-reference/research/search.mdxapi-reference/research/similar.mdxapi-reference/research/tracks.mdxapi-reference/research/web.mdxcli.mdxdocs.json
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
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (2)
cli.mdx (2)
176-179:⚠️ Potential issue | 🟡 MinorDocument valid
--platformvalues foraudience.The table says “Instagram default” but still doesn’t list accepted values (
tiktok,youtube), so users can’t reliably discover valid inputs from CLI docs alone.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cli.mdx` around lines 176 - 179, Update the CLI docs for the audience subcommand to explicitly list valid --platform values and the default: amend the `audience <id>` row (and any related help text for the audience command) to show accepted values: `instagram`, `tiktok`, `youtube` and indicate the default is `instagram`; reference the `audience <id>` subcommand and the `--platform` flag so users can discover inputs from the docs.
194-200:⚠️ Potential issue | 🟠 MajorRemove unsupported playlists flags to match the API and CLI behavior.
--editorialand--sinceare still documented (and used in the workflow example), but the playlists endpoint contract only supports query params likelimitandsortwhileplatform/statusare path-driven selections. This will mislead users into failing commands.Suggested doc diff
```bash recoup research playlists <id> recoup research playlists <id> --platform applemusic -recoup research playlists <id> --editorial -recoup research playlists <id> --status past --since 2025-01-01 +recoup research playlists <id> --status past recoup research playlists <id> --sort followers --limit 50
Flag Description --platform <p>spotify(default),applemusic,deezer,amazon,youtube- --editorial--status <s>current(default) orpast- --since <date>--sort <field>Sort results (e.g., followers)--limit <n>Max results @@ -recoup research playlists 241089 --editorial --json +recoup research playlists 241089 --status current --json </details> Also applies to: 202-209, 281-281 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@cli.mdxaround lines 194 - 200, Remove the unsupported --editorial and
--since flags from the playlists docs and examples and replace their usage with
the path-driven --status flag (e.g., use --status current or --status past);
update all example commands (e.g., the block showing "recoup research playlists
" and the example "recoup research playlists 241089 ...") and the flags
table to delete the--editorialand--since <date>entries and ensure
remaining flags include--platform,--status,--sort, and--limitso the
documented CLI matches the playlists endpoint contract.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@api-reference/openapi.json:
- Around line 11757-11760: The OpenAPI schema ResearchProxyResponse is an empty
object so all endpoints (profile, metrics, audience, cities, similarArtists,
playlists, albums, tracks, career, insights, genre, festival) are being
published as opaque objects; update openapi.json to replace the empty
"properties": {} for ResearchProxyResponse with concrete response schemas (or a
discriminated oneOf/anyOf) that match each endpoint's actual response shape, or
create separate named schemas (e.g., ProfileResponse, MetricsResponse,
AudienceResponse, CitiesResponse, SimilarArtistsResponse, PlaylistsResponse,
AlbumsResponse, TracksResponse, CareerResponse, InsightsResponse, GenreResponse,
FestivalResponse) and reference them from the respective paths so generated
clients and Mintlify receive typed responses instead of {}.- Around line 4861-4878: The OpenAPI Search endpoint documents that returned IDs
can be used in other research endpoints but the response schema doesn't declare
an id nor does the parameter "type" restrict results to artists; update the
search operation's response schema to include an explicit "id" (integer or
string as used by the research endpoints) and, depending on intended behavior,
either (a) restrict the "type" enum/default to "artists" if only artist IDs are
valid for the /{id} research routes, or (b) add a discriminated response schema
(or per-type items) that documents the ID field and its type for each allowed
entity ("artists", "tracks", etc.) so callers know which ID form the /{id}
endpoints expect (also apply the same fix at the other occurrence noted).- Around line 5195-5234: The endpoint description promises follower-count and
growth-rate filtering but the OpenAPI parameters array for the "Discover artists
by criteria" operation only lists country, genre, sp_monthly_listeners_min,
sp_monthly_listeners_max, sort, and limit; either add the missing query
parameters (e.g., follower_count_min, follower_count_max, growth_rate_min,
growth_rate_max with appropriate "in":"query", "schema":{"type":"integer" or
"number"}, descriptions and required:false) to the parameters array or update
the operationdescriptionto remove mention of follower-count and growth-rate
so docs match the actual parameters; ensure changes are made in openapi.json
next to the existing parameter entries (country, genre,
sp_monthly_listeners_min, sp_monthly_listeners_max, sort, limit).In
@cli.mdx:
- Line 130: Replace the provider-specific phrase "Find an artist in the music
industry database. Returns an ID you can use with all other research commands."
with provider-agnostic wording such as "Find an artist and return an ID for
other research commands." Locate the exact sentence in the CLI documentation
(the line containing "Find an artist in the music industry database...") and
update it to the new neutral phrasing, ensuring punctuation and capitalization
match surrounding entries.
Duplicate comments:
In@cli.mdx:
- Around line 176-179: Update the CLI docs for the audience subcommand to
explicitly list valid --platform values and the default: amend theaudience <id>row (and any related help text for the audience command) to show accepted
values:tiktok,youtubeand indicate the default is
audience <id>subcommand and the--platformflag
so users can discover inputs from the docs.- Around line 194-200: Remove the unsupported --editorial and --since flags from
the playlists docs and examples and replace their usage with the path-driven
--status flag (e.g., use --status current or --status past); update all example
commands (e.g., the block showing "recoup research playlists " and the
example "recoup research playlists 241089 ...") and the flags table to delete
the--editorialand--since <date>entries and ensure remaining flags
include--platform,--status,--sort, and--limitso the documented CLI
matches the playlists endpoint contract.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `583452c4-0d42-493d-b99b-1c8e064694a9` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 77f108e47aa26e2724ef093164208100ca7e0b60 and 32a041dba478f72afdf5938666b1a93ed96414f0. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `api-reference/openapi.json` * `cli.mdx` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
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
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (7)
api-reference/openapi.json (5)
5474-5477:⚠️ Potential issue | 🟡 MinorPoint genre guidance to the concrete discover route.
“Use these IDs with the discover endpoint” is ambiguous. Reference the exact operation path (
GET /api/research/artist/list/filter) to avoid dead-end navigation.📝 Proposed wording
- "description": "List all available genre IDs and names. Use these IDs with the discover endpoint.", + "description": "List all available genre IDs and names. Use these IDs with `GET /api/research/artist/list/filter`.",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 5474 - 5477, Update the description for the "/api/research/genre" GET operation to replace the vague "Use these IDs with the discover endpoint" with an explicit reference to the concrete operation path and method (e.g., "Use these IDs with GET /api/research/artist/list/filter") so callers can navigate directly to the correct discover route; modify the description string in the openapi.json entry for "/api/research/genre" accordingly.
12000-12003:⚠️ Potential issue | 🟠 Major
ResearchProxyResponseas{}keeps most research endpoints opaque.Many research endpoints still resolve to an empty-object schema, which weakens generated docs and SDK typing. Replace with concrete per-endpoint schemas (or a
oneOf/discriminated model) and reference those from each operation.Based on learnings, "Applies to **/openapi.json : Place all API descriptions, parameter documentation, and response schemas in openapi.json, not in MDX pages".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 12000 - 12003, The ResearchProxyResponse schema is currently an empty object which makes endpoint responses opaque; update the OpenAPI definitions by replacing "ResearchProxyResponse" with concrete response schemas or a discriminated oneOf union that enumerates each endpoint's response shape (or create distinct schemas like ResearchProxyResponseTypeA, ResearchProxyResponseTypeB and reference them). Then update each operation that currently references ResearchProxyResponse to reference the specific schema or the new oneOf discriminator; ensure you add clear property definitions and descriptions in the new schemas so generated docs and SDK typings are accurate.
5229-5256:⚠️ Potential issue | 🟡 MinorRemove
defaultfrom required path parameters.
platformandstatusare required path params; defaults are semantically misleading because path segments must always be provided.✂️ Proposed fix
{ "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "spotify", "applemusic", "deezer", "amazon", "youtube" - ], - "default": "spotify" + ] } }, { "name": "status", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "current", "past" - ], - "default": "current" + ] } },🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 5229 - 5256, The OpenAPI spec incorrectly sets "default" values for required path parameters "platform" and "status"; remove the "default" keys from the schema objects for the "platform" and "status" path parameters so the parameters remain required without misleading defaults (update the schema blocks for the parameters named platform and status).
4983-4998:⚠️ Potential issue | 🟠 MajorSearch response still does not document a usable ID contract.
typeallows multiple entity kinds, butResearchSearchResponse.resultsis an untyped object array and does not define required ID fields/types that downstream research routes expect. Either constrain search to artist results or define discriminated per-entity result schemas with explicit ID shape.As per coding guidelines, "Place all API descriptions, parameter documentation, and response schemas in openapi.json, not in MDX pages".
Also applies to: 11991-11997
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 4983 - 4998, ResearchSearchResponse currently returns an untyped results array while the query parameter "type" can be multiple entity kinds; update openapi.json to either (A) constrain the "type" query parameter to only "artists" and document that ResearchSearchResponse.results is an array of ArtistResult objects with a required id field of the expected type, or (B) implement discriminated union result schemas: create per-entity result components (e.g., ArtistResult, TrackResult, AlbumResult, PlaylistResult, CuratorResult, StationResult) each with a required id property and a "kind" discriminator, then change ResearchSearchResponse.results to use oneOf with the discriminator keyed to the "type" parameter so downstream research routes have a clear, typed id contract; make sure to add these response schema definitions in openapi.json (not in MDX) and reference the new components from ResearchSearchResponse.
5405-5458:⚠️ Potential issue | 🟡 MinorDiscover description overpromises unsupported filters.
The description advertises follower-count and growth-rate filtering, but those query params are not documented in this operation. Either add those parameters or tighten the description to match the current surface.
As per coding guidelines, "Place all API descriptions, parameter documentation, and response schemas in openapi.json, not in MDX pages".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 5405 - 5458, The operation description promises follower-count and growth-rate filters but the parameters list only contains country, genre, sp_monthly_listeners_min, sp_monthly_listeners_max, sort, and limit; update the OpenAPI entry so the description matches the documented params by either (A) removing references to "follower-count" and "growth-rate" from the description string, or (B) adding explicit query parameters (e.g., follower_count_min, follower_count_max, growth_rate_min, growth_rate_max) with appropriate "in":"query" and "schema":{"type":"integer" or "number"} entries; locate the operation that contains parameters country, genre, sp_monthly_listeners_min, sp_monthly_listeners_max, sort, and limit and apply the chosen change so description and parameter list are consistent.cli.mdx (2)
193-210:⚠️ Potential issue | 🟠 MajorRemove unsupported playlists flags from examples and flag table.
--editorialand--sinceare still documented for playlists (Lines 196-197, 204, 206, and workflow Line 284). This appears out of sync with the playlists API contract.Suggested doc cleanup
recoup research playlists "Drake" recoup research playlists "Drake" --platform applemusic -recoup research playlists "Drake" --editorial -recoup research playlists "Drake" --status past --since 2025-01-01 +recoup research playlists "Drake" --status past recoup research playlists "Drake" --sort followers --limit 50 @@ | Flag | Description | |------|-------------| | `--platform <p>` | `spotify` (default), `applemusic`, `deezer`, `amazon`, `youtube` | -| `--editorial` | Only editorial playlists | | `--status <s>` | `current` (default) or `past` | -| `--since <date>` | Filter by date (YYYY-MM-DD) | | `--sort <field>` | Sort results (e.g., `followers`) | | `--limit <n>` | Max results | @@ -recoup research playlists "Phoebe Bridgers" --editorial --json +recoup research playlists "Phoebe Bridgers" --status current --json#!/bin/bash set -euo pipefail echo "Playlists endpoint parameters:" jq '.paths["/api/research/artist/{id}/{platform}/{status}/playlists"].get.parameters | map({name, in, required})' api-reference/openapi.json echo echo "Audience endpoint parameters (for --platform validity):" jq '.paths["/api/research/artist/{id}/{platform}-audience-stats"].get.parameters | map({name, in, required, enum: (.schema.enum // null)})' api-reference/openapi.jsonAlso applies to: 279-285
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cli.mdx` around lines 193 - 210, The docs show unsupported flags --editorial and --since for the "recoup research playlists" command; remove these flags from the example usages, the flag table entries (`--editorial`, `--since`) and any workflow text that references them (the playlists workflow and the GET /api/research/artist/{id}/{platform}/{status}/playlists section) so examples and the table only list supported flags (`--platform`, `--status`, `--sort`, `--limit`) and match the API contract; update any example lines containing `recoup research playlists "Drake" --editorial` or `--since` to omit those flags.
175-178:⚠️ Potential issue | 🟡 MinorDocument valid
--platformvalues foraudience.Line 177 mentions the default platform but still doesn’t list allowed values. Add explicit values (
tiktok,youtube) for CLI correctness.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cli.mdx` around lines 175 - 178, Update the documentation for the "audience" subcommand to explicitly list the valid values for the --platform option (instagram, tiktok, youtube); specifically, modify the table row for the `audience` subcommand so its Description or a new column/parenthetical mentions the allowed --platform values and that the default is `instagram`, and ensure the API endpoint reference (`GET /api/research/artist/{id}/{platform}-audience-stats`) is kept in sync with those values.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 4962-4966: The OpenAPI document references "callbackSecret" in the
security requirement for the /api/content-agent/callback operation but never
declares it; add a corresponding security scheme named "callbackSecret" under
components.securitySchemes (e.g., a scheme object keyed as "callbackSecret")
that matches the intended auth type (for example "http" with scheme "bearer", or
"apiKey" in header/query, or "oauth2" as appropriate), and ensure its name,
type, and placement (header/query) reflect how the callback secret is expected
to be provided so the operation's security reference resolves correctly.
In `@cli.mdx`:
- Line 128: The documentation line stating "Every research command accepts an
artist name or a Recoup artist ID (UUID)" is too broad; update the sentence to
scope the artist-ID rule only to artist-scoped subcommands (e.g., the commands
that specifically operate on an artist like the artist-search/artist-details
subcommands) and explicitly exclude commands that do not accept an artist
identifier such as discover, genres, festivals, and web; modify the wording
around the existing sentence to say something like "Artist-scoped research
commands accept an artist name or a Recoup artist ID (UUID)..." and add a short
parenthetical or list naming the excluded commands (discover, genres, festivals,
web) so readers know which commands do not accept an artist identifier.
---
Duplicate comments:
In `@api-reference/openapi.json`:
- Around line 5474-5477: Update the description for the "/api/research/genre"
GET operation to replace the vague "Use these IDs with the discover endpoint"
with an explicit reference to the concrete operation path and method (e.g., "Use
these IDs with GET /api/research/artist/list/filter") so callers can navigate
directly to the correct discover route; modify the description string in the
openapi.json entry for "/api/research/genre" accordingly.
- Around line 12000-12003: The ResearchProxyResponse schema is currently an
empty object which makes endpoint responses opaque; update the OpenAPI
definitions by replacing "ResearchProxyResponse" with concrete response schemas
or a discriminated oneOf union that enumerates each endpoint's response shape
(or create distinct schemas like ResearchProxyResponseTypeA,
ResearchProxyResponseTypeB and reference them). Then update each operation that
currently references ResearchProxyResponse to reference the specific schema or
the new oneOf discriminator; ensure you add clear property definitions and
descriptions in the new schemas so generated docs and SDK typings are accurate.
- Around line 5229-5256: The OpenAPI spec incorrectly sets "default" values for
required path parameters "platform" and "status"; remove the "default" keys from
the schema objects for the "platform" and "status" path parameters so the
parameters remain required without misleading defaults (update the schema blocks
for the parameters named platform and status).
- Around line 4983-4998: ResearchSearchResponse currently returns an untyped
results array while the query parameter "type" can be multiple entity kinds;
update openapi.json to either (A) constrain the "type" query parameter to only
"artists" and document that ResearchSearchResponse.results is an array of
ArtistResult objects with a required id field of the expected type, or (B)
implement discriminated union result schemas: create per-entity result
components (e.g., ArtistResult, TrackResult, AlbumResult, PlaylistResult,
CuratorResult, StationResult) each with a required id property and a "kind"
discriminator, then change ResearchSearchResponse.results to use oneOf with the
discriminator keyed to the "type" parameter so downstream research routes have a
clear, typed id contract; make sure to add these response schema definitions in
openapi.json (not in MDX) and reference the new components from
ResearchSearchResponse.
- Around line 5405-5458: The operation description promises follower-count and
growth-rate filters but the parameters list only contains country, genre,
sp_monthly_listeners_min, sp_monthly_listeners_max, sort, and limit; update the
OpenAPI entry so the description matches the documented params by either (A)
removing references to "follower-count" and "growth-rate" from the description
string, or (B) adding explicit query parameters (e.g., follower_count_min,
follower_count_max, growth_rate_min, growth_rate_max) with appropriate
"in":"query" and "schema":{"type":"integer" or "number"} entries; locate the
operation that contains parameters country, genre, sp_monthly_listeners_min,
sp_monthly_listeners_max, sort, and limit and apply the chosen change so
description and parameter list are consistent.
In `@cli.mdx`:
- Around line 193-210: The docs show unsupported flags --editorial and --since
for the "recoup research playlists" command; remove these flags from the example
usages, the flag table entries (`--editorial`, `--since`) and any workflow text
that references them (the playlists workflow and the GET
/api/research/artist/{id}/{platform}/{status}/playlists section) so examples and
the table only list supported flags (`--platform`, `--status`, `--sort`,
`--limit`) and match the API contract; update any example lines containing
`recoup research playlists "Drake" --editorial` or `--since` to omit those
flags.
- Around line 175-178: Update the documentation for the "audience" subcommand to
explicitly list the valid values for the --platform option (instagram, tiktok,
youtube); specifically, modify the table row for the `audience` subcommand so
its Description or a new column/parenthetical mentions the allowed --platform
values and that the default is `instagram`, and ensure the API endpoint
reference (`GET /api/research/artist/{id}/{platform}-audience-stats`) is kept in
sync with those values.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 67121d38-e81e-4f36-8535-1e3d20d950e6
📒 Files selected for processing (2)
api-reference/openapi.jsoncli.mdx
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
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 <template> "Artist" Made-with: Cursor
Per CodeRabbit review — discover, genres, festivals, and web don't take an artist identifier. Made-with: Cursor
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
Replaced nested path params (/api/research/artist/{id}/stat/{source})
with flat routes and query params (/api/research/metrics?artist=Drake&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
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (5)
api-reference/openapi.json (4)
12271-12275:⚠️ Potential issue | 🟠 MajorMost research endpoints still publish
{}.
ResearchProxyResponseis still empty, so the profile/metrics/audience/cities/similar/urls/playlists/albums/tracks/career/insights/discover/genres/festivals routes all render as opaque JSON. Replace it with endpoint-specific schemas or at least aoneOfof concrete shapes. As per coding guidelines, "Place all API descriptions, parameter documentation, and response schemas in openapi.json, not in MDX pages".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 12271 - 12275, The ResearchProxyResponse schema is currently an empty object, leaving many research endpoints (profile, metrics, audience, cities, similar, urls, playlists, albums, tracks, career, insights, discover, genres, festivals) with opaque JSON responses; update openapi.json by replacing ResearchProxyResponse with concrete response schemas per endpoint (e.g., ResearchProfileResponse, ResearchMetricsResponse, etc.) or at minimum make ResearchProxyResponse a oneOf that references those concrete component schemas, and then update each endpoint's responses to reference the correct schema (use the component schema names such as ResearchProxyResponse, ResearchProfileResponse, ResearchMetricsResponse in the endpoints' response objects to ensure docs and validation are explicit).
4971-4998:⚠️ Potential issue | 🟠 MajorSearch still doesn't document a usable result shape.
The operation description is still artist-only,
typestill allows non-artist entities, andResearchSearchResponse.results[]is just an opaque object. Callers cannot tell whichidcomes back or which downstream endpoint it fits. Either narrow this to artists or publish a typed/discriminated result schema with explicitid,type,name, and basic metadata. As per coding guidelines, "Place all API descriptions, parameter documentation, and response schemas in openapi.json, not in MDX pages".Also applies to: 12251-12269
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 4971 - 4998, The search operation currently claims "Search for artists" but accepts a generic query parameter "type" and returns ResearchSearchResponse.results[] as an opaque object; update openapi.json so the operation and parameters align and the response is typed: either restrict the "type" enum to only "artists" and make the operation description and response schema explicitly ArtistSearchResponse with each result containing typed fields (id, type, name, and basic metadata), or define a discriminated union ResultsItem schema (with a required "type" discriminator and concrete sub-schemas for "artist"/"track"/etc) and replace ResearchSearchResponse.results[] with this schema; ensure the parameter "type" description matches the enforced enum and add explicit properties for id, type, name, and minimal metadata in the returned result schema so callers can map ids to downstream endpoints.
4962-4966:⚠️ Potential issue | 🔴 CriticalDefine the referenced
callbackSecretscheme.
callbackSecretis referenced here, butcomponents.securitySchemesstill only definesbearerAuthandapiKeyAuth. That leaves the spec invalid and the auth model unresolved.Verify by checking for a reference without a matching definition; expected result: the callback operation references
callbackSecret, butcomponents.securitySchemesdoes not declare it.#!/bin/bash python - <<'PY' import json from pathlib import Path doc = json.loads(Path("api-reference/openapi.json").read_text()) print("operation security:", doc["paths"]["/api/content-agent/callback"]["post"].get("security")) print("declared schemes:", sorted(doc["components"]["securitySchemes"].keys())) PY🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 4962 - 4966, The OpenAPI operation at paths["/api/content-agent/callback"].post references a security scheme named "callbackSecret" but that scheme is not declared; add a new entry "callbackSecret" under components.securitySchemes that matches the intended auth type (e.g., an apiKey in header/query, or HTTP bearer) so the reference resolves; update the components.securitySchemes object to include "callbackSecret" with the appropriate "type" and fields (name/in or scheme) to align with how callback authentication is implemented.
5676-5729:⚠️ Potential issue | 🟡 MinorThe discover description still overpromises filters.
Follower-count and growth-rate filtering are mentioned here, but the parameter list only documents country, genre, Spotify monthly listeners, sort, and limit. Add the missing query parameters or trim the description so the generated docs stay accurate. As per coding guidelines, "Place all API descriptions, parameter documentation, and response schemas in openapi.json, not in MDX pages".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi.json` around lines 5676 - 5729, The "Discover artists by criteria" endpoint description promises follower-count and growth-rate filters but those query parameters are missing; update the parameters array in openapi.json (the same block that contains country, genre, sp_monthly_listeners_min, sp_monthly_listeners_max, sort, limit) to add the missing filters—e.g., follower_count_min, follower_count_max (type: integer) and growth_rate_min, growth_rate_max (type: number or integer as appropriate)—each with clear descriptions and required:false, or alternatively shorten the description to remove mentions of follower-count and growth-rate so the docs match the existing parameters; ensure all additions live only in openapi.json per guidelines.cli.mdx (1)
222-241:⚠️ Potential issue | 🔴 CriticalRemove unsupported flags from the playlists documentation.
The CLI documentation describes
--editorialand--sinceflags that don't exist in the OpenAPI specification. According to the previous review, the API only supportslimitandsortas query parameters;platformandstatusare path parameters.Remove these flags and their table entries:
- Line 227:
recoup research playlists "Drake" --editorial- Line 228:
recoup research playlists "Drake" --status past --since 2025-01-01→ change to--status past- Line 235:
--editorialtable row- Line 237:
--sincetable row🛠️ Proposed fix
recoup research playlists "Drake" recoup research playlists "Drake" --platform applemusic -recoup research playlists "Drake" --editorial -recoup research playlists "Drake" --status past --since 2025-01-01 +recoup research playlists "Drake" --status past recoup research playlists "Drake" --sort followers --limit 50
Flag Description --platform <p>spotify(default),applemusic,deezer,amazon,youtube- --editorial--status <s>current(default) orpast- --since <date>--sort <field>Sort results (e.g., followers)--limit <n>Max results </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@cli.mdxaround lines 222 - 241, The docs include unsupported CLI flags
--editorial and --since in the playlists examples and flag table; remove the
example linerecoup research playlists "Drake" --editorial, changerecoup research playlists "Drake" --status past --since 2025-01-01to onlyrecoup research playlists "Drake" --status past, and delete the--editorialand
--since <date>rows from the flag table so the examples and table only
reference supported parameters:--platform <p>,--status <s>,--sort <field>, and--limit <n>.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@api-reference/openapi.json:
- Around line 4813-4862: The POST operation for the
"/api/content-agent/{platform}" Slack webhook currently inherits the
document-level apiKeyAuth requirement which Slack cannot satisfy; add an
operation-level security override (security: []) on this POST operation to
disable the inherited apiKeyAuth requirement (or alternatively replace it with
the actual Slack signature validation mechanism) so the webhook contract no
longer requires x-api-key; locate the POST operation block under the
"/api/content-agent/{platform}" path in openapi.json to make this change.
Duplicate comments:
In@api-reference/openapi.json:
- Around line 12271-12275: The ResearchProxyResponse schema is currently an
empty object, leaving many research endpoints (profile, metrics, audience,
cities, similar, urls, playlists, albums, tracks, career, insights, discover,
genres, festivals) with opaque JSON responses; update openapi.json by replacing
ResearchProxyResponse with concrete response schemas per endpoint (e.g.,
ResearchProfileResponse, ResearchMetricsResponse, etc.) or at minimum make
ResearchProxyResponse a oneOf that references those concrete component schemas,
and then update each endpoint's responses to reference the correct schema (use
the component schema names such as ResearchProxyResponse,
ResearchProfileResponse, ResearchMetricsResponse in the endpoints' response
objects to ensure docs and validation are explicit).- Around line 4971-4998: The search operation currently claims "Search for
artists" but accepts a generic query parameter "type" and returns
ResearchSearchResponse.results[] as an opaque object; update openapi.json so the
operation and parameters align and the response is typed: either restrict the
"type" enum to only "artists" and make the operation description and response
schema explicitly ArtistSearchResponse with each result containing typed fields
(id, type, name, and basic metadata), or define a discriminated union
ResultsItem schema (with a required "type" discriminator and concrete
sub-schemas for "artist"/"track"/etc) and replace
ResearchSearchResponse.results[] with this schema; ensure the parameter "type"
description matches the enforced enum and add explicit properties for id, type,
name, and minimal metadata in the returned result schema so callers can map ids
to downstream endpoints.- Around line 4962-4966: The OpenAPI operation at
paths["/api/content-agent/callback"].post references a security scheme named
"callbackSecret" but that scheme is not declared; add a new entry
"callbackSecret" under components.securitySchemes that matches the intended auth
type (e.g., an apiKey in header/query, or HTTP bearer) so the reference
resolves; update the components.securitySchemes object to include
"callbackSecret" with the appropriate "type" and fields (name/in or scheme) to
align with how callback authentication is implemented.- Around line 5676-5729: The "Discover artists by criteria" endpoint description
promises follower-count and growth-rate filters but those query parameters are
missing; update the parameters array in openapi.json (the same block that
contains country, genre, sp_monthly_listeners_min, sp_monthly_listeners_max,
sort, limit) to add the missing filters—e.g., follower_count_min,
follower_count_max (type: integer) and growth_rate_min, growth_rate_max (type:
number or integer as appropriate)—each with clear descriptions and
required:false, or alternatively shorten the description to remove mentions of
follower-count and growth-rate so the docs match the existing parameters; ensure
all additions live only in openapi.json per guidelines.In
@cli.mdx:
- Around line 222-241: The docs include unsupported CLI flags --editorial and
--since in the playlists examples and flag table; remove the example line
recoup research playlists "Drake" --editorial, changerecoup research playlists "Drake" --status past --since 2025-01-01to onlyrecoup research playlists "Drake" --status past, and delete the--editorialand--since <date>rows from the flag table so the examples and table only reference
supported parameters:--platform <p>,--status <s>,--sort <field>, and
--limit <n>.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `6ccabc49-f20e-4543-91fa-062510daf9cf` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between b5f810a7179bfd4f15eaa614ff894a5bf5c71765 and a65f69722e50ec567ef121fbc78802952642a3d2. </details> <details> <summary>📒 Files selected for processing (23)</summary> * `api-reference/openapi.json` * `api-reference/research/albums.mdx` * `api-reference/research/audience.mdx` * `api-reference/research/career.mdx` * `api-reference/research/cities.mdx` * `api-reference/research/curator.mdx` * `api-reference/research/discover.mdx` * `api-reference/research/festivals.mdx` * `api-reference/research/genres.mdx` * `api-reference/research/insights.mdx` * `api-reference/research/instagram-posts.mdx` * `api-reference/research/lookup.mdx` * `api-reference/research/metrics.mdx` * `api-reference/research/playlist.mdx` * `api-reference/research/playlists.mdx` * `api-reference/research/profile.mdx` * `api-reference/research/search.mdx` * `api-reference/research/similar.mdx` * `api-reference/research/track.mdx` * `api-reference/research/tracks.mdx` * `api-reference/research/urls.mdx` * `cli.mdx` * `docs.json` </details> <details> <summary>✅ Files skipped from review due to trivial changes (21)</summary> * api-reference/research/search.mdx * api-reference/research/track.mdx * api-reference/research/curator.mdx * api-reference/research/cities.mdx * api-reference/research/metrics.mdx * api-reference/research/profile.mdx * api-reference/research/career.mdx * api-reference/research/tracks.mdx * api-reference/research/playlists.mdx * api-reference/research/audience.mdx * api-reference/research/lookup.mdx * api-reference/research/discover.mdx * api-reference/research/insights.mdx * api-reference/research/instagram-posts.mdx * api-reference/research/playlist.mdx * api-reference/research/similar.mdx * api-reference/research/albums.mdx * api-reference/research/genres.mdx * api-reference/research/urls.mdx * docs.json * api-reference/research/festivals.mdx </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
- 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
There was a problem hiding this comment.
🧹 Nitpick comments (1)
cli.mdx (1)
321-327: Consolidate repeated artist-ID guidance.Line 128 already explains artist name/UUID resolution for artist-scoped commands; this section repeats the same concept and can be tightened.
♻️ Suggested concise rewrite
### Using Recoup artist IDs -If the artist is already on your Recoup roster, you can pass their Recoup artist ID (UUID) instead of a name. The API resolves it automatically. +Artist IDs are supported on artist-scoped commands (see the note above). Example: ```bash recoup research metrics de05ba8c-7e29-4f1a-93a7-3635653599f6 --source spotify</details> As per coding guidelines, "Follow DRY principle - don't duplicate content across pages, use snippets instead" and "Keep documentation content concise and scannable". <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@cli.mdxaround lines 321 - 327, Remove the duplicated explanatory paragraph
under the "### Using Recoup artist IDs" heading and replace it with a concise
reference to the existing earlier section that explains artist name/UUID
resolution; keep only the example command (recoup research metrics
de05ba8c-7e29-4f1a-93a7-3635653599f6 --source spotify) and/or include a short
inline pointer like "See 'artist name/UUID resolution' above" so the doc follows
DRY and remains scannable while preserving the example.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In@cli.mdx:
- Around line 321-327: Remove the duplicated explanatory paragraph under the
"### Using Recoup artist IDs" heading and replace it with a concise reference to
the existing earlier section that explains artist name/UUID resolution; keep
only the example command (recoup research metrics
de05ba8c-7e29-4f1a-93a7-3635653599f6 --source spotify) and/or include a short
inline pointer like "See 'artist name/UUID resolution' above" so the doc follows
DRY and remains scannable while preserving the example.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `8c80307e-56be-462c-a25b-a070772ea556` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between a65f69722e50ec567ef121fbc78802952642a3d2 and 25d8600542db15aa89aa29c5f3f5b646552b4b8a. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `api-reference/openapi.json` * `cli.mdx` </details> <details> <summary>✅ Files skipped from review due to trivial changes (1)</summary> * api-reference/openapi.json </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
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
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
Made-with: Cursor
Made-with: Cursor
3 tasks
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
5 tasks
5 new endpoints with OpenAPI schemas + MDX pages + CLI docs. Total documented: 30 research endpoints. Made-with: Cursor
Made-with: Cursor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
recoup researchprimitive/api/research/with OpenAPI schemasWhat's documented
API endpoints (16):
CLI commands:
recoup research "Drake"— find artistrecoup research metrics/audience/cities/similar/playlists/albums/tracks/career/insights— structured datarecoup research discover— artist discovery by criteriarecoup research web— web searchrecoup research report— comprehensive deep researchTest plan
npx mintlify@latest devMade with Cursor
Summary by CodeRabbit
New Features
CLI
Documentation