Skip to content

docs: add GET /api/research/track/playlists endpoint #113

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

Open
sidneyswift wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add GET /api/research/track/playlists endpoint #113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8e3bd9c
docs: add GET /api/research/track/playlists endpoint
sidneyswift Apr 7, 2026
680b81a
docs: add artist param to track/playlists endpoint
sidneyswift Apr 7, 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
201 changes: 201 additions & 0 deletions api-reference/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6913,6 +6913,158 @@
}
}
},
"/api/research/track/playlists": {
"get": {
"description": "Get playlists featuring a specific track — editorial, algorithmic, and indie. Returns playlist name, cover image, follower count, and curator.",
"parameters": [
{
"name": "id",
"in": "query",
"required": false,
"description": "Chartmetric track ID. Provide this or `q`.",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"required": false,
"description": "Track name to search for. Provide this or `id`.",
"schema": {
"type": "string"
}
},
{
"name": "artist",
"in": "query",
"required": false,
"description": "Artist name — improves track search accuracy when using `q`.",
"schema": {
"type": "string"
}
},
{
"name": "platform",
"in": "query",
"required": false,
"description": "Streaming platform.",
"schema": {
"type": "string",
"enum": ["spotify", "applemusic", "deezer", "amazon"],
"default": "spotify"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Playlist status.",
"schema": {
"type": "string",
"enum": ["current", "past"],
"default": "current"
}
},
{
"name": "editorial",
"in": "query",
"required": false,
"description": "Only editorial playlists.",
"schema": {
"type": "boolean"
}
},
{
"name": "since",
"in": "query",
"required": false,
"description": "Filter by start date (YYYY-MM-DD).",
"schema": {
"type": "string"
}
},
{
"name": "until",
"in": "query",
"required": false,
"description": "Filter by end date (YYYY-MM-DD).",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "Sort results by this field (e.g. followers, added_at, position).",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum number of results (max 100).",
"schema": {
"type": "integer",
"default": 10
}
Comment on lines +6979 to +7013
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 7, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Align schema constraints with the parameter descriptions.

since/until are documented as YYYY-MM-DD but lack format: date, and limit says max 100 without a maximum constraint. This creates a doc/contract mismatch for generated clients and validators.

Proposed patch 
           {
             "name": "since",
             "in": "query",
             "required": false,
             "description": "Filter by start date (YYYY-MM-DD).",
             "schema": {
-              "type": "string"
+              "type": "string",
+              "format": "date"
             }
           },
           {
             "name": "until",
             "in": "query",
             "required": false,
             "description": "Filter by end date (YYYY-MM-DD).",
             "schema": {
-              "type": "string"
+              "type": "string",
+              "format": "date"
             }
           },
@@
           {
             "name": "limit",
             "in": "query",
             "required": false,
             "description": "Maximum number of results (max 100).",
             "schema": {
               "type": "integer",
-              "default": 10
+              "default": 10,
+              "minimum": 1,
+              "maximum": 100
             }
           },
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi.json` around lines 6970 - 7004, The OpenAPI parameter
schemas for 'since' and 'until' are missing the date format and the 'limit'
parameter lacks the maximum constraint; update the schema objects for the query
parameters named "since" and "until" to include "format": "date" (to match the
YYYY-MM-DD description) and update the "limit" parameter's schema to add
"maximum": 100 (and optionally "minimum": 1) so the schema contract matches the
documented constraints.

},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset for pagination.",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Playlists featuring the track",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchTrackPlaylistsResponse"
}
}
}
},
"400": {
"description": "Missing or invalid parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": { "type": "string", "example": "error" },
"error": { "type": "string" }
}
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": { "type": "string", "example": "error" },
"error": { "type": "string" }
}
}
}
}
}
}
}
},
"/api/research/tracks": {
"get": {
"description": "Get all tracks by an artist with popularity data.",
Expand Down Expand Up @@ -15087,6 +15239,55 @@
}
}
},
"ResearchTrackPlaylistsResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "success"
},
"placements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"playlist": {
"type": "object",
"properties": {
"name": { "type": "string", "description": "Playlist name" },
"image_url": { "type": "string", "description": "Playlist cover image URL" },
"playlist_id": { "type": "string", "description": "Spotify playlist ID" },
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 7, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Use platform-neutral wording for playlist_id.

The schema says “Spotify playlist ID”, but this endpoint is documented for multiple platforms. Consider neutral wording (e.g., “Platform playlist ID”).

Proposed patch 
-                    "playlist_id": { "type": "string", "description": "Spotify playlist ID" },
+                    "playlist_id": { "type": "string", "description": "Platform playlist ID" },
📝 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
"playlist_id": { "type": "string", "description": "Spotify playlist ID" },
"playlist_id": { "type": "string", "description": "Platform playlist ID" },
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi.json` at line 15250, The OpenAPI schema for the
property "playlist_id" currently uses platform-specific wording ("Spotify
playlist ID"); update the description for the "playlist_id" schema entry to a
platform-neutral phrase such as "Platform playlist ID" or "ID of the playlist on
the source platform" so it accurately reflects multi-platform support; locate
the "playlist_id" schema key in the OpenAPI document (property name
"playlist_id") and replace the description string accordingly.

"id": { "type": "integer", "description": "Chartmetric playlist ID" },
"description": { "type": "string" },
"followers": { "type": "integer", "description": "Playlist follower count" },
"num_track": { "type": "integer", "description": "Number of tracks" },
"editorial": { "type": "boolean", "description": "Whether playlist is editorial" },
"owner_name": { "type": "string", "description": "Playlist curator name" },
"position": { "type": "integer", "description": "Track position in playlist" },
"peak_position": { "type": "integer", "description": "Track peak position" },
"added_at": { "type": "string", "description": "When track was added" },
"tags": { "type": "array", "items": { "type": "object" } }
},
"additionalProperties": true
},
"track": {
"type": "object",
"properties": {
"name": { "type": "string", "description": "Track name" },
"cm_track": { "type": "integer", "description": "Chartmetric track ID" },
"isrc": { "type": "string", "description": "Track ISRC" },
"image_url": { "type": "string", "description": "Track image URL" },
"artist_names": { "type": "array", "items": { "type": "string" } },
"spotify_popularity": { "type": "integer" }
},
"additionalProperties": true
}
},
"additionalProperties": true
}
}
}
},
"ResearchProfileResponse": {
"type": "object",
"description": "Full artist profile \u2014 bio, genres, social links, label, images, and basic stats.",
Expand Down
4 changes: 4 additions & 0 deletions api-reference/research/track-playlists.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: 'Track Playlists'
openapi: 'GET /api/research/track/playlists'
---
Comment on lines +1 to +4
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 7, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Add description to frontmatter for consistency.

This API page is correctly frontmatter-only, but it’s missing a description field.

Proposed fix 
 ---
 title: 'Track Playlists'
+description: 'Get playlists associated with a track in Research.'
 openapi: 'GET /api/research/track/playlists'
 ---

As per coding guidelines, "**/*.mdx: Use MDX (Markdown + JSX) for documentation pages with frontmatter for page metadata (title, description)".

📝 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
---
title: 'Track Playlists'
openapi: 'GET /api/research/track/playlists'
---
---
title: 'Track Playlists'
description: 'Get playlists associated with a track in Research.'
openapi: 'GET /api/research/track/playlists'
---
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/research/track-playlists.mdx` around lines 1 - 4, The
frontmatter in the Track Playlists MDX file is missing a description field;
update the frontmatter block (the YAML with title: 'Track Playlists' and
openapi: 'GET /api/research/track/playlists') to include a descriptive
description: string summarizing the page (e.g., "Retrieve playlists for research
tracks" or similar) so the file follows the MDX frontmatter guideline requiring
title and description metadata.

1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,7 @@
"api-reference/research/albums",
"api-reference/research/tracks",
"api-reference/research/track",
"api-reference/research/track-playlists",
"api-reference/research/career",
"api-reference/research/insights",
"api-reference/research/playlist",
Expand Down