docs(sessions): add GET /api/sessions/{sessionId} reference#185
Merged
sweetmantech merged 1 commit intomainfrom May 4, 2026
Merged
docs(sessions): add GET /api/sessions/{sessionId} reference#185sweetmantech merged 1 commit intomainfrom
sweetmantech merged 1 commit intomainfrom
Conversation
📝 WalkthroughWalkthroughThis PR adds comprehensive API documentation for agent sessions. It introduces a new OpenAPI specification for the ChangesAgent Sessions API & Navigation Consolidation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
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)
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 |
![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:146">
P2: OpenAPI 3.1 schema uses deprecated `nullable`; represent nullable fields with JSON Schema null unions instead.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| @@ -0,0 +1,276 @@ | |||
| { | |||
There was a problem hiding this comment.
P2: OpenAPI 3.1 schema uses deprecated nullable; represent nullable fields with JSON Schema null unions instead.
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 146:
<comment>OpenAPI 3.1 schema uses deprecated `nullable`; represent nullable fields with JSON Schema null unions instead.</comment>
<file context>
@@ -0,0 +1,276 @@
+ },
+ "repoOwner": {
+ "type": "string",
+ "nullable": true,
+ "description": "GitHub repo owner if the session is bound to a repository."
+ },
</file context>
![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
🧹 Nitpick comments (1)
api-reference/openapi/sessions.json (1)
26-82: ⚡ Quick winAdd an
operationIdto the GET operation.
operationIdis used by Mintlify for anchor generation, by SDK generators for method naming, and by testing tools for operation identification.✏️ Proposed addition
"get": { + "operationId": "getSessionById", "summary": "Get session by id",🤖 Prompt for 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. In `@api-reference/openapi/sessions.json` around lines 26 - 82, Add an operationId to the GET operation for "Get session by id" so tools can generate stable anchors and method names; open the GET operation object with summary "Get session by id" and add an "operationId" property (e.g., "getSessionById" or "getSession") at the same level as "summary" and "description" so SDK generators and tests can identify this operation (the response schema ref is "#/components/schemas/GetSessionResponse" which helps confirm you are editing the correct operation).
🤖 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 144-259: The Session schema uses the removed OpenAPI 3.1
"nullable": true on many properties — replace each occurrence with JSON-Schema
style nullability: change "type": "string"/"integer"/"object"/"string" with
"format":"date-time" to "type": ["<T>", "null"] (e.g., repoOwner, repoName,
branch, cloneUrl, lifecycleRunId, lifecycleError, snapshotUrl -> type:
["string","null"]; linesAdded, linesRemoved, snapshotSizeBytes -> type:
["integer","null"]; lastActivityAt, sandboxExpiresAt, hibernateAfter,
snapshotCreatedAt, cachedDiffUpdatedAt -> type: ["string","null"] and keep
"format":"date-time"; sandboxState, cachedDiff -> type: ["object","null"]), and
convert lifecycleState to an anyOf with a string enum and null (e.g., anyOf:
[{type:"string", enum:[...]} , {type:"null"}]); also add a missing operationId
to the GET operation that returns Session so SDKs/documentation can generate
stable method names.
In `@api-reference/sessions/get.mdx`:
- Around line 2-3: Add a missing frontmatter description and ensure the openapi
frontmatter matches project guideline: update the frontmatter in the Get Session
page by adding a descriptive `description` field (e.g., "Retrieve a session by
ID") and either change the `openapi` value from
"/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" to the
guideline format "GET /api/sessions/{sessionId}" (if global spec registration
will be used) or keep the current file-scoped form but document/register the
spec globally in docs.json; modify the frontmatter keys `title` and `openapi`
accordingly to reflect this fix.
---
Nitpick comments:
In `@api-reference/openapi/sessions.json`:
- Around line 26-82: Add an operationId to the GET operation for "Get session by
id" so tools can generate stable anchors and method names; open the GET
operation object with summary "Get session by id" and add an "operationId"
property (e.g., "getSessionById" or "getSession") at the same level as "summary"
and "description" so SDK generators and tests can identify this operation (the
response schema ref is "#/components/schemas/GetSessionResponse" which helps
confirm you are editing the correct operation).
🪄 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: f55607c2-12c8-45af-9d35-daacc14c866d
📒 Files selected for processing (3)
api-reference/openapi/sessions.jsonapi-reference/sessions/get.mdxdocs.json
Comment on lines
+144
to
+259
| "repoOwner": { | ||
| "type": "string", | ||
| "nullable": true, | ||
| "description": "GitHub repo owner if the session is bound to a repository." | ||
| }, | ||
| "repoName": { | ||
| "type": "string", | ||
| "nullable": true | ||
| }, | ||
| "branch": { | ||
| "type": "string", | ||
| "nullable": true | ||
| }, | ||
| "cloneUrl": { | ||
| "type": "string", | ||
| "nullable": true, | ||
| "description": "Clone URL the sandbox should fetch from." | ||
| }, | ||
| "isNewBranch": { | ||
| "type": "boolean", | ||
| "description": "True when this session created and pushed a new branch (not committing back to the original)." | ||
| }, | ||
| "globalSkillRefs": { | ||
| "type": "array", | ||
| "description": "Skills attached to the agent at provision time.", | ||
| "items": { | ||
| "type": "object", | ||
| "additionalProperties": true | ||
| } | ||
| }, | ||
| "sandboxState": { | ||
| "type": "object", | ||
| "nullable": true, | ||
| "additionalProperties": true, | ||
| "description": "Sandbox runtime state (Vercel Sandbox)." | ||
| }, | ||
| "lifecycleState": { | ||
| "type": "string", | ||
| "nullable": true, | ||
| "enum": [ | ||
| "provisioning", | ||
| "active", | ||
| "hibernating", | ||
| "hibernated", | ||
| "restoring", | ||
| "archived", | ||
| "failed" | ||
| ], | ||
| "description": "Lifecycle orchestration state for the sandbox." | ||
| }, | ||
| "lifecycleVersion": { | ||
| "type": "integer", | ||
| "description": "Optimistic concurrency token for lifecycle transitions." | ||
| }, | ||
| "lastActivityAt": { | ||
| "type": "string", | ||
| "format": "date-time", | ||
| "nullable": true | ||
| }, | ||
| "sandboxExpiresAt": { | ||
| "type": "string", | ||
| "format": "date-time", | ||
| "nullable": true | ||
| }, | ||
| "hibernateAfter": { | ||
| "type": "string", | ||
| "format": "date-time", | ||
| "nullable": true | ||
| }, | ||
| "lifecycleRunId": { | ||
| "type": "string", | ||
| "nullable": true | ||
| }, | ||
| "lifecycleError": { | ||
| "type": "string", | ||
| "nullable": true | ||
| }, | ||
| "linesAdded": { | ||
| "type": "integer", | ||
| "nullable": true | ||
| }, | ||
| "linesRemoved": { | ||
| "type": "integer", | ||
| "nullable": true | ||
| }, | ||
| "snapshotUrl": { | ||
| "type": "string", | ||
| "nullable": true | ||
| }, | ||
| "snapshotCreatedAt": { | ||
| "type": "string", | ||
| "format": "date-time", | ||
| "nullable": true | ||
| }, | ||
| "snapshotSizeBytes": { | ||
| "type": "integer", | ||
| "nullable": true | ||
| }, | ||
| "cachedDiff": { | ||
| "type": "object", | ||
| "nullable": true, | ||
| "additionalProperties": true | ||
| }, | ||
| "cachedDiffUpdatedAt": { | ||
| "type": "string", | ||
| "format": "date-time", | ||
| "nullable": true | ||
| }, | ||
| "createdAt": { | ||
| "type": "string", | ||
| "format": "date-time" | ||
| }, | ||
| "updatedAt": { | ||
| "type": "string", | ||
| "format": "date-time" | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, check if the file exists and get basic info
ls -la api-reference/openapi/sessions.json
wc -l api-reference/openapi/sessions.jsonRepository: recoupable/docs
Length of output: 184
🏁 Script executed:
# Check the OpenAPI version declaration
head -20 api-reference/openapi/sessions.jsonRepository: recoupable/docs
Length of output: 538
🏁 Script executed:
# Count nullable occurrences in the Session schema (lines 144-259)
sed -n '144,259p' api-reference/openapi/sessions.json | grep -c "nullable"Repository: recoupable/docs
Length of output: 62
🏁 Script executed:
# Check the GET operation structure (lines 26-82)
sed -n '26,82p' api-reference/openapi/sessions.jsonRepository: recoupable/docs
Length of output: 1837
🏁 Script executed:
# Check if operationId is present in the GET operation
sed -n '26,82p' api-reference/openapi/sessions.json | grep -i "operationId"Repository: recoupable/docs
Length of output: 41
🌐 Web query:
OpenAPI 3.1.0 nullable specification removed deprecated
💡 Result:
In OpenAPI 3.1.0, the nullable keyword was removed entirely from the specification, rather than just being deprecated. This change was made to align with JSON Schema 2020-12, where nullability is expressed using type: ["string", "null"] (or similar type arrays including "null") instead of a separate nullable: true modifier.[1][2][3] The removal occurred via a merged pull request targeting the 3.1.0 development branch in May 2020.[1] Official migration guides confirm this: replace nullable: true with type arrays.[4][3] The official spec documents (e.g., v3.1.1, which is backward-compatible with 3.1.0) do not list nullable as a Schema Object field.[5][6]
Citations:
- 1: Remove "nullable" entirely OAI/OpenAPI-Specification#2246
- 2: Remove "nullable" in OAS 3.1? OAI/OpenAPI-Specification#2244
- 3: https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
- 4: https://learn.openapis.org/upgrading/v3.0-to-v3.1.html
- 5: https://spec.openapis.org/oas/v3.1.1.html
- 6: https://spec.openapis.org/oas/v3.1.2.html
🏁 Script executed:
# Let's also check the entire Session schema structure to see all the nullable properties
sed -n '144,259p' api-reference/openapi/sessions.jsonRepository: recoupable/docs
Length of output: 3482
🌐 Web query:
OpenAPI 3.1 nullable removed JSON Schema deprecated
💡 Result:
In OpenAPI 3.1.0, the OpenAPI-specific 'nullable' keyword was removed entirely rather than deprecated [1][2][3]. This change aligns OpenAPI Schema Objects with JSON Schema Draft 2020-12, where nullability is expressed by including "null" in the 'type' array, such as type: ["string", "null"] [2][3][4][5]. The 'nullable' keyword from OpenAPI 3.0 is not part of JSON Schema and was eliminated to achieve full compatibility, not merely deprecated [1][2]. Official specs confirm data types now include "null" directly [4], and discussions clarify how to specify nullable properties using JSON Schema features [6]. JSON Schema Draft 2020-12 itself never had a 'nullable' keyword; it uses the 'type' keyword for this purpose [5][7].
Citations:
- 1: Remove "nullable" entirely OAI/OpenAPI-Specification#2246
- 2: https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
- 3: https://learn.openapis.org/upgrading/v3.0-to-v3.1.html
- 4: https://spec.openapis.org/oas/v3.1.2.html
- 5: https://json-schema.org/draft/2020-12/json-schema-validation.html
- 6: Clarification on nullable properties, OpenAPI 3.1 OAI/OpenAPI-Specification#3148
- 7: https://learnjsonschema.com/2020-12/validation/type
Replace nullable: true with type arrays — nullable is not valid in OpenAPI 3.1.0.
The nullable keyword was removed entirely from OpenAPI 3.1 to align with JSON Schema 2020-12, where nullability is expressed using type arrays. All 18 properties in the Session schema that use "nullable": true are non-conformant with the declared OpenAPI version and will fail validation with strict validators and SDK generators.
Replace "type": "<T>", "nullable": true with "type": ["<T>", "null"] for each affected field. For the lifecycleState enum, use anyOf to keep the enum constraint scoped to the string type:
🛠️ Representative fixes (apply the same pattern to all 18 affected properties)
Simple nullable scalar (e.g. repoOwner, repoName, branch, cloneUrl, lifecycleRunId, lifecycleError, snapshotUrl):
-"repoOwner": {
- "type": "string",
- "nullable": true,
- "description": "GitHub repo owner if the session is bound to a repository."
-}
+"repoOwner": {
+ "type": ["string", "null"],
+ "description": "GitHub repo owner if the session is bound to a repository."
+}Nullable integer (e.g. linesAdded, linesRemoved, snapshotSizeBytes):
-"linesAdded": {
- "type": "integer",
- "nullable": true
-}
+"linesAdded": {
+ "type": ["integer", "null"]
+}Nullable date-time (e.g. lastActivityAt, sandboxExpiresAt, hibernateAfter, snapshotCreatedAt, cachedDiffUpdatedAt):
-"lastActivityAt": {
- "type": "string",
- "format": "date-time",
- "nullable": true
-}
+"lastActivityAt": {
+ "type": ["string", "null"],
+ "format": "date-time"
+}Nullable object (e.g. sandboxState, cachedDiff):
-"sandboxState": {
- "type": "object",
- "nullable": true,
- "additionalProperties": true,
- "description": "Sandbox runtime state (Vercel Sandbox)."
-}
+"sandboxState": {
+ "type": ["object", "null"],
+ "additionalProperties": true,
+ "description": "Sandbox runtime state (Vercel Sandbox)."
+}Nullable enum (lifecycleState):
-"lifecycleState": {
- "type": "string",
- "nullable": true,
- "enum": ["provisioning", "active", "hibernating", "hibernated", "restoring", "archived", "failed"],
- "description": "Lifecycle orchestration state for the sandbox."
-}
+"lifecycleState": {
+ "anyOf": [
+ {
+ "type": "string",
+ "enum": ["provisioning", "active", "hibernating", "hibernated", "restoring", "archived", "failed"]
+ },
+ { "type": "null" }
+ ],
+ "description": "Lifecycle orchestration state for the sandbox."
+}Additionally, the GET operation (lines 26–82) is missing an operationId. This is recommended practice for OpenAPI specs as it's used by SDK generators for method naming and documentation tools for anchoring.
🧰 Tools
🪛 Checkov (3.2.526)
[medium] 166-172: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🤖 Prompt for 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.
In `@api-reference/openapi/sessions.json` around lines 144 - 259, The Session
schema uses the removed OpenAPI 3.1 "nullable": true on many properties —
replace each occurrence with JSON-Schema style nullability: change "type":
"string"/"integer"/"object"/"string" with "format":"date-time" to "type":
["<T>", "null"] (e.g., repoOwner, repoName, branch, cloneUrl, lifecycleRunId,
lifecycleError, snapshotUrl -> type: ["string","null"]; linesAdded,
linesRemoved, snapshotSizeBytes -> type: ["integer","null"]; lastActivityAt,
sandboxExpiresAt, hibernateAfter, snapshotCreatedAt, cachedDiffUpdatedAt ->
type: ["string","null"] and keep "format":"date-time"; sandboxState, cachedDiff
-> type: ["object","null"]), and convert lifecycleState to an anyOf with a
string enum and null (e.g., anyOf: [{type:"string", enum:[...]} ,
{type:"null"}]); also add a missing operationId to the GET operation that
returns Session so SDKs/documentation can generate stable method names.
Comment on lines
+2
to
+3
| title: "Get Session" | ||
| openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" |
There was a problem hiding this comment.
Add a description field and verify the openapi reference format against the project guideline.
The openapi value "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" matches the Mintlify format for MDX pages that reference a specific local spec file, and is technically correct. However, the coding guideline for api-reference/**/*.mdx specifies the format as openapi: 'METHOD /path' (i.e., without a file-path prefix), which implies global spec registration via docs.json. Since docs.json has no global openapi entry, the per-file format is the working approach — but the guideline should be updated to match, or the spec registered globally.
Additionally, the page is missing a description frontmatter field. As per coding guidelines, **/*.mdx files should "Use clear, self-documenting titles and descriptions in documentation."
📝 Proposed fix
---
title: "Get Session"
+description: "Retrieve a single agent session by its ID."
openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}"
---📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| title: "Get Session" | |
| openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" | |
| --- | |
| title: "Get Session" | |
| description: "Retrieve a single agent session by its ID." | |
| openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" | |
| --- |
🤖 Prompt for 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.
In `@api-reference/sessions/get.mdx` around lines 2 - 3, Add a missing frontmatter
description and ensure the openapi frontmatter matches project guideline: update
the frontmatter in the Get Session page by adding a descriptive `description`
field (e.g., "Retrieve a session by ID") and either change the `openapi` value
from "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" to the
guideline format "GET /api/sessions/{sessionId}" (if global spec registration
will be used) or keep the current file-scoped form but document/register the
spec globally in docs.json; modify the frontmatter keys `title` and `openapi`
accordingly to reflect this fix.
3 tasks
sweetmantech
added a commit
that referenced
this pull request
May 4, 2026
Per PR feedback: this PR is scoped to POST only. Removes the GET endpoint page, OpenAPI path, GetSessionResponse schema, and the nav reference to it. The GET docs ship in PR #185. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
sweetmantech
added a commit
that referenced
this pull request
May 4, 2026
* docs(sessions): add GET /api/sessions/{sessionId} reference
Documents the first endpoint ported in the open-agents -> api migration
(api PR #514). Establishes the reference shape for the Agent Sessions
endpoint family — subsequent ports (list, chats, etc.) will land in
this same group.
Files:
api-reference/openapi/sessions.json
New OpenAPI 3.1 spec for the agent-sessions endpoint family.
Documents GET /api/sessions/{sessionId} with the full Session
schema (camelCase wire format that mirrors what api returns).
Auth: x-api-key header or Bearer token.
Response codes: 200 / 401 / 403 / 404.
api-reference/sessions/get.mdx
Frontmatter-only, per repo convention. References the OpenAPI
spec — Mintlify auto-generates the page from there.
docs.json
Adds an "Agent Sessions" group under the API Reference tab,
immediately after Sandboxes. One entry today; subsequent route
ports add their pages here.
Naming note in the schema: the Session.userId field is documented
explicitly as "named userId for client compatibility; on the server
side this is account_id". Captures the wire-format-vs-schema name
difference that exists during the cutover window so consumers reading
the docs alongside the database schema do not get confused.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(nav): introduce Agents & Sandboxes top-level tab (Phase 1 restructure)
Hoists agent + sandbox concepts out of three different tabs into a
single dedicated top-level. Addresses the structural problem where
"Content" had become a junk drawer for anything sandbox- or
agent-shaped, and agent concepts were scattered across five locations
(Quickstart > Agents, Artists > Tasks, Content > Sandboxes,
Content > Agent Sessions, Content > Content Agent, Accounts > Agent
Onboarding).
Moves into new "Agents & Sandboxes" tab (in this order — onboarding
first, primitives last):
Agent Onboarding ← was Accounts > Agent Onboarding
Agents ← was Quickstart > Agents (intro pages)
Tasks ← was Artists > Tasks
Content Agent ← was Content > Content Agent
Sandboxes ← was Content > Sandboxes
Agent Sessions ← stayed under Content (added in this PR)
Tab placement: between Social Media and Accounts. The workflow tabs
(Artists, Research, Releases, Content, Social Media) stay together;
Agents & Sandboxes sits as the platform's differentiated capability
just before the platform-mechanics tab (Accounts).
Net effect on each existing tab:
Quickstart Agents group removed → just "Getting started" now
Artists Tasks group removed (background-job concept lives
with the agents that drive it)
Content Three groups removed (Content Agent, Sandboxes,
Agent Sessions). Content is now coherent: creation,
posts/comments, image, transcribe.
Accounts Agent Onboarding removed (moved to its true home)
No MDX file paths change — all moves are within docs.json. External
deep links to specific pages stay valid; only tab/group anchors
change.
This is Phase 1 of a four-phase restructure outlined in PR
discussion. Phases 2-4 (rationalize Content remainder, split Accounts
into Platform + Tools & Reference, rebalance Releases) are deferred
to follow-up PRs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(nav): consolidate Content + extract Tools & Reference (Phases 2-3)
Phase 2 — Content tab: fold the single-page Image and Transcribe groups
into Content Creation. They are content-creation utilities; one-page
groups under Content were over-segmentation that made the tab look
fuller than it is. Image generation and audio transcription now sit
alongside the other generate-* / transcribe-* endpoints they belong
with.
Phase 3 — extract Tools & Reference: pull Connectors and AI (model
catalog) out of the Accounts tab into a new top-level "Tools &
Reference" tab. Both are dev-reference content, not account
mechanics. Accounts is now coherent: account-mechanics only (Accounts,
Organizations, Workspaces, Subscriptions, Admins, Pulses,
Notifications).
Phase 4 (rebalance Releases) intentionally skipped: Releases is
sparsely populated (1 group, ~8 pages) but architecturally fine.
Folding it into Artists or artificially growing it is cosmetic.
Will fill in as more endpoints land.
Final structure (9 tabs):
Quickstart Getting started
Artists Workflows · Artists · Fans
Research 8 groups (unchanged)
Releases Songs & Catalogs
Content Content Creation · Posts & Comments ← Phase 2
Social Media Social · Spotify · Apify
Agents & Sandboxes 6 groups (added in Phase 1)
Accounts 7 groups, account mechanics only ← Phase 3
Tools & Reference Connectors · AI ← Phase 3 (NEW)
No MDX file paths change — all moves are within docs.json. External
deep links to specific pages stay valid; only tab/group anchors change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(nav): rename group "Agent Sessions" -> "Sessions" (KISS)
The "Agent" prefix was redundant. Every other artifact for this surface
already uses the bare term:
- URL: /api/sessions/{sessionId}
- OpenAPI file: sessions.json
- Folder: api-reference/sessions/
- MDX title: "Get Session"
- Schema type: Session
The "Agents & Sandboxes" tab already establishes context, so "Sessions"
under that tab reads naturally and unambiguously. Only places the old
label appeared:
docs.json (group label)
api-reference/openapi/sessions.json (title + description)
The Stripe checkout-session endpoints under Accounts > Subscriptions
remain at their distinct path (/api/subscriptions/sessions), so there
is no nav-level collision.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(sessions): trim description to single sentence (KISS)
The 403 ownership detail is already documented in the responses
section ("Forbidden - the authenticated account does not own this
session") — restating it in the description was redundant prose.
Description is now one sentence.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(sessions): add status:"error" to Error schema
api PR #514 returns {status:"error", error:"..."} for all error
responses (401/404/403). The OpenAPI Error schema only documented
{error}. Add the status discriminator so the docs match what the
endpoint actually emits.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(sessions): add POST /api/sessions reference
Documents the create-session endpoint: optional body fields for repo
binding + commit/push overrides, transactional return of `{session, chat}`,
and 200/400/401/500 error envelope.
Also fills in four Session fields the GET reference was missing
(autoCommitPushOverride, autoCreatePrOverride, prNumber, prStatus) and
adds the new Chat schema for the initial chat row created alongside
the session. Captured the live shape from sandbox.recoupable.com so
the spec mirrors the open-agents response that downstream clients
will eventually cut over from.
Error envelope stays as `{error}` to match open-agents (no
status:error divergence here — that's a deliberate compatibility
choice for frontend cutover).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(sessions): drop GET reference from this PR
Per PR feedback: this PR is scoped to POST only. Removes the GET
endpoint page, OpenAPI path, GetSessionResponse schema, and the
nav reference to it. The GET docs ship in PR #185.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Restored after rebasing on main, which absorbed the nav restructure
and Error-schema changes that previously also lived in this branch.
Net diff vs main is now scoped to just the GET endpoint:
- New `api-reference/sessions/get.mdx`
- Adds `/api/sessions/{sessionId}` GET path + `GetSessionResponse`
schema to `api-reference/openapi/sessions.json`
- Adds `api-reference/sessions/get` to the Sessions nav group
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
sweetmantech
force-pushed
the
docs/get-session-by-id
branch
from
a846f2c to
5a2da65
Compare
sidneyswift
added a commit
that referenced
this pull request
May 6, 2026
PR #174's nav structure was written Apr 27, before three pages were added to main: - api-reference/ai/models (added by #177 on May 1) - api-reference/sessions/create (added by #186 on May 3) - api-reference/sessions/get (added by #185 on May 4) These pages exist on disk but had no nav entry in the combined PR, which would orphan them once #189 lands. Adding them in: - Accounts tab → new "Sessions" group placed after "Sandboxes" (matches main's grouping of sessions with sandboxes) - Chat tab → new "Models" group at the end (closest semantic fit; main grouped this under "Tools & Reference" which doesn't exist in our restructured 9-tab layout) Co-authored-by: Cursor <cursoragent@cursor.com>
sidneyswift
added a commit
that referenced
this pull request
May 6, 2026
Spotted by a rendered-page review. Two pages had outdated or misleading content that needed correction: index.mdx: - "any of the 40+ endpoints" -> "130+ endpoints" (actual: 137 across all 7 OpenAPI specs) - "running a label" -> "running a music business" (matches the homepage lead paragraph that was already broadened) - Artists card: removed "and comments" — that endpoint was deleted in f896bc7 because it has no API handler. Card now reads "browse fans and posts" - Artists / Catalog cards: "your label" -> "your roster" (consistent with broader audience framing) - Content card: "7 endpoints" -> "11 endpoints" (7 primitives + create, estimate, validate, templates) - Quickstart bullet vs Quickstart Guides card: now both say "Under a minute" (was inconsistent — one said "~5 minutes") - For AI agents OpenAPI table: added rows for ai.json (added by main #177) and sessions.json (added by main #185-187). Was missing 2 of 7 specs. mcp.mdx: - Reframe the "Org-scoped keys can target any account... Personal API keys can only operate on their own data" callout. The phrasing implied two key types exist, which is wrong — there's only one key type, and access is determined by the OWNER ACCOUNT's organization membership. New phrasing matches /authentication's access rules and explicitly says there's no separate "org-scoped" key type. Links out to /authentication#access-control for the full ladder.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the first endpoint in the open-agents → api migration (api PR #514). Establishes the docs shape for the Agent Sessions endpoint family — subsequent ports (list, chats, chats by id, etc.) will land in this same group.
Files
Naming note
`Session.userId` is documented explicitly as "named `userId` for client compatibility; on the server side this is `account_id`". Captures the wire-format-vs-schema name difference that exists during the open-agents-frontend cutover window. When the migration is complete and the wire format can be redesigned, the doc + the route handler's `toSessionResponse` translator can be updated together.
Validation
🤖 Generated with Claude Code
Summary by cubic
Adds API reference for
GET /api/sessions/{sessionId}and links it in the Sessions group to document fetching a single agent session.GET /api/sessions/{sessionId}returningGetSessionResponse.session(Sessionschema) with 200/401/403/404.x-api-keyorBearerauth.api-reference/sessions/get.mdxfor Mintlify auto-generation.api-reference/sessions/getto the Sessions nav group.Written for commit 5a2da65. Summary will update on new commits.
Summary by CodeRabbit
Release Notes
New Features
Documentation