docs(sessions): add PATCH /api/sessions/{sessionId} endpoint and update navigation#200
Conversation
…te 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.
📝 WalkthroughWalkthroughThis PR adds a complete PATCH endpoint for updating sessions. It defines a request schema with optional fields, implements the OpenAPI operation, documents it in MDX, and registers the documentation page in the navigation sidebar. ChangesSession PATCH Endpoint Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api-reference/openapi/sessions.json`:
- Around line 289-305: The PatchSessionRequest.status schema currently allows
null which conflicts with the Session.status enum; update the OpenAPI spec so
PatchSessionRequest.status matches Session.status by removing the null branch
from the anyOf (i.e., only allow the enum strings
"running","completed","failed","archived"), or alternatively add explicit null
semantics (document what null means and update Session.status/model and any
server-side handling in the Session controller to accept null). Ensure the
change references PatchSessionRequest.status and Session.status so generated
clients and server validation share the same contract.
In `@api-reference/sessions/patch.mdx`:
- Line 3: The frontmatter value uses the spec-file-prefixed form instead of the
required METHOD /path format; update the openapi frontmatter (the openapi: key
in api-reference MDX) to use "PATCH /api/sessions/{sessionId}" (i.e., replace
the current '/api-reference/openapi/sessions.json PATCH
/api/sessions/{sessionId}' entry with the canonical "PATCH
/api/sessions/{sessionId}" string) so it follows the required API-reference
openapi format.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a236a7ad-26d0-46fd-9e31-6850b2ee08c4
📒 Files selected for processing (3)
api-reference/openapi/sessions.jsonapi-reference/sessions/patch.mdxdocs.json
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 3 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/sessions.json">
<violation number="1" location="api-reference/openapi/sessions.json:290">
P2: `PatchSessionRequest.status` permits values (`completed`, `failed`, `null`) that contradict the endpoint’s documented archive/unarchive behavior.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
- 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.
…te 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.
- 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.
sweetmantech
force-pushed
the
docs/patch-session-by-id
branch
from
cd0acea to
578ad7a
Compare
Finding:
|
| Field | DB column | Persists? |
|---|---|---|
title |
title TEXT NOT NULL |
✓ |
status |
status TEXT ... CHECK (...) |
✓ |
linesAdded |
lines_added INTEGER DEFAULT 0 |
✓ |
linesRemoved |
lines_removed INTEGER DEFAULT 0 |
✓ |
prNumber |
no column | ✗ silently no-op |
prStatus |
no column | ✗ silently no-op |
So only linesAdded and linesRemoved should be added to the spec. Documenting prNumber / prStatus would mislead callers — the API accepts them without error, but nothing happens.
(prNumber / prStatus being in the handler interface looks like a separate handler-side bug — not something this docs PR should propagate.)
Suggested final shape
"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": {
"type": "string",
"enum": ["running", "completed", "failed", "archived"],
"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."
}
}
}Reproduce this independently (prompt for your LLM)
If you want your own coding agent to re-derive these findings before applying them, paste this block. It is self-contained — anyone with bash + grep on the monorepo can run it:
You're investigating whether the docs PR for
PATCH /api/sessions/{sessionId}accurately describes the endpoint. Treat the Supabase migration as the ground truth, not the route handler's TypeScript interface.Steps:
Read the route handler at
open-agents/apps/web/app/api/sessions/[sessionId]/route.ts(thePATCHexport). Note what itsUpdateSessionRequestinterface says it accepts.Read
open-agents/apps/web/lib/db/sessions.tsfor theupdateSessionfunction. Confirm it passes the body straight to Drizzle's.set({ ...data }). Note that Drizzle silently drops keys that don't match a column in the schema — no runtime error, no log line, nothing.Open
recoupable/database/supabase/migrations/and find the migration that creates thesessionstable (grep -rln "CREATE TABLE.*sessions\b" database/supabase/migrations/). This is the canonical column list.For each field in
UpdateSessionRequest, check whether a corresponding column exists in the migration. Note thestatuscolumn has aCHECK (status IN (...))constraint — that's the authoritative enum.Build a 3-column table:
field → DB column? → persists?. Anything that's "no column" gets silently no-op'd — the route accepts it but nothing changes.Report which fields should be added to the docs'
PatchSessionRequestschema (the persisted ones only), and which enum values should be in the documentedstatus.Expected finding: docs should document
title,status(4 values),linesAdded,linesRemoved. Do NOT documentprNumber/prStatus— those are present in the handler interface but have no DB columns, so they're silent no-ops. That's a separate handler-side bug to flag, not something to propagate into the public contract.
…ble/docs into docs/patch-session-by-id
…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.
There was a problem hiding this comment.
1 issue found across 4 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/sessions.json">
<violation number="1" location="api-reference/openapi/sessions.json:445">
P2: `PatchSessionRequest` exposes `linesAdded`/`linesRemoved` as client-writable fields even though they are documented as cached metrics, which makes the request contract inconsistent and likely incorrect.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
| ], | ||
| "description": "Lifecycle status. Use `archived` to archive, `running` to unarchive." | ||
| }, | ||
| "linesAdded": { |
There was a problem hiding this comment.
P2: PatchSessionRequest exposes linesAdded/linesRemoved as client-writable fields even though they are documented as cached metrics, which makes the request contract inconsistent and likely incorrect.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/sessions.json, line 445:
<comment>`PatchSessionRequest` exposes `linesAdded`/`linesRemoved` as client-writable fields even though they are documented as cached metrics, which makes the request contract inconsistent and likely incorrect.</comment>
<file context>
@@ -290,9 +436,85 @@
- "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,
</file context>
Tip: Review your code locally with the cubic CLI to iterate faster.
…istency - 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.
…ble/docs into docs/patch-session-by-id
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api-reference/openapi/sessions.json`:
- Around line 613-676: Remove the earlier duplicate OpenAPI schema objects for
ChatSummary, ListSessionChatsResponse, CreateSessionChatRequest, and
CreateSessionChatResponse (the first occurrence of each in components.schemas)
so only the later, more complete definitions remain; locate the duplicate
definitions by their schema names (ChatSummary, ListSessionChatsResponse,
CreateSessionChatRequest, CreateSessionChatResponse) and delete the first block
for each, leaving the richer versions intact.
- Around line 230-374: The OpenAPI spec contains a duplicate path definition for
"/api/sessions/{sessionId}/chats"; remove the first (earlier) definition block
so only the more complete second definition remains, ensuring you delete the
entire JSON object for "/api/sessions/{sessionId}/chats" that appears first and
remove any leftover trailing comma so the resulting JSON is valid; verify the
remaining "/api/sessions/{sessionId}/chats" entry (the later one) contains the
desired GET/POST schemas and responses.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 3b57ec95-cfc3-4f11-9532-23479d11709c
📒 Files selected for processing (7)
api-reference/openapi/sessions.jsonapi-reference/sessions/create-chat.mdxapi-reference/sessions/create.mdxapi-reference/sessions/get.mdxapi-reference/sessions/list-chats.mdxapi-reference/sessions/patch.mdxdocs.json
✅ Files skipped from review due to trivial changes (6)
- api-reference/sessions/list-chats.mdx
- api-reference/sessions/create-chat.mdx
- api-reference/sessions/create.mdx
- api-reference/sessions/get.mdx
- api-reference/sessions/patch.mdx
- docs.json
- 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.
|
Confirmed — my earlier finding has been implemented on the current branch.
Schema matches the suggested final shape. Thanks for the quick turnaround. |
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.
| --- | ||
| title: "Create Session Chat" | ||
| openapi: "/api-reference/openapi/sessions.json POST /api/sessions/{sessionId}/chats" | ||
| openapi: 'POST /api/sessions/{sessionId}/chats' |
There was a problem hiding this comment.
Why are you removing information resolution from this endpoint? The JSON path is important, right?
2 participants
PatchSessionRequestand updated theGetSessionResponse.This change enhances the API's functionality by providing a way to modify existing sessions, improving user experience and flexibility.
Summary by cubic
Add docs for PATCH
/api/sessions/{sessionId}to rename or archive/unarchive a session. Updated navigation and standardizedopenapifrontmatter to include the spec path across session pages./api/sessions/{sessionId}: optional body (title,status:running|archived,linesAdded,linesRemoved; omitted fields unchanged); returnsGetSessionResponse; errors400/401/403/404/500.Written for commit 2496fd5. Summary will update on new commits.
Summary by CodeRabbit