#233 docs(research): align response schemas with SongStats implementation

Align /research/* response schemas with the SongStats implementation

Following DDD, the docs are our contract — but the provider-neutral migration (docs#232) made IDs neutral and dropped Chartmetric-only routes while leaving the /research/* response schemas in Chartmetric shape. Meanwhile api#635 returns SongStats-shaped payloads. This reconciles the spec to the verified-correct implementation.

Verification basis: field-by-field diff against the live api#635 preview + the official SongStats SDK (route audit + typed resources). Full table: api#635 comment. Tracking: recoupable/chat#1777.

What changed (api-reference/openapi/research.json only)

Added shared Songstats* component schemas (reused across endpoints): SongstatsArtistRef, SongstatsArtistInfo, SongstatsActivity, SongstatsCatalogItem, SongstatsTrackInfo, SongstatsMetricStat, SongstatsLink, SongstatsAudioAnalysisEntry, …

Rewrote response schemas to the real shape:

Endpoint	New documented shape
lookup, profile	{status, result, message, artist_info}
metrics	{status, result, message, stats[], artist_info, source_ids}
audience	{status, result, message, audience[], artist_info, source_ids}
track	{status, result, message, track_info, audio_analysis[]}
career, insights, milestones	{status, …[]} of shared SongstatsActivity
albums, tracks	{status, …[]} of shared SongstatsCatalogItem
search	result items → SongStats fields; type enum restricted to artists/tracks/labels
similar	drop total; items are provider-neutral artist refs
rank	documented as 501 (SongStats has no rank endpoint); 200 removed

Unchanged on purpose:

• urls — already matches.
• playlists — currently returns a metric descriptor {source, metric, scope, scope_options} instead of placements. That's an api-side bug (needs the /artists/top_playlists resolution call), tracked in api#635 — the docs keep the intended placements contract so the API has a target to meet.

Validation

• mint openapi-check → OpenAPI definition is valid.
• All $refs resolve; no orphaned/unreferenced schemas; no endpoints added or removed (nav intact).

🤖 Generated with Claude Code

---

Summary by cubic

Updates /research/* docs to the provider‑neutral response shapes returned by the API. Removes the unsupported rank endpoint and standardizes on shared Research* schemas.

• Refactors
  • Added shared Research* component schemas (ArtistRef/Info, Activity, CatalogItem, TrackInfo, MetricStat, Link, AudioAnalysis).
  • Rewrote responses to neutral shapes: lookup/profile → {status,result,message,artist_info}; metrics → {status,result,message,stats[],artist_info,source_ids}; audience → {status,result,message,audience[],artist_info,source_ids}; track → {status,result,message,track_info,audio_analysis[]}; career/insights/milestones → ResearchActivity[]; albums/tracks → ResearchCatalogItem[]; similar drops total and returns ResearchArtistRef items.
  • search: restrict type to artists | tracks | labels.
  • rank: removed endpoint, reference page, and nav entry.
  • Intentionally unchanged: urls; playlists contract kept as placements target.

Summary by CodeRabbit

• API Changes
  • Research API type query parameter updated to include labels and modified supported values.
  • Research ranking endpoint (/api/research/rank) is no longer supported.
  • Research response structures redesigned to improve data consistency across endpoints.