From 4f27912dc11fbf511c079a568926bce5bc257a37 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Sat, 18 Apr 2026 00:14:07 +0530 Subject: [PATCH 1/8] docs: repoint /api/fans to /api/artists/{id}/fans Rename the OpenAPI path key from `/api/fans` to `/api/artists/{id}/fans`, move the `artist_account_id` query param to a required `{id}` path param, and drop the per-operation `servers` override so the top-level `https://recoup-api.vercel.app` server applies. Response schemas are unchanged. --- api-reference/openapi/releases.json | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index a40b3cdb..c21ef026 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -807,18 +807,13 @@ } } }, - "/api/fans": { + "/api/artists/{id}/fans": { "get": { - "servers": [ - { - "url": "https://api.recoupable.com" - } - ], "description": "Retrieve all social profiles from fans of an artist across all platforms. This endpoint aggregates fan data from all connected social media platforms. Supports pagination for large fan lists.", "parameters": [ { - "name": "artist_account_id", - "in": "query", + "name": "id", + "in": "path", "description": "The unique identifier of the artist account to fetch fans for", "required": true, "schema": { From 486e1f448be995a20b2fdfa14e270b409c5f96cb Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Sun, 19 Apr 2026 22:30:32 +0530 Subject: [PATCH 2/8] docs(fans): add security, 401, 500 to OpenAPI spec --- api-reference/openapi/releases.json | 32 +++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index c21ef026..11e3e55b 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -809,7 +809,15 @@ }, "/api/artists/{id}/fans": { "get": { - "description": "Retrieve all social profiles from fans of an artist across all platforms. This endpoint aggregates fan data from all connected social media platforms. Supports pagination for large fan lists.", + "description": "Retrieve paginated fans for an artist, ordered by most recent engagement. Fans are sourced from `social_fans` (trigger-populated from `post_comments`) and aggregated across every social profile the artist account owns. Requires authentication via API key or Bearer token.", + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ], "parameters": [ { "name": "id", @@ -855,7 +863,27 @@ } }, "400": { - "description": "Bad request - missing required parameters", + "description": "Bad request - invalid id, page, or limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArtistFansErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized - missing or invalid credentials", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { From 68324be944e70a210e2280975c6c89093d65888c Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Mon, 20 Apr 2026 00:57:42 +0530 Subject: [PATCH 3/8] docs(fans): repoint mdx frontmatter; drop unused ArtistFansErrorResponse schema - api-reference/fans/get.mdx now references GET /api/artists/{id}/fans - Remove dead ArtistFansErrorResponse schema (endpoint uses generic Error) Co-Authored-By: Claude Opus 4.7 --- api-reference/fans/get.mdx | 2 +- api-reference/openapi/releases.json | 29 +++-------------------------- 2 files changed, 4 insertions(+), 27 deletions(-) diff --git a/api-reference/fans/get.mdx b/api-reference/fans/get.mdx index a4803e11..6e0d9fa1 100644 --- a/api-reference/fans/get.mdx +++ b/api-reference/fans/get.mdx @@ -1,4 +1,4 @@ --- title: Get Artist Fans -openapi: "/api-reference/openapi/releases.json GET /api/fans" +openapi: "/api-reference/openapi/releases.json GET /api/artists/{id}/fans" --- diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 11e3e55b..d4e2bdf1 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -809,13 +809,10 @@ }, "/api/artists/{id}/fans": { "get": { - "description": "Retrieve paginated fans for an artist, ordered by most recent engagement. Fans are sourced from `social_fans` (trigger-populated from `post_comments`) and aggregated across every social profile the artist account owns. Requires authentication via API key or Bearer token.", + "description": "Retrieve paginated fans for an artist, ordered by most recent engagement. Fans are sourced from `social_fans` (trigger-populated from `post_comments`) and aggregated across every social profile the artist account owns. Requires authentication via API key.", "security": [ { "apiKeyAuth": [] - }, - { - "bearerAuth": [] } ], "parameters": [ @@ -867,7 +864,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ArtistFansErrorResponse" + "$ref": "#/components/schemas/Error" } } } @@ -887,7 +884,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ArtistFansErrorResponse" + "$ref": "#/components/schemas/Error" } } } @@ -1599,26 +1596,6 @@ } } }, - "ArtistFansErrorResponse": { - "type": "object", - "required": [ - "status", - "error" - ], - "properties": { - "status": { - "type": "string", - "enum": [ - "error" - ], - "description": "Status of the request" - }, - "error": { - "type": "string", - "description": "Error message describing what went wrong" - } - } - }, "ArtistFansPagination": { "type": "object", "properties": { From 052c0c96ed9f2ee26e692eb9075a1b898c0fdb92 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Mon, 20 Apr 2026 23:42:46 +0530 Subject: [PATCH 4/8] docs: drop dead /api/segment/fans path from releases spec --- api-reference/openapi/releases.json | 65 ----------------------------- 1 file changed, 65 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index eb83db39..0725c57a 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -682,71 +682,6 @@ } } }, - "/api/segment/fans": { - "get": { - "servers": [ - { - "url": "https://api.recoupable.com" - } - ], - "description": "Retrieve all social profiles from fans within a specific segment. This endpoint should be called after obtaining segment IDs from the Artist Segments endpoint. Supports pagination for large fan lists.", - "parameters": [ - { - "name": "segment_id", - "in": "query", - "description": "The unique identifier of the segment to fetch fans for", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "page", - "in": "query", - "description": "The page number to retrieve (default: 1)", - "required": false, - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "The number of records per page (default: 20, max: 100)", - "required": false, - "schema": { - "type": "integer", - "default": 20, - "maximum": 100 - } - } - ], - "responses": { - "200": { - "description": "Segment fans retrieved successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SegmentFansResponse" - } - } - } - }, - "400": { - "description": "Bad request - missing required parameters", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SegmentFansErrorResponse" - } - } - } - } - } - } - }, "/api/artists/{id}/fans": { "get": { "servers": [ From fc378d397850ff7cb15dc82a3c5b309056fc5dcf Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Mon, 20 Apr 2026 23:44:37 +0530 Subject: [PATCH 5/8] docs(fans): document 401 and 500 response codes --- api-reference/openapi/releases.json | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 0725c57a..54502b85 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -743,6 +743,26 @@ } } } + }, + "401": { + "description": "Unauthorized - missing or invalid credentials", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArtistFansErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArtistFansErrorResponse" + } + } + } } } } From 0dedbc5ccb3e112ec7791e8d6838746b54996e50 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Mon, 20 Apr 2026 23:52:20 +0530 Subject: [PATCH 6/8] docs(fans): drop api.recoupable.com override, inherit recoup-api.vercel.app --- api-reference/openapi/releases.json | 5 ----- 1 file changed, 5 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 54502b85..3af96d12 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -684,11 +684,6 @@ }, "/api/artists/{id}/fans": { "get": { - "servers": [ - { - "url": "https://api.recoupable.com" - } - ], "description": "Retrieve all social profiles from fans of an artist across all platforms. This endpoint aggregates fan data from all connected social media platforms. Supports pagination for large fan lists.", "parameters": [ { From dedaf38cd7ff3b4d518a9bd71587e1efc391a070 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Tue, 21 Apr 2026 00:00:16 +0530 Subject: [PATCH 7/8] docs(fans): rename followerCount/followingCount to snake_case to match api --- api-reference/openapi/releases.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 3af96d12..574e45f8 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -1451,11 +1451,11 @@ "type": "string", "description": "Fan's biography or profile description" }, - "followerCount": { + "follower_count": { "type": "integer", "description": "Number of followers the fan has" }, - "followingCount": { + "following_count": { "type": "integer", "description": "Number of accounts the fan is following" }, From 7568409962bc95a1f7407153b93099ceb2faf162 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Tue, 21 Apr 2026 16:11:38 -0500 Subject: [PATCH 8/8] docs(nav): move Fans group from Releases tab to Artists tab MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The endpoint is now /api/artists/{id}/fans — an artist-scoped resource, not a release one. Move the Fans nav group under the Artists tab so the IA matches the route shape. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs.json b/docs.json index 997442ca..20364d6c 100644 --- a/docs.json +++ b/docs.json @@ -48,6 +48,12 @@ "api-reference/artist/profile" ] }, + { + "group": "Fans", + "pages": [ + "api-reference/fans/get" + ] + }, { "group": "Tasks", "pages": [ @@ -164,12 +170,6 @@ "api-reference/songs/catalog-songs-add", "api-reference/songs/catalog-songs-delete" ] - }, - { - "group": "Fans", - "pages": [ - "api-reference/fans/get" - ] } ] },