From 0a6d31f2fa37b70be8e9e50ec33b63bc24dd0d7b Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Mon, 13 Apr 2026 23:15:33 +0530 Subject: [PATCH 1/3] docs: add patch artist endpoint reference --- api-reference/artists/update.mdx | 5 + api-reference/openapi/releases.json | 226 ++++++++++++++++++++++++++++ docs.json | 1 + 3 files changed, 232 insertions(+) create mode 100644 api-reference/artists/update.mdx diff --git a/api-reference/artists/update.mdx b/api-reference/artists/update.mdx new file mode 100644 index 0000000..7e83144 --- /dev/null +++ b/api-reference/artists/update.mdx @@ -0,0 +1,5 @@ +--- +title: 'Update Artist' +description: 'Update manual artist settings for an artist accessible to the authenticated account.' +openapi: "/api-reference/openapi/releases.json PATCH /api/artists/{id}" +--- diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 97176b7..3bd33c4 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -393,6 +393,77 @@ } }, "/api/artists/{id}": { + "patch": { + "description": "Update manual artist settings for an artist accessible to the authenticated account. This updates profile fields, artist account info, and any provided socials, then returns the merged artist payload.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Artist account ID to update.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "description": "Artist fields to update", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateArtistRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Artist updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateArtistResponse" + } + } + } + }, + "400": { + "description": "Bad request - invalid artist id or invalid update payload", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateArtistErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized - missing or invalid authentication" + }, + "403": { + "description": "Forbidden - the authenticated account cannot update this artist", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateArtistErrorResponse" + } + } + } + }, + "404": { + "description": "Artist not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateArtistErrorResponse" + } + } + } + } + } + }, "delete": { "description": "Delete an artist accessible to the authenticated account. This removes the caller's direct artist link and, if no owner links remain, deletes the artist account itself.", "parameters": [ @@ -3309,6 +3380,161 @@ "example": true } } + }, + "UpdateArtistErrorResponse": { + "type": "object", + "required": [ + "status", + "error" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Status of the request" + }, + "missing_fields": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Path to the first invalid field when validation fails" + }, + "error": { + "type": "string", + "description": "Error message describing what went wrong" + } + } + }, + "ArtistKnowledge": { + "type": "object", + "required": [ + "name", + "url", + "type" + ], + "properties": { + "name": { + "type": "string", + "description": "Display name of the knowledge file" + }, + "url": { + "type": "string", + "format": "uri", + "description": "Resolvable URL for the knowledge file" + }, + "type": { + "type": "string", + "description": "MIME type of the knowledge file" + } + } + }, + "UpdateArtistProfileUrls": { + "type": "object", + "additionalProperties": { + "type": "string", + "format": "uri" + }, + "description": "Social profile URLs keyed by platform slug, for example INSTAGRAM or SPOTIFY." + }, + "UpdateArtistRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Artist display name" + }, + "image": { + "type": "string", + "format": "uri", + "description": "Artist profile image URL" + }, + "instruction": { + "type": "string", + "description": "Manual instruction text for the artist" + }, + "label": { + "type": "string", + "description": "Record label name" + }, + "knowledges": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtistKnowledge" + }, + "description": "Knowledge files attached to the artist" + }, + "profileUrls": { + "$ref": "#/components/schemas/UpdateArtistProfileUrls" + } + } + }, + "UpdatedArtist": { + "type": "object", + "required": [ + "account_id", + "name", + "account_socials", + "pinned" + ], + "properties": { + "account_id": { + "type": "string", + "format": "uuid", + "description": "UUID of the artist account" + }, + "name": { + "type": "string", + "description": "Artist name" + }, + "image": { + "type": "string", + "nullable": true, + "description": "Artist profile image URL" + }, + "instruction": { + "type": "string", + "nullable": true, + "description": "Artist instruction text" + }, + "knowledges": { + "type": "array", + "nullable": true, + "items": { + "$ref": "#/components/schemas/ArtistKnowledge" + }, + "description": "Knowledge files stored on the artist profile" + }, + "label": { + "type": "string", + "nullable": true, + "description": "Record label name" + }, + "account_socials": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtistSocial" + }, + "description": "Linked artist socials" + }, + "pinned": { + "type": "boolean", + "description": "Whether the artist is pinned for the authenticated account" + } + } + }, + "UpdateArtistResponse": { + "type": "object", + "required": [ + "artist" + ], + "properties": { + "artist": { + "$ref": "#/components/schemas/UpdatedArtist" + } + } } } } diff --git a/docs.json b/docs.json index 58ceefa..9f71014 100644 --- a/docs.json +++ b/docs.json @@ -40,6 +40,7 @@ "pages": [ "api-reference/artists/list", "api-reference/artists/create", + "api-reference/artists/update", "api-reference/artists/delete", "api-reference/artist/segments", "api-reference/artist/socials", From 156c1fe9d0298cfed3aaa0c0363c85c64ee513ab Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Tue, 14 Apr 2026 23:12:02 +0530 Subject: [PATCH 2/3] docs: add pin field to PATCH artist and tighten copy - Document pinned in UpdateArtistRequest and PATCH description so the endpoint reflects the pin/unpin consolidation in api. - Drop "authenticated account" phrasing per KISS review feedback; auth is implied for every Recoup endpoint. - Clarify missing_fields description on UpdateArtistErrorResponse to match CreateArtistError phrasing. --- api-reference/artists/update.mdx | 2 +- api-reference/openapi/releases.json | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/api-reference/artists/update.mdx b/api-reference/artists/update.mdx index 7e83144..58bd82c 100644 --- a/api-reference/artists/update.mdx +++ b/api-reference/artists/update.mdx @@ -1,5 +1,5 @@ --- title: 'Update Artist' -description: 'Update manual artist settings for an artist accessible to the authenticated account.' +description: 'Update an artist''s settings, including pin state.' openapi: "/api-reference/openapi/releases.json PATCH /api/artists/{id}" --- diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index a16d5f9..fc97341 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -516,7 +516,7 @@ }, "/api/artists/{id}": { "patch": { - "description": "Update manual artist settings for an artist accessible to the authenticated account. This updates profile fields, artist account info, and any provided socials, then returns the merged artist payload.", + "description": "Update an artist's settings. Sets profile fields, artist account info, any provided socials, and the caller's pin state for this artist, then returns the merged artist payload.", "parameters": [ { "name": "id", @@ -3572,7 +3572,7 @@ "items": { "type": "string" }, - "description": "Path to the first invalid field when validation fails" + "description": "List of missing or invalid field names" }, "error": { "type": "string", @@ -3640,6 +3640,10 @@ }, "profileUrls": { "$ref": "#/components/schemas/UpdateArtistProfileUrls" + }, + "pinned": { + "type": "boolean", + "description": "Pin or unpin this artist for the authenticated account" } } }, From 7197497785fe691abf4a0752665a8513ab09d28c Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Tue, 14 Apr 2026 23:18:50 +0530 Subject: [PATCH 3/3] docs: drop pin mention from PATCH artist descriptions Pin state is documented as a body field; descriptions stay focused on the endpoint's purpose. --- api-reference/artists/update.mdx | 2 +- api-reference/openapi/releases.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/artists/update.mdx b/api-reference/artists/update.mdx index 58bd82c..257f40d 100644 --- a/api-reference/artists/update.mdx +++ b/api-reference/artists/update.mdx @@ -1,5 +1,5 @@ --- title: 'Update Artist' -description: 'Update an artist''s settings, including pin state.' +description: 'Update the settings for an artist.' openapi: "/api-reference/openapi/releases.json PATCH /api/artists/{id}" --- diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index fc97341..6863db9 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -516,7 +516,7 @@ }, "/api/artists/{id}": { "patch": { - "description": "Update an artist's settings. Sets profile fields, artist account info, any provided socials, and the caller's pin state for this artist, then returns the merged artist payload.", + "description": "Update an artist's settings. This updates profile fields, artist account info, and any provided socials, then returns the merged artist payload.", "parameters": [ { "name": "id",