docs(research): add GET /api/research/track/stats — per-track Songstats stats

Merged
SW
4mo ago
+246-1

Contract-first docs for the per-track stats passthrough tracked in recoupable/chat#1789 (step 1 of docs → api).

Adds GET /api/research/track/stats — per-track, per-source current stats by isrc (or songstats_track_id / spotify_track_id / apple_music_track_id), returning the same stats[].data envelope as GET /api/research/metrics but scoped to a single recording (so data.streams_total is per-track, not artist-wide).

Changes

  • api-reference/openapi/research.json — new path + ResearchTrackStatsResponse / ResearchTrackStat schemas (reuses ResearchTrackInfo for track_info, ResearchErrorResponse for 400/401/404). Params mirror Songstats enterprise/v1/tracks/stats 1:1 (source required; with_playlists/charts/stations/videos/links, only_current, limit, offset).
  • api-reference/research/track-stats.mdx — reference page (frontmatter-only, per house style).
  • docs.json — adds the page under Research → Catalog (surfaces in the generated llms.txt).

Notes

  • No security block / no new credential — matches the sibling /research/metrics (research endpoints document a 401 response; auth is x-api-key/Bearer). Server-side Songstats apikey is never part of the contract.
  • This is the contract; api implements against it next (passthrough to Songstats, response shaped like /research/metrics).

Source: Songstats Get Track Current Stats (verified 2026-06-09) — https://docs.songstats.com/docs/api/6659134e76415-get-track-current-stats

🤖 Generated with Claude Code

Summary by cubic

Adds contract-first docs for GET /api/research/track/stats — per-source current stats for a single track by isrc or platform IDs. Mirrors GET /api/research/metrics data shape, scoped to one recording, and aligned with the live API.

  • New Features

    • OpenAPI: new path with identifiers (isrc, songstats_track_id, spotify_track_id, apple_music_track_id), required source, and toggles (with_playlists, with_charts, with_stations, with_videos, with_links, only_current, limit, offset). Adds ResearchTrackStatsResponse (includes stats[], track_info, source_ids) and ResearchTrackStat; adds songstats_track_id to ResearchTrackInfo; 200/400/401/404.
    • Docs: adds api-reference/research/track-stats.mdx and updates docs.json under Research → Catalog.

  • Refactors

    • Simplified endpoint and param descriptions to match neighbor brevity (single “provide exactly one identifier” note on isrc; removed passthrough/envelope copy).

Summary by CodeRabbit

Release Notes

  • New Features
    • Added new Track Stats API endpoint to query per-source streaming, chart, and listener metrics for individual tracks using ISRC, SongStats ID, Spotify ID, or Apple Music ID
    • Published Track Stats API documentation for reference