From e45f354f947c7be0eb832792600b401b1618ab39 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 2 Jun 2026 03:57:46 +0700 Subject: [PATCH 1/6] docs: align sessions OpenAPI with api PatchSessionBody and Session shape --- api-reference/openapi/sessions.json | 10 ++++++---- api-reference/sessions/patch.mdx | 1 + 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index a4aab6f..4271245 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -158,7 +158,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PatchSessionRequest" + "$ref": "#/components/schemas/PatchSessionBody" } } } @@ -746,9 +746,9 @@ } } }, - "PatchSessionRequest": { + "PatchSessionBody": { "type": "object", - "description": "All fields are optional. Omitted fields are left unchanged.", + "description": "Request body for `PATCH /api/sessions/{sessionId}`. All fields are optional; an empty object `{}` is valid and leaves the session unchanged.", "properties": { "title": { "type": "string", @@ -1084,9 +1084,11 @@ }, "Session": { "type": "object", + "description": "Agent session returned by `POST /api/sessions`, `GET /api/sessions/{sessionId}`, and `PATCH /api/sessions/{sessionId}`. The api serializes every field listed in `required` on each response, including `isNewBranch` (boolean, from the non-null `sessions.is_new_branch` column) and `artistId` (UUID or null).", "required": [ "id", "userId", + "artistId", "title", "status", "isNewBranch", @@ -1137,7 +1139,7 @@ }, "isNewBranch": { "type": "boolean", - "description": "True when this session created and pushed a new branch (not committing back to the original)." + "description": "Always present on session responses. True when this session created and pushed a new branch (not committing back to the original); false otherwise." }, "globalSkillRefs": { "type": "array", diff --git a/api-reference/sessions/patch.mdx b/api-reference/sessions/patch.mdx index f09b441..0244dd9 100644 --- a/api-reference/sessions/patch.mdx +++ b/api-reference/sessions/patch.mdx @@ -1,4 +1,5 @@ --- title: "Update Session" +description: "Rename a session, change lifecycle status, or update line counters. Request body uses the PatchSessionBody schema." openapi: "/api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId}" --- From b6b112abe925b804d465746af3de1c8f14078a87 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 2 Jun 2026 04:12:34 +0700 Subject: [PATCH 2/6] fix(docs): Session.artistId OAS 3.1 null type for required field --- api-reference/openapi/sessions.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 4271245..8f53f44 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -1238,9 +1238,8 @@ "format": "date-time" }, "artistId": { - "type": "string", + "type": ["string", "null"], "format": "uuid", - "nullable": true, "description": "Artist account id this session was created in the context of, or `null` when no artist was associated. Set via `POST /api/sessions { artistId }`; surfaces here for clients (e.g. the chat sidebar) that filter sessions/chats by artist." } } From b296b472c15c20f82857e9b0411fba7c33b4eae2 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 2 Jun 2026 04:17:41 +0700 Subject: [PATCH 3/6] fix(docs): patch.mdx openapi frontmatter uses METHOD /path format --- api-reference/sessions/patch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/sessions/patch.mdx b/api-reference/sessions/patch.mdx index 0244dd9..4a16784 100644 --- a/api-reference/sessions/patch.mdx +++ b/api-reference/sessions/patch.mdx @@ -1,5 +1,5 @@ --- title: "Update Session" description: "Rename a session, change lifecycle status, or update line counters. Request body uses the PatchSessionBody schema." -openapi: "/api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId}" +openapi: "PATCH /api/sessions/{sessionId}" --- From 05cd6a18aac9673fe74fe92a592c7ad7e0c404cd Mon Sep 17 00:00:00 2001 From: john Date: Sat, 6 Jun 2026 01:52:40 -0700 Subject: [PATCH 4/6] fix(docs): update openapi frontmatter format in patch.mdx to include full path --- api-reference/sessions/patch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/sessions/patch.mdx b/api-reference/sessions/patch.mdx index 4a16784..0244dd9 100644 --- a/api-reference/sessions/patch.mdx +++ b/api-reference/sessions/patch.mdx @@ -1,5 +1,5 @@ --- title: "Update Session" description: "Rename a session, change lifecycle status, or update line counters. Request body uses the PatchSessionBody schema." -openapi: "PATCH /api/sessions/{sessionId}" +openapi: "/api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId}" --- From e3581985171445e430e937fc10254f2025416da4 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Fri, 5 Jun 2026 15:30:28 -0500 Subject: [PATCH 5/6] docs(sessions): hyperlink referenced endpoints + trim PATCH description (review) - Session description: link POST/GET/PATCH endpoints to their reference pages (house style, no backticks) - patch.mdx: drop redundant schema sentence (KISS) --- api-reference/openapi/sessions.json | 2 +- api-reference/sessions/patch.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 8f53f44..cc6e706 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -1084,7 +1084,7 @@ }, "Session": { "type": "object", - "description": "Agent session returned by `POST /api/sessions`, `GET /api/sessions/{sessionId}`, and `PATCH /api/sessions/{sessionId}`. The api serializes every field listed in `required` on each response, including `isNewBranch` (boolean, from the non-null `sessions.is_new_branch` column) and `artistId` (UUID or null).", + "description": "Agent session returned by [POST /api/sessions](/api-reference/sessions/create), [GET /api/sessions/{sessionId}](/api-reference/sessions/get), and [PATCH /api/sessions/{sessionId}](/api-reference/sessions/patch). The api serializes every field listed in `required` on each response, including `isNewBranch` (boolean, from the non-null `sessions.is_new_branch` column) and `artistId` (UUID or null).", "required": [ "id", "userId", diff --git a/api-reference/sessions/patch.mdx b/api-reference/sessions/patch.mdx index 0244dd9..c5081f8 100644 --- a/api-reference/sessions/patch.mdx +++ b/api-reference/sessions/patch.mdx @@ -1,5 +1,5 @@ --- title: "Update Session" -description: "Rename a session, change lifecycle status, or update line counters. Request body uses the PatchSessionBody schema." +description: "Rename a session, change lifecycle status, or update line counters." openapi: "/api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId}" --- From 02dc73bb725220fee086e0117267a38e766cd29e Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Fri, 5 Jun 2026 15:38:01 -0500 Subject: [PATCH 6/6] docs(sessions): trim PatchSessionBody description (KISS, match CreateSessionRequest sibling) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the redundant 'Request body for PATCH ...' prefix — the schema is already bound to the endpoint. Now mirrors the create-counterpart CreateSessionRequest. --- api-reference/openapi/sessions.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index cc6e706..9f2bdf3 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -748,7 +748,7 @@ }, "PatchSessionBody": { "type": "object", - "description": "Request body for `PATCH /api/sessions/{sessionId}`. All fields are optional; an empty object `{}` is valid and leaves the session unchanged.", + "description": "All fields are optional; an empty object `{}` is valid and leaves the session unchanged.", "properties": { "title": { "type": "string",