From 24e39e6f287a59b11bc1afd364656cf8e74f8477 Mon Sep 17 00:00:00 2001 From: john Date: Mon, 11 May 2026 01:19:10 +0700 Subject: [PATCH 1/8] docs(sessions): add PATCH /api/sessions/{sessionId} endpoint and update navigation - Introduced a new PATCH endpoint for updating session details, allowing renaming or status changes (e.g., archiving). - Added detailed request and response schemas for `PatchSessionRequest` and updated the `GetSessionResponse`. - Updated navigation to include the new PATCH endpoint under the Sessions group in the documentation. This change enhances the API's functionality by providing a way to modify existing sessions, improving user experience and flexibility. --- api-reference/openapi/sessions.json | 115 ++++++++++++++++++++++++++++ api-reference/sessions/patch.mdx | 4 + docs.json | 3 +- 3 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 api-reference/sessions/patch.mdx diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 350f8f8..f7ccd71 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -137,6 +137,94 @@ } } } + }, + "patch": { + "operationId": "patchSessionById", + "summary": "Update session", + "description": "Renames a session or changes its status (e.g. archive / unarchive). All body fields are optional; omitted fields are left unchanged.", + "parameters": [ + { + "name": "sessionId", + "in": "path", + "required": true, + "description": "The id of the session to update.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PatchSessionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Session updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetSessionResponse" + } + } + } + }, + "400": { + "description": "Bad request — malformed JSON body.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Unauthorized — invalid or missing API key / Bearer token.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Forbidden — the authenticated account does not own this session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Not found — no session exists with the given id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict — sandbox is still being paused; retry unarchiving in a few seconds.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } } } }, @@ -190,6 +278,33 @@ } } }, + "PatchSessionRequest": { + "type": "object", + "description": "All fields are optional. Omitted fields are left unchanged.", + "properties": { + "title": { + "type": "string", + "description": "New display title for the session (rename)." + }, + "status": { + "anyOf": [ + { + "type": "string", + "enum": [ + "running", + "completed", + "failed", + "archived" + ] + }, + { + "type": "null" + } + ], + "description": "Set to `\"archived\"` to archive the session or `\"running\"` to unarchive it." + } + } + }, "GetSessionResponse": { "type": "object", "required": [ diff --git a/api-reference/sessions/patch.mdx b/api-reference/sessions/patch.mdx new file mode 100644 index 0000000..f09b441 --- /dev/null +++ b/api-reference/sessions/patch.mdx @@ -0,0 +1,4 @@ +--- +title: "Update Session" +openapi: "/api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId}" +--- diff --git a/docs.json b/docs.json index fdf0a2c..9f8c934 100644 --- a/docs.json +++ b/docs.json @@ -275,7 +275,8 @@ "group": "Sessions", "pages": [ "api-reference/sessions/create", - "api-reference/sessions/get" + "api-reference/sessions/get", + "api-reference/sessions/patch" ] }, { From cd0acea8e3697a4c6ee9a4508646e31185cfa52b Mon Sep 17 00:00:00 2001 From: john Date: Mon, 11 May 2026 01:31:01 +0700 Subject: [PATCH 2/8] docs(sessions): update session status schema to reflect valid states - Modified the `status` field in the session schema to only allow "running" and "archived" as valid states, removing "completed", "failed", and null options. - Updated the description to clarify the purpose of the `status` field for archiving and unarchiving sessions. This change streamlines the session status options, enhancing clarity in the API documentation. --- api-reference/openapi/sessions.json | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index f7ccd71..823ee33 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -287,19 +287,10 @@ "description": "New display title for the session (rename)." }, "status": { - "anyOf": [ - { - "type": "string", - "enum": [ - "running", - "completed", - "failed", - "archived" - ] - }, - { - "type": "null" - } + "type": "string", + "enum": [ + "running", + "archived" ], "description": "Set to `\"archived\"` to archive the session or `\"running\"` to unarchive it." } From f5f96431dc92733f8292d6af9083cc384b237158 Mon Sep 17 00:00:00 2001 From: john Date: Mon, 11 May 2026 01:19:10 +0700 Subject: [PATCH 3/8] docs(sessions): add PATCH /api/sessions/{sessionId} endpoint and update navigation - Introduced a new PATCH endpoint for updating session details, allowing renaming or status changes (e.g., archiving). - Added detailed request and response schemas for `PatchSessionRequest` and updated the `GetSessionResponse`. - Updated navigation to include the new PATCH endpoint under the Sessions group in the documentation. This change enhances the API's functionality by providing a way to modify existing sessions, improving user experience and flexibility. --- api-reference/openapi/sessions.json | 115 ++++++++++++++++++++++++++++ api-reference/sessions/patch.mdx | 4 + docs.json | 3 +- 3 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 api-reference/sessions/patch.mdx diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 350f8f8..f7ccd71 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -137,6 +137,94 @@ } } } + }, + "patch": { + "operationId": "patchSessionById", + "summary": "Update session", + "description": "Renames a session or changes its status (e.g. archive / unarchive). All body fields are optional; omitted fields are left unchanged.", + "parameters": [ + { + "name": "sessionId", + "in": "path", + "required": true, + "description": "The id of the session to update.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PatchSessionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Session updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetSessionResponse" + } + } + } + }, + "400": { + "description": "Bad request — malformed JSON body.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Unauthorized — invalid or missing API key / Bearer token.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Forbidden — the authenticated account does not own this session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Not found — no session exists with the given id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict — sandbox is still being paused; retry unarchiving in a few seconds.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } } } }, @@ -190,6 +278,33 @@ } } }, + "PatchSessionRequest": { + "type": "object", + "description": "All fields are optional. Omitted fields are left unchanged.", + "properties": { + "title": { + "type": "string", + "description": "New display title for the session (rename)." + }, + "status": { + "anyOf": [ + { + "type": "string", + "enum": [ + "running", + "completed", + "failed", + "archived" + ] + }, + { + "type": "null" + } + ], + "description": "Set to `\"archived\"` to archive the session or `\"running\"` to unarchive it." + } + } + }, "GetSessionResponse": { "type": "object", "required": [ diff --git a/api-reference/sessions/patch.mdx b/api-reference/sessions/patch.mdx new file mode 100644 index 0000000..f09b441 --- /dev/null +++ b/api-reference/sessions/patch.mdx @@ -0,0 +1,4 @@ +--- +title: "Update Session" +openapi: "/api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId}" +--- diff --git a/docs.json b/docs.json index 458ada9..6c610c2 100644 --- a/docs.json +++ b/docs.json @@ -276,7 +276,8 @@ "group": "Sessions", "pages": [ "api-reference/sessions/create", - "api-reference/sessions/get" + "api-reference/sessions/get", + "api-reference/sessions/patch" ] }, { From 578ad7a32579b3114f9476b10ae5b0a07ecd8f48 Mon Sep 17 00:00:00 2001 From: john Date: Mon, 11 May 2026 01:31:01 +0700 Subject: [PATCH 4/8] docs(sessions): update session status schema to reflect valid states - Modified the `status` field in the session schema to only allow "running" and "archived" as valid states, removing "completed", "failed", and null options. - Updated the description to clarify the purpose of the `status` field for archiving and unarchiving sessions. This change streamlines the session status options, enhancing clarity in the API documentation. --- api-reference/openapi/sessions.json | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index f7ccd71..823ee33 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -287,19 +287,10 @@ "description": "New display title for the session (rename)." }, "status": { - "anyOf": [ - { - "type": "string", - "enum": [ - "running", - "completed", - "failed", - "archived" - ] - }, - { - "type": "null" - } + "type": "string", + "enum": [ + "running", + "archived" ], "description": "Set to `\"archived\"` to archive the session or `\"running\"` to unarchive it." } From 0dfbff5198b12dd22c7c0b1b02740eddbdd0ae58 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 12 May 2026 23:24:15 +0700 Subject: [PATCH 5/8] docs(sessions): enhance session API documentation with new endpoints and updates - Added new endpoints for listing session chats (`GET /api/sessions/{sessionId}/chats`) and creating a session chat (`POST /api/sessions/{sessionId}/chats`). - Updated the `requestBody` for the existing session chat creation to make it optional. - Expanded response schemas to include detailed error handling and descriptions for new endpoints. - Updated navigation in the documentation to include new chat-related pages. These changes improve the API's functionality and clarity, providing users with more comprehensive tools for managing session chats. --- api-reference/openapi/sessions.json | 228 ++++++++++++++++++++++++- api-reference/sessions/create-chat.mdx | 4 + api-reference/sessions/list-chats.mdx | 4 + docs.json | 4 +- 4 files changed, 236 insertions(+), 4 deletions(-) create mode 100644 api-reference/sessions/create-chat.mdx create mode 100644 api-reference/sessions/list-chats.mdx diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 823ee33..487da98 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -154,7 +154,7 @@ } ], "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { @@ -214,8 +214,154 @@ } } }, + "500": { + "description": "Internal server error — the session could not be updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/sessions/{sessionId}/chats": { + "get": { + "summary": "List session chats", + "description": "Returns chat summaries for the session plus the caller's default model id for new chats.", + "parameters": [ + { + "name": "sessionId", + "in": "path", + "required": true, + "description": "The id of the session whose chats to list.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Chats retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListSessionChatsResponse" + } + } + } + }, + "401": { + "description": "Unauthorized — invalid or missing API key / Bearer token.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Forbidden — the authenticated account does not own this session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Not found — no session exists with the given id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "summary": "Create session chat", + "description": "Creates a new chat in the session. Optional body may include `id` to use a client-generated id when idempotent creation is needed.", + "parameters": [ + { + "name": "sessionId", + "in": "path", + "required": true, + "description": "The id of the session to attach the chat to.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSessionChatRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Chat created or returned (idempotent when `id` matches an existing chat in this session).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSessionChatResponse" + } + } + } + }, + "400": { + "description": "Bad request — invalid optional `id` in body.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Unauthorized — invalid or missing API key / Bearer token.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Forbidden — the authenticated account does not own this session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Not found — no session exists with the given id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "409": { - "description": "Conflict — sandbox is still being paused; retry unarchiving in a few seconds.", + "description": "Conflict — requested `id` belongs to a chat in another session.", "content": { "application/json": { "schema": { @@ -290,9 +436,85 @@ "type": "string", "enum": [ "running", + "completed", + "failed", "archived" ], - "description": "Set to `\"archived\"` to archive the session or `\"running\"` to unarchive it." + "description": "Lifecycle status. Use `archived` to archive, `running` to unarchive." + }, + "linesAdded": { + "type": "integer", + "minimum": 0, + "description": "Lines added across the session's commits — cached for session list display." + }, + "linesRemoved": { + "type": "integer", + "minimum": 0, + "description": "Lines removed across the session's commits — cached for session list display." + } + } + }, + "ChatSummary": { + "allOf": [ + { + "$ref": "#/components/schemas/Chat" + }, + { + "type": "object", + "required": [ + "hasUnread", + "isStreaming" + ], + "properties": { + "hasUnread": { + "type": "boolean", + "description": "Whether the caller has unread assistant activity in this chat." + }, + "isStreaming": { + "type": "boolean", + "description": "True when an assistant stream is active (`activeStreamId` is set)." + } + } + } + ] + }, + "ListSessionChatsResponse": { + "type": "object", + "required": [ + "chats", + "defaultModelId" + ], + "properties": { + "chats": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChatSummary" + } + }, + "defaultModelId": { + "type": "string", + "description": "Default AI Gateway model id for new chats in this product context." + } + } + }, + "CreateSessionChatRequest": { + "type": "object", + "description": "All fields are optional. An empty body creates a chat with a server-generated id.", + "properties": { + "id": { + "type": "string", + "description": "Optional client-generated chat id. When supplied, creation is idempotent for chats already in this session; if the id exists on another session, the request fails with 409." + } + } + }, + "CreateSessionChatResponse": { + "type": "object", + "required": [ + "chat" + ], + "properties": { + "chat": { + "$ref": "#/components/schemas/Chat" } } }, diff --git a/api-reference/sessions/create-chat.mdx b/api-reference/sessions/create-chat.mdx new file mode 100644 index 0000000..9dfc7b8 --- /dev/null +++ b/api-reference/sessions/create-chat.mdx @@ -0,0 +1,4 @@ +--- +title: "Create Session Chat" +openapi: "/api-reference/openapi/sessions.json POST /api/sessions/{sessionId}/chats" +--- diff --git a/api-reference/sessions/list-chats.mdx b/api-reference/sessions/list-chats.mdx new file mode 100644 index 0000000..dc4a2a3 --- /dev/null +++ b/api-reference/sessions/list-chats.mdx @@ -0,0 +1,4 @@ +--- +title: "List Session Chats" +openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}/chats" +--- diff --git a/docs.json b/docs.json index 6c610c2..46d9b3d 100644 --- a/docs.json +++ b/docs.json @@ -277,7 +277,9 @@ "pages": [ "api-reference/sessions/create", "api-reference/sessions/get", - "api-reference/sessions/patch" + "api-reference/sessions/patch", + "api-reference/sessions/list-chats", + "api-reference/sessions/create-chat" ] }, { From 67c79e2a299da6e9853d98921a2429a0565950cb Mon Sep 17 00:00:00 2001 From: john Date: Tue, 12 May 2026 23:35:02 +0700 Subject: [PATCH 6/8] docs(sessions): update session API documentation for clarity and consistency - Enhanced descriptions in the session schema to provide clearer definitions for `status`, `linesAdded`, and `linesRemoved` fields. - Standardized the `openapi` frontmatter format across multiple session-related documentation files for consistency. These changes improve the clarity and usability of the API documentation, ensuring users have a better understanding of session management functionalities. --- api-reference/openapi/sessions.json | 6 +++--- api-reference/sessions/create-chat.mdx | 2 +- api-reference/sessions/create.mdx | 2 +- api-reference/sessions/get.mdx | 2 +- api-reference/sessions/list-chats.mdx | 2 +- api-reference/sessions/patch.mdx | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 487da98..e25aac6 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -440,17 +440,17 @@ "failed", "archived" ], - "description": "Lifecycle status. Use `archived` to archive, `running` to unarchive." + "description": "Lifecycle status (matches the DB CHECK). `running` is active / unarchived; `completed` and `failed` are terminal; `archived` archives the row. Use `running` to unarchive from `archived`." }, "linesAdded": { "type": "integer", "minimum": 0, - "description": "Lines added across the session's commits — cached for session list display." + "description": "Updates the persisted `lines_added` column on the session (≥ 0)." }, "linesRemoved": { "type": "integer", "minimum": 0, - "description": "Lines removed across the session's commits — cached for session list display." + "description": "Updates the persisted `lines_removed` column on the session (≥ 0)." } } }, diff --git a/api-reference/sessions/create-chat.mdx b/api-reference/sessions/create-chat.mdx index 9dfc7b8..fec8772 100644 --- a/api-reference/sessions/create-chat.mdx +++ b/api-reference/sessions/create-chat.mdx @@ -1,4 +1,4 @@ --- title: "Create Session Chat" -openapi: "/api-reference/openapi/sessions.json POST /api/sessions/{sessionId}/chats" +openapi: 'POST /api/sessions/{sessionId}/chats' --- diff --git a/api-reference/sessions/create.mdx b/api-reference/sessions/create.mdx index f73e290..eb17d0a 100644 --- a/api-reference/sessions/create.mdx +++ b/api-reference/sessions/create.mdx @@ -1,4 +1,4 @@ --- title: "Create Session" -openapi: "/api-reference/openapi/sessions.json POST /api/sessions" +openapi: 'POST /api/sessions' --- diff --git a/api-reference/sessions/get.mdx b/api-reference/sessions/get.mdx index 483ac1b..b7029f4 100644 --- a/api-reference/sessions/get.mdx +++ b/api-reference/sessions/get.mdx @@ -1,4 +1,4 @@ --- title: "Get Session" -openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" +openapi: 'GET /api/sessions/{sessionId}' --- diff --git a/api-reference/sessions/list-chats.mdx b/api-reference/sessions/list-chats.mdx index dc4a2a3..5fc661b 100644 --- a/api-reference/sessions/list-chats.mdx +++ b/api-reference/sessions/list-chats.mdx @@ -1,4 +1,4 @@ --- title: "List Session Chats" -openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}/chats" +openapi: 'GET /api/sessions/{sessionId}/chats' --- diff --git a/api-reference/sessions/patch.mdx b/api-reference/sessions/patch.mdx index f09b441..ed3654f 100644 --- a/api-reference/sessions/patch.mdx +++ b/api-reference/sessions/patch.mdx @@ -1,4 +1,4 @@ --- title: "Update Session" -openapi: "/api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId}" +openapi: 'PATCH /api/sessions/{sessionId}' --- From ef8d77ebf05a54a2fd4d35568bdfa89191745450 Mon Sep 17 00:00:00 2001 From: john Date: Wed, 13 May 2026 00:57:36 +0700 Subject: [PATCH 7/8] docs(sessions): remove deprecated chat endpoints and schemas - Deleted the `GET` and `POST` endpoints for listing and creating session chats from the API documentation. - Removed associated schemas such as `ChatSummary`, `ListSessionChatsResponse`, `CreateSessionChatRequest`, and `CreateSessionChatResponse`. - This cleanup streamlines the documentation by eliminating outdated references, ensuring users have access to the most current API functionalities. --- api-reference/openapi/sessions.json | 210 ---------------------------- 1 file changed, 210 deletions(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 997db42..eeadd0b 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -227,152 +227,6 @@ } } }, - "/api/sessions/{sessionId}/chats": { - "get": { - "summary": "List session chats", - "description": "Returns chat summaries for the session plus the caller's default model id for new chats.", - "parameters": [ - { - "name": "sessionId", - "in": "path", - "required": true, - "description": "The id of the session whose chats to list.", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Chats retrieved successfully.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListSessionChatsResponse" - } - } - } - }, - "401": { - "description": "Unauthorized — invalid or missing API key / Bearer token.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "403": { - "description": "Forbidden — the authenticated account does not own this session.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "Not found — no session exists with the given id.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "post": { - "summary": "Create session chat", - "description": "Creates a new chat in the session. Optional body may include `id` to use a client-generated id when idempotent creation is needed.", - "parameters": [ - { - "name": "sessionId", - "in": "path", - "required": true, - "description": "The id of the session to attach the chat to.", - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateSessionChatRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Chat created or returned (idempotent when `id` matches an existing chat in this session).", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateSessionChatResponse" - } - } - } - }, - "400": { - "description": "Bad request — invalid optional `id` in body.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized — invalid or missing API key / Bearer token.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "403": { - "description": "Forbidden — the authenticated account does not own this session.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "Not found — no session exists with the given id.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "409": { - "description": "Conflict — requested `id` belongs to a chat in another session.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, "/api/sessions/{sessionId}/chats": { "get": { "summary": "List session chats", @@ -610,70 +464,6 @@ } } }, - "ChatSummary": { - "allOf": [ - { - "$ref": "#/components/schemas/Chat" - }, - { - "type": "object", - "required": [ - "hasUnread", - "isStreaming" - ], - "properties": { - "hasUnread": { - "type": "boolean", - "description": "Whether the caller has unread assistant activity in this chat." - }, - "isStreaming": { - "type": "boolean", - "description": "True when an assistant stream is active (`activeStreamId` is set)." - } - } - } - ] - }, - "ListSessionChatsResponse": { - "type": "object", - "required": [ - "chats", - "defaultModelId" - ], - "properties": { - "chats": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ChatSummary" - } - }, - "defaultModelId": { - "type": "string", - "description": "Default AI Gateway model id for new chats in this product context." - } - } - }, - "CreateSessionChatRequest": { - "type": "object", - "description": "All fields are optional. An empty body creates a chat with a server-generated id.", - "properties": { - "id": { - "type": "string", - "description": "Optional client-generated chat id. When supplied, creation is idempotent for chats already in this session; if the id exists on another session, the request fails with 409." - } - } - }, - "CreateSessionChatResponse": { - "type": "object", - "required": [ - "chat" - ], - "properties": { - "chat": { - "$ref": "#/components/schemas/Chat" - } - } - }, "GetSessionResponse": { "type": "object", "required": [ From 2496fd5a7a54b55404dc014430df5fc65b88ff01 Mon Sep 17 00:00:00 2001 From: john Date: Thu, 14 May 2026 04:09:16 +0700 Subject: [PATCH 8/8] docs(sessions): update OpenAPI frontmatter for session endpoints Revised the `openapi` field in multiple session-related documentation files to include the path to the OpenAPI specification. This change enhances clarity and consistency across the API documentation for session management functionalities. --- api-reference/sessions/create-chat.mdx | 2 +- api-reference/sessions/create.mdx | 2 +- api-reference/sessions/get.mdx | 2 +- api-reference/sessions/list-chats.mdx | 2 +- api-reference/sessions/patch.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api-reference/sessions/create-chat.mdx b/api-reference/sessions/create-chat.mdx index fec8772..9dfc7b8 100644 --- a/api-reference/sessions/create-chat.mdx +++ b/api-reference/sessions/create-chat.mdx @@ -1,4 +1,4 @@ --- title: "Create Session Chat" -openapi: 'POST /api/sessions/{sessionId}/chats' +openapi: "/api-reference/openapi/sessions.json POST /api/sessions/{sessionId}/chats" --- diff --git a/api-reference/sessions/create.mdx b/api-reference/sessions/create.mdx index eb17d0a..f73e290 100644 --- a/api-reference/sessions/create.mdx +++ b/api-reference/sessions/create.mdx @@ -1,4 +1,4 @@ --- title: "Create Session" -openapi: 'POST /api/sessions' +openapi: "/api-reference/openapi/sessions.json POST /api/sessions" --- diff --git a/api-reference/sessions/get.mdx b/api-reference/sessions/get.mdx index b7029f4..483ac1b 100644 --- a/api-reference/sessions/get.mdx +++ b/api-reference/sessions/get.mdx @@ -1,4 +1,4 @@ --- title: "Get Session" -openapi: 'GET /api/sessions/{sessionId}' +openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" --- diff --git a/api-reference/sessions/list-chats.mdx b/api-reference/sessions/list-chats.mdx index 5fc661b..dc4a2a3 100644 --- a/api-reference/sessions/list-chats.mdx +++ b/api-reference/sessions/list-chats.mdx @@ -1,4 +1,4 @@ --- title: "List Session Chats" -openapi: 'GET /api/sessions/{sessionId}/chats' +openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}/chats" --- diff --git a/api-reference/sessions/patch.mdx b/api-reference/sessions/patch.mdx index ed3654f..f09b441 100644 --- a/api-reference/sessions/patch.mdx +++ b/api-reference/sessions/patch.mdx @@ -1,4 +1,4 @@ --- title: "Update Session" -openapi: 'PATCH /api/sessions/{sessionId}' +openapi: "/api-reference/openapi/sessions.json PATCH /api/sessions/{sessionId}" ---