From ba952290f023341564e5656257541cc1b1d2d1a4 Mon Sep 17 00:00:00 2001
From: Sweets Sweetman <sweetmantech@gmail.com>
Date: Wed, 1 Jul 2026 17:40:03 -0500
Subject: [PATCH] docs(artists): reconcile /api/artists + /socials schemas with
 the live API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Surfaced verifying recoupable/api#734 + #735 (recoupable/chat#1833):
- Artist: add `id` (= account_id, forgiving alias for /artists/{id}/* sub-resources),
  `instruction`, `knowledges`, `label`; rename `socials` -> `account_socials` (the
  field the API actually returns).
- SocialProfile: drop `id` — api#735 removed the dead `account_socials.id` from
  /api/artists/{id}/socials (only `social_id` is returned now).

Docs ↔ API now agree field-for-field (verified against the live #734/#735 previews).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 api-reference/openapi/releases.json | 36 +++++++++++++++++++++++------
 1 file changed, 29 insertions(+), 7 deletions(-)

diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json
index eb34d3bf..9bfe4743 100644
--- a/api-reference/openapi/releases.json
+++ b/api-reference/openapi/releases.json
@@ -1714,6 +1714,11 @@
       "Artist": {
         "type": "object",
         "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "UUID of the artist account. Equal to account_id; use this (or account_id) for /api/artists/{id}/* sub-resources."
+          },
           "account_id": {
             "type": "string",
             "format": "uuid",
@@ -1728,16 +1733,38 @@
             "nullable": true,
             "description": "Artist profile image URL"
           },
+          "instruction": {
+            "type": "string",
+            "nullable": true,
+            "description": "Artist-specific agent instruction / system prompt"
+          },
+          "knowledges": {
+            "type": "array",
+            "description": "Artist knowledge-base entries",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "url": { "type": "string" },
+                "type": { "type": "string" }
+              }
+            }
+          },
+          "label": {
+            "type": "string",
+            "nullable": true,
+            "description": "Artist label / category"
+          },
           "pinned": {
             "type": "boolean",
             "description": "Whether the account has pinned this artist"
           },
-          "socials": {
+          "account_socials": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/ArtistSocial"
             },
-            "description": "Social media profiles linked to the artist"
+            "description": "Social media profiles linked to the artist (embedded in the /api/artists response)"
           }
         }
       },
@@ -2880,11 +2907,6 @@
       "SocialProfile": {
         "type": "object",
         "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "UUID of the artist's account_socials record"
-          },
           "social_id": {
             "type": "string",
             "format": "uuid",