From dc17ccae42994a51bd2c87713c13188e5f16228b Mon Sep 17 00:00:00 2001
From: Arpit Gupta <arpitgupta1214@gmail.com>
Date: Thu, 16 Apr 2026 01:59:13 +0530
Subject: [PATCH] docs: add GET /api/artists/{id}/segments, remove legacy
 /api/artist/segments

Replace the legacy top-level /api/artist/segments list route with the
nested /api/artists/{id}/segments route in the same PR, matching the
resource-first URL convention already in use for /api/artists/{id}/pin,
/api/artists/{id}/unpin, and DELETE /api/artists/{id}.

Per the segments surface migration plan, the legacy route is removed,
not aliased, and the api PR that introduces the nested route will drop
the old route in the same release.

- add api-reference/artists/segments.mdx referencing the new nested
  operation in api-reference/openapi/releases.json
- remove api-reference/artist/segments.mdx and swap the docs.json
  navigation entry to point at the new page
- add GET /api/artists/{id}/segments to releases.json with the id path
  param, page/limit query params, and 200/400/401/403/500 responses
  (reusing the existing ArtistSegmentsResponse / ArtistSegmentsErrorResponse
  schemas so the payload shape is identical to the legacy route)
- remove the legacy GET /api/artist/segments path from releases.json

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 api-reference/artist/segments.mdx   |  4 ----
 api-reference/artists/segments.mdx  |  5 +++++
 api-reference/openapi/releases.json | 33 ++++++++++++++++++++++++-----
 docs.json                           |  2 +-
 4 files changed, 34 insertions(+), 10 deletions(-)
 delete mode 100644 api-reference/artist/segments.mdx
 create mode 100644 api-reference/artists/segments.mdx

diff --git a/api-reference/artist/segments.mdx b/api-reference/artist/segments.mdx
deleted file mode 100644
index cad734b..0000000
--- a/api-reference/artist/segments.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: Get Artist Segments
-openapi: "/api-reference/openapi/releases.json GET /api/artist/segments"
----
diff --git a/api-reference/artists/segments.mdx b/api-reference/artists/segments.mdx
new file mode 100644
index 0000000..40c22e8
--- /dev/null
+++ b/api-reference/artists/segments.mdx
@@ -0,0 +1,5 @@
+---
+title: 'Get Artist Segments'
+description: 'Retrieve all segments associated with an artist. Supports pagination.'
+openapi: "/api-reference/openapi/releases.json GET /api/artists/{id}/segments"
+---
diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json
index a40b3cd..b0cd3d9 100644
--- a/api-reference/openapi/releases.json
+++ b/api-reference/openapi/releases.json
@@ -566,14 +566,14 @@
         }
       }
     },
-    "/api/artist/segments": {
+    "/api/artists/{id}/segments": {
       "get": {
         "description": "Retrieve all segments associated with an artist. This endpoint should be called before using the Segment Fans endpoint to obtain the necessary segment IDs. Supports pagination.",
         "parameters": [
           {
-            "name": "artist_account_id",
-            "in": "query",
-            "description": "The unique identifier of the artist account to fetch segments for",
+            "name": "id",
+            "in": "path",
+            "description": "Artist account ID to fetch segments for.",
             "required": true,
             "schema": {
               "type": "string",
@@ -614,7 +614,30 @@
             }
           },
           "400": {
-            "description": "Bad request - missing required parameters",
+            "description": "Bad request - invalid artist ID path parameter or query parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ArtistSegmentsErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - missing or invalid authentication"
+          },
+          "403": {
+            "description": "Forbidden - the authenticated account cannot access this artist",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ArtistSegmentsErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error while retrieving segments",
             "content": {
               "application/json": {
                 "schema": {
diff --git a/docs.json b/docs.json
index 2b50c59..2f44c1c 100644
--- a/docs.json
+++ b/docs.json
@@ -43,7 +43,7 @@
               "api-reference/artists/pin",
               "api-reference/artists/unpin",
               "api-reference/artists/delete",
-              "api-reference/artist/segments",
+              "api-reference/artists/segments",
               "api-reference/artist/socials",
               "api-reference/artist/socials-scrape",
               "api-reference/artist/profile"