From ac5cd0642f788de7fd31e98cb3675981c4d05375 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Fri, 29 May 2026 20:53:51 +0530 Subject: [PATCH 1/6] docs(api-reference): update GET /api/chats to session-scoped shape Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/openapi/research.json | 45 ++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 34fdbe5..1d419a4 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -16,13 +16,14 @@ "paths": { "/api/chats": { "get": { - "description": "Retrieve chat rooms (conversations) for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations. Optionally filter by an artist_account_id. The endpoint returns metadata about each room, including the topic, associated artist, and last updated timestamp.", + "description": "Returns the caller's chats joined to their parent sessions. Each row carries `sessionId` so consumers can construct the canonical `/sessions/{sessionId}/chats/{id}` URL. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats.", "parameters": [ { "name": "artist_account_id", "in": "query", - "description": "Optional. Filter chats to only include those for the specified artist.", + "description": "Reserved for the artist-surface migration. Currently accepted but does not filter — the new session-scoped listing does not yet carry artist linkage. Will return once `sessions.artist_id` is backfilled.", "required": false, + "deprecated": true, "schema": { "type": "string", "format": "uuid" @@ -3842,9 +3843,45 @@ "chats": { "type": "array", "items": { - "$ref": "#/components/schemas/ChatRoom" + "$ref": "#/components/schemas/SessionScopedChat" }, - "description": "Array of chat room objects" + "description": "Array of session-scoped chat objects" + } + } + }, + "SessionScopedChat": { + "type": "object", + "required": [ + "id", + "title", + "accountId", + "sessionId", + "updatedAt" + ], + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Chat id." + }, + "title": { + "type": "string", + "description": "Display title for the chat." + }, + "accountId": { + "type": "string", + "format": "uuid", + "description": "Owning account, inherited from the parent session." + }, + "sessionId": { + "type": "string", + "format": "uuid", + "description": "Parent session. Use with id to build the canonical /sessions/{sessionId}/chats/{id} URL." + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "ISO timestamp of the last update." } } }, From 31b5ea37971150d135459f60afe06ce7233da455 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Fri, 29 May 2026 21:29:58 +0530 Subject: [PATCH 2/6] docs(api-reference): keep artist_account_id non-deprecated on GET /api/chats MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The artist filter is staying — it's just dormant until sessions.artist_id is backfilled. Drop the deprecated marker and reword the description so clients know the parameter is a normal first-class filter that will start matching rows once the database column lands. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/openapi/research.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 1d419a4..ef3c645 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -21,9 +21,8 @@ { "name": "artist_account_id", "in": "query", - "description": "Reserved for the artist-surface migration. Currently accepted but does not filter — the new session-scoped listing does not yet carry artist linkage. Will return once `sessions.artist_id` is backfilled.", + "description": "Optional. Filter chats to only include those for the specified artist. The filter is wired through but currently has no effect — `sessions.artist_id` is not yet populated, so no rows match. Will start filtering once the artist column is backfilled onto sessions.", "required": false, - "deprecated": true, "schema": { "type": "string", "format": "uuid" From b4a3dcb467d51c1e99522bbdfbaa9e5e1ecdfa2b Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Sat, 30 May 2026 02:08:38 +0530 Subject: [PATCH 3/6] docs(api-reference): modify ChatRoom schema in place for session-scoped GET Replace ChatRoom's rooms-shape fields (account_id, topic, updated_at, artist_id) with the session-scoped wire shape (id, title, accountId, sessionId, updatedAt) and drop the parallel SessionScopedChat schema. ChatRoom is also referenced by CreateChatResponse and UpdateChatResponse (POST /api/chats, PATCH /api/chats/{id}), which still return the rooms shape until they're deleted in a follow-up cleanup PR. Those operation docs are knowingly stale for that brief window. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/openapi/research.json | 72 ++++++++--------------------- 1 file changed, 20 insertions(+), 52 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index ef3c645..43b7ac5 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -3236,33 +3236,37 @@ }, "ChatRoom": { "type": "object", + "required": [ + "id", + "title", + "accountId", + "sessionId", + "updatedAt" + ], "properties": { "id": { "type": "string", "format": "uuid", - "description": "UUID of the chat room" + "description": "Chat id." }, - "account_id": { + "title": { "type": "string", - "format": "uuid", - "nullable": true, - "description": "UUID of the associated account (can be null if not set)" + "description": "Display title for the chat." }, - "topic": { + "accountId": { "type": "string", - "nullable": true, - "description": "Optional topic or description of the room (null if not provided)" + "format": "uuid", + "description": "Owning account, inherited from the parent session." }, - "updated_at": { + "sessionId": { "type": "string", - "format": "date-time", - "description": "ISO timestamp of the last update to the room" + "format": "uuid", + "description": "Parent session. Use with `id` to build the canonical `/sessions/{sessionId}/chats/{id}` URL." }, - "artist_id": { + "updatedAt": { "type": "string", - "format": "uuid", - "nullable": true, - "description": "UUID of the associated artist account (null when not applicable)" + "format": "date-time", + "description": "ISO timestamp of the last update." } } }, @@ -3842,48 +3846,12 @@ "chats": { "type": "array", "items": { - "$ref": "#/components/schemas/SessionScopedChat" + "$ref": "#/components/schemas/ChatRoom" }, "description": "Array of session-scoped chat objects" } } }, - "SessionScopedChat": { - "type": "object", - "required": [ - "id", - "title", - "accountId", - "sessionId", - "updatedAt" - ], - "properties": { - "id": { - "type": "string", - "format": "uuid", - "description": "Chat id." - }, - "title": { - "type": "string", - "description": "Display title for the chat." - }, - "accountId": { - "type": "string", - "format": "uuid", - "description": "Owning account, inherited from the parent session." - }, - "sessionId": { - "type": "string", - "format": "uuid", - "description": "Parent session. Use with id to build the canonical /sessions/{sessionId}/chats/{id} URL." - }, - "updatedAt": { - "type": "string", - "format": "date-time", - "description": "ISO timestamp of the last update." - } - } - }, "ResearchAlbum": { "type": "object", "properties": { From f77477c96a653902c2486bda89d7a9f3ff3c54e2 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Sat, 30 May 2026 02:12:49 +0530 Subject: [PATCH 4/6] docs(api-reference): drop internal vocab from GET /api/chats descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The public spec shouldn't lean on internal migration language — "session-scoped", "joined to parent sessions", "sessions.artist_id". External consumers care about what the fields are and how to use them, not the internal join shape or the schema column they came from. Reword the operation description, the artist_account_id parameter note, and a couple of field descriptions to focus on what each thing is and how to use it. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/openapi/research.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 43b7ac5..83d9b37 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -16,12 +16,12 @@ "paths": { "/api/chats": { "get": { - "description": "Returns the caller's chats joined to their parent sessions. Each row carries `sessionId` so consumers can construct the canonical `/sessions/{sessionId}/chats/{id}` URL. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats.", + "description": "Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL.", "parameters": [ { "name": "artist_account_id", "in": "query", - "description": "Optional. Filter chats to only include those for the specified artist. The filter is wired through but currently has no effect — `sessions.artist_id` is not yet populated, so no rows match. Will start filtering once the artist column is backfilled onto sessions.", + "description": "Optional. Filter chats to only include those for the specified artist. The parameter is accepted but currently has no effect; artist filtering returns in a future release.", "required": false, "schema": { "type": "string", @@ -3256,12 +3256,12 @@ "accountId": { "type": "string", "format": "uuid", - "description": "Owning account, inherited from the parent session." + "description": "Owning account for this chat." }, "sessionId": { "type": "string", "format": "uuid", - "description": "Parent session. Use with `id` to build the canonical `/sessions/{sessionId}/chats/{id}` URL." + "description": "Session that owns this chat. Combine with `id` to build the chat URL: `/sessions/{sessionId}/chats/{id}`." }, "updatedAt": { "type": "string", @@ -3848,7 +3848,7 @@ "items": { "$ref": "#/components/schemas/ChatRoom" }, - "description": "Array of session-scoped chat objects" + "description": "Array of chat objects" } } }, From e710dd44a24c3f4f8bb20aa7f3932ce9b9153325 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Sat, 30 May 2026 21:36:07 -0500 Subject: [PATCH 5/6] docs(chats): add artistId to ChatRoom response schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pairs with the projection that api#626 will add (`session.artist_id` → `artistId` per row in GET /api/chats), so the docs describe the field the client will receive. Nullable per the underlying column (`sessions.artist_id` is nullable, populated for sessions whose room had an artist or whose creator passed `artistId` to `POST /api/sessions`). Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/openapi/research.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 83d9b37..7377df4 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -3267,6 +3267,12 @@ "type": "string", "format": "date-time", "description": "ISO timestamp of the last update." + }, + "artistId": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Artist account id this chat's session was created in the context of, or `null` when no artist was associated. Inherited from `sessions.artist_id` on the owning session." } } }, From 23a32ebf598c1278668920601547a06e67129d20 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Sat, 30 May 2026 21:38:41 -0500 Subject: [PATCH 6/6] docs(chats): describe artist_account_id as a real filter Drops the "currently has no effect" caveat. Documentation-driven: the docs describe the contract api#626 will satisfy (filter by `session.artist_id`) rather than papering over the temporary no-op. --- api-reference/openapi/research.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 7377df4..92135d2 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -21,7 +21,7 @@ { "name": "artist_account_id", "in": "query", - "description": "Optional. Filter chats to only include those for the specified artist. The parameter is accepted but currently has no effect; artist filtering returns in a future release.", + "description": "Optional. Filter chats to only include those whose owning session's `artistId` matches the supplied artist account id. Combine with `account_id` to scope by both owner and artist.", "required": false, "schema": { "type": "string",