From 6dfcc51d952bf6abb68fcc3b65e211f871912bce Mon Sep 17 00:00:00 2001
From: Sweets Sweetman <sweetmantech@gmail.com>
Date: Wed, 15 Apr 2026 17:55:28 -0500
Subject: [PATCH] docs: tighten /research/curator spec to match Chartmetric
 contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- platform enum: spotify | applemusic | deezer (remove amazon + youtube;
  Chartmetric's curator endpoints only support these three)
- id is documented as a numeric Chartmetric curator ID with a pattern
  (^[0-9]+$) and an example value (2 — Spotify's own account)
- Add 404 response for unknown curator id
- Description clarifies how to discover curators via /research/playlists

Surfaced while testing api PR #366 on preview — callers were passing
string handles like "spotify" / "filtr" and getting opaque upstream
400s. Docs now correctly specify numeric id + restricted platform set.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 api-reference/openapi/research.json | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json
index 1b92cff..db3e11e 100644
--- a/api-reference/openapi/research.json
+++ b/api-reference/openapi/research.json
@@ -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",
@@ -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"
             }
           }
         ],
@@ -1227,7 +1227,7 @@
             }
           },
           "400": {
-            "description": "Validation error",
+            "description": "Validation error — missing/invalid `platform` or `id`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -1245,6 +1245,16 @@
                 }
               }
             }
+          },
+          "404": {
+            "description": "Curator not found for the given platform/id.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ResearchErrorResponse"
+                }
+              }
+            }
           }
         }
       }