Skip to content

docs: tighten /research/curator spec to match Chartmetric contract #137

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

Merged
sweetmantech merged 1 commit into from
Apr 15, 2026
Merged

docs: tighten /research/curator spec to match Chartmetric contract #137

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
26 changes: 18 additions & 8 deletions api-reference/openapi/research.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1187,7 +1187,7 @@
},
"/api/research/curator": {
"get": {
"description": "Get curator profile — who curates a playlist, their other playlists, and follower reach.",
"description": "Get curator profile — name, image, follower counts across platforms, tag-based genre info, and Chartmetric playlist reach statistics. Requires a numeric Chartmetric curator ID (e.g. `2` for Spotify's own account). Use `GET /api/research/playlists` to discover curators via their playlists.",
"parameters": [
{
"name": "platform",
Expand All @@ -1198,20 +1198,20 @@
"enum": [
"spotify",
"applemusic",
"deezer",
"amazon",
"youtube"
"deezer"
]
},
"description": "Streaming platform."
"description": "Streaming platform. Only Spotify, Apple Music, and Deezer have curator metadata on Chartmetric. (YouTube and Amazon are not supported by this endpoint.)"
},
{
"name": "id",
"in": "query",
"required": true,
"description": "Curator ID.",
"description": "Numeric Chartmetric curator ID (e.g. `2` for Spotify's own account). Non-numeric values will be rejected.",
"schema": {
"type": "string"
"type": "string",
"pattern": "^[0-9]+$",
"example": "2"
}
}
],
Expand All @@ -1227,7 +1227,7 @@
}
},
"400": {
"description": "Validation error",
"description": "Validation error — missing/invalid `platform` or `id`.",
"content": {
"application/json": {
"schema": {
Expand All @@ -1245,6 +1245,16 @@
}
}
}
},
"404": {
"description": "Curator not found for the given platform/id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchErrorResponse"
}
Comment on lines +1249 to +1255
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 15, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

ResearchErrorResponse description is stale after adding 404.

This endpoint now uses ResearchErrorResponse for 404 as well, but Line 5002 still says the schema is for 400/401 only. Please update that description to avoid misleading generated docs.

✏️ Suggested wording update 
-        "description": "Error response returned by all research endpoints for validation failures (400) and authentication errors (401).",
+        "description": "Error response returned by research endpoints for validation failures (400), authentication errors (401), and resource-not-found errors where applicable (404).",
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi/research.json` around lines 1249 - 1255, Update the
ResearchErrorResponse schema description to reflect that it is used for 400, 401
and 404 responses (not just 400/401) so generated docs aren't misleading; locate
the ResearchErrorResponse component (the schema referenced by responses
including the 404 in the endpoint diff) and change its description text to list
400, 401 and 404 (and any brief context about curator not found if present).

}
}
}
}
}
Expand Down