From 4d097cbfcb55c89665b6f3297927305231f63239 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 29 Jul 2026 08:01:54 -0500 Subject: [PATCH 1/2] docs(artists): POST /api/artists resolves-or-creates the canonical for a spotify_artist_id Optional spotify_artist_id on CreateArtistRequest: when a canonical artist already carries the id the endpoint links it to the account and returns 200; otherwise it creates with the Spotify profile attached (201). Contract for the dedup-at-creation slice on chat#1889 rows 8-10: one canonical artist per Spotify id, enforced where rows are born. Co-Authored-By: Claude Opus 5 (1M context) --- api-reference/openapi/releases.json | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 4a7511e..b49af77 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -554,7 +554,7 @@ } }, "post": { - "description": "Create a new artist account. The artist can optionally be linked to an organization.", + "description": "Create a new artist account, or — when spotify_artist_id is provided and a canonical artist already exists for it — link that existing artist to the account instead of creating a duplicate. The artist can optionally be linked to an organization.", "requestBody": { "description": "Artist creation parameters", "required": true, @@ -567,6 +567,16 @@ } }, "responses": { + "200": { + "description": "Existing canonical artist for the given spotify_artist_id linked to the account (no new artist created)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateArtistResponse" + } + } + } + }, "201": { "description": "Artist created successfully", "content": { @@ -2822,6 +2832,10 @@ "minLength": 1, "description": "The name of the artist to create" }, + "spotify_artist_id": { + "type": "string", + "description": "Optional Spotify artist id. When provided, the endpoint resolves-or-creates the canonical artist for that id: if an artist already carries it, that artist is linked to the account and returned (200) instead of creating a duplicate; otherwise the artist is created with its Spotify profile attached (201)." + }, "account_id": { "type": "string", "format": "uuid", From 135ee368798a6227112d67ba1e6c316da3707444 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 29 Jul 2026 08:28:16 -0500 Subject: [PATCH 2/2] docs(artists): drop em dashes from the endpoint description (customer-facing copy rule) --- api-reference/openapi/releases.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index b49af77..ee25dc8 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -554,7 +554,7 @@ } }, "post": { - "description": "Create a new artist account, or — when spotify_artist_id is provided and a canonical artist already exists for it — link that existing artist to the account instead of creating a duplicate. The artist can optionally be linked to an organization.", + "description": "Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization.", "requestBody": { "description": "Artist creation parameters", "required": true,