From 86c307fbdc6f471d605d11790e9505abe66d7ebc Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Mon, 4 May 2026 15:21:59 -0500 Subject: [PATCH 1/8] docs(sessions): add GET /api/sessions/{sessionId} reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- api-reference/openapi/sessions.json | 276 ++++++++++++++++++++++++++++ api-reference/sessions/get.mdx | 4 + docs.json | 6 + 3 files changed, 286 insertions(+) create mode 100644 api-reference/openapi/sessions.json create mode 100644 api-reference/sessions/get.mdx diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json new file mode 100644 index 0000000..f5d2dd4 --- /dev/null +++ b/api-reference/openapi/sessions.json @@ -0,0 +1,276 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Recoup API - Agent Sessions", + "description": "Agent sessions — sandboxed runs of an LLM-driven agent with tool use, lifecycle hooks, and persistence. Each session pairs one Vercel Sandbox with one or more chat threads.", + "license": { + "name": "MIT" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.recoupable.com" + } + ], + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ], + "paths": { + "/api/sessions/{sessionId}": { + "get": { + "summary": "Get session by id", + "description": "Returns a single agent session by its id. The authenticated account must own the session — requests for sessions owned by other accounts return 403.", + "parameters": [ + { + "name": "sessionId", + "in": "path", + "required": true, + "description": "The id of the session to fetch.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Session retrieved successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetSessionResponse" + } + } + } + }, + "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" + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "ApiKeyAuth": { + "type": "apiKey", + "in": "header", + "name": "x-api-key" + }, + "BearerAuth": { + "type": "http", + "scheme": "bearer" + } + }, + "schemas": { + "GetSessionResponse": { + "type": "object", + "required": [ + "session" + ], + "properties": { + "session": { + "$ref": "#/components/schemas/Session" + } + } + }, + "Session": { + "type": "object", + "required": [ + "id", + "userId", + "title", + "status", + "isNewBranch", + "globalSkillRefs", + "lifecycleVersion", + "createdAt", + "updatedAt" + ], + "properties": { + "id": { + "type": "string", + "description": "Session id (nanoid)." + }, + "userId": { + "type": "string", + "format": "uuid", + "description": "Owning account id. Named `userId` here for compatibility with existing clients; on the server side this is the account_id foreign key into the accounts table." + }, + "title": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "running", + "completed", + "failed", + "archived" + ] + }, + "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" + } + } + }, + "Error": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "Human-readable error message." + } + } + } + } + } +} diff --git a/api-reference/sessions/get.mdx b/api-reference/sessions/get.mdx new file mode 100644 index 0000000..483ac1b --- /dev/null +++ b/api-reference/sessions/get.mdx @@ -0,0 +1,4 @@ +--- +title: "Get Session" +openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" +--- diff --git a/docs.json b/docs.json index 0ea3137..ccf5154 100644 --- a/docs.json +++ b/docs.json @@ -235,6 +235,12 @@ "api-reference/sandboxes/file", "api-reference/sandboxes/upload" ] + }, + { + "group": "Agent Sessions", + "pages": [ + "api-reference/sessions/get" + ] } ] }, From a3d0669091277cf7105fd00de176e51b3d662e8f Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Mon, 4 May 2026 15:44:33 -0500 Subject: [PATCH 2/8] docs(nav): introduce Agents & Sandboxes top-level tab (Phase 1 restructure) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs.json | 91 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 43 deletions(-) diff --git a/docs.json b/docs.json index ccf5154..5b7433d 100644 --- a/docs.json +++ b/docs.json @@ -22,13 +22,6 @@ "mcp", "authentication" ] - }, - { - "group": "Agents", - "pages": [ - "agents", - "content-agent" - ] } ] }, @@ -60,16 +53,6 @@ "pages": [ "api-reference/fans/get" ] - }, - { - "group": "Tasks", - "pages": [ - "api-reference/tasks/get", - "api-reference/tasks/create", - "api-reference/tasks/update", - "api-reference/tasks/delete", - "api-reference/tasks/runs" - ] } ] }, @@ -205,13 +188,6 @@ "api-reference/comments/get" ] }, - { - "group": "Content Agent", - "pages": [ - "api-reference/content-agent/webhook", - "api-reference/content-agent/callback" - ] - }, { "group": "Image", "pages": [ @@ -223,24 +199,6 @@ "pages": [ "api-reference/transcribe/audio" ] - }, - { - "group": "Sandboxes", - "pages": [ - "api-reference/sandboxes/list", - "api-reference/sandboxes/create", - "api-reference/sandboxes/snapshot", - "api-reference/sandboxes/delete", - "api-reference/sandboxes/setup", - "api-reference/sandboxes/file", - "api-reference/sandboxes/upload" - ] - }, - { - "group": "Agent Sessions", - "pages": [ - "api-reference/sessions/get" - ] } ] }, @@ -272,7 +230,7 @@ ] }, { - "tab": "Accounts", + "tab": "Agents & Sandboxes", "groups": [ { "group": "Agent Onboarding", @@ -281,6 +239,53 @@ "api-reference/agents/verify" ] }, + { + "group": "Agents", + "pages": [ + "agents", + "content-agent" + ] + }, + { + "group": "Tasks", + "pages": [ + "api-reference/tasks/get", + "api-reference/tasks/create", + "api-reference/tasks/update", + "api-reference/tasks/delete", + "api-reference/tasks/runs" + ] + }, + { + "group": "Content Agent", + "pages": [ + "api-reference/content-agent/webhook", + "api-reference/content-agent/callback" + ] + }, + { + "group": "Sandboxes", + "pages": [ + "api-reference/sandboxes/list", + "api-reference/sandboxes/create", + "api-reference/sandboxes/snapshot", + "api-reference/sandboxes/delete", + "api-reference/sandboxes/setup", + "api-reference/sandboxes/file", + "api-reference/sandboxes/upload" + ] + }, + { + "group": "Agent Sessions", + "pages": [ + "api-reference/sessions/get" + ] + } + ] + }, + { + "tab": "Accounts", + "groups": [ { "group": "Connectors", "pages": [ From ca65371ea77293e8b27c7179a5076c05b223b04e Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Mon, 4 May 2026 15:51:23 -0500 Subject: [PATCH 3/8] docs(nav): consolidate Content + extract Tools & Reference (Phases 2-3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs.json | 41 ++++++++++++++++++----------------------- 1 file changed, 18 insertions(+), 23 deletions(-) diff --git a/docs.json b/docs.json index 5b7433d..18c451e 100644 --- a/docs.json +++ b/docs.json @@ -178,7 +178,9 @@ "api-reference/content/templates", "api-reference/content/template-detail", "api-reference/content/validate", - "api-reference/content/estimate" + "api-reference/content/estimate", + "api-reference/image/generation", + "api-reference/transcribe/audio" ] }, { @@ -187,18 +189,6 @@ "api-reference/posts/get", "api-reference/comments/get" ] - }, - { - "group": "Image", - "pages": [ - "api-reference/image/generation" - ] - }, - { - "group": "Transcribe", - "pages": [ - "api-reference/transcribe/audio" - ] } ] }, @@ -286,16 +276,6 @@ { "tab": "Accounts", "groups": [ - { - "group": "Connectors", - "pages": [ - "api-reference/connectors/list", - "api-reference/connectors/authorize", - "api-reference/connectors/disconnect", - "api-reference/connectors/list-actions", - "api-reference/connectors/execute-action" - ] - }, { "group": "Pulses", "pages": [ @@ -353,6 +333,21 @@ "pages": [ "api-reference/notifications/create" ] + } + ] + }, + { + "tab": "Tools & Reference", + "groups": [ + { + "group": "Connectors", + "pages": [ + "api-reference/connectors/list", + "api-reference/connectors/authorize", + "api-reference/connectors/disconnect", + "api-reference/connectors/list-actions", + "api-reference/connectors/execute-action" + ] }, { "group": "AI", From 46edfd2ae2cde306f4a8c409fbfb2ebc455b9089 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Mon, 4 May 2026 15:56:43 -0500 Subject: [PATCH 4/8] 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) --- api-reference/openapi/sessions.json | 4 ++-- docs.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index f5d2dd4..3020a3a 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -1,8 +1,8 @@ { "openapi": "3.1.0", "info": { - "title": "Recoup API - Agent Sessions", - "description": "Agent sessions — sandboxed runs of an LLM-driven agent with tool use, lifecycle hooks, and persistence. Each session pairs one Vercel Sandbox with one or more chat threads.", + "title": "Recoup API - Sessions", + "description": "Sessions — sandboxed runs of an LLM-driven agent with tool use, lifecycle hooks, and persistence. Each session pairs one Vercel Sandbox with one or more chat threads.", "license": { "name": "MIT" }, diff --git a/docs.json b/docs.json index 18c451e..9b01739 100644 --- a/docs.json +++ b/docs.json @@ -266,7 +266,7 @@ ] }, { - "group": "Agent Sessions", + "group": "Sessions", "pages": [ "api-reference/sessions/get" ] From fc17438a9cfb9534b067d4e7e67d8882186847a3 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Mon, 4 May 2026 15:57:27 -0500 Subject: [PATCH 5/8] docs(sessions): trim description to single sentence (KISS) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- 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 3020a3a..5ec991e 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -25,7 +25,7 @@ "/api/sessions/{sessionId}": { "get": { "summary": "Get session by id", - "description": "Returns a single agent session by its id. The authenticated account must own the session — requests for sessions owned by other accounts return 403.", + "description": "Returns a single agent session by its id.", "parameters": [ { "name": "sessionId", From a846f2c78713e6a91285706f116fd1bd5761856f Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Mon, 4 May 2026 16:11:18 -0500 Subject: [PATCH 6/8] 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) --- api-reference/openapi/sessions.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 5ec991e..e30ebcd 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -262,9 +262,17 @@ "Error": { "type": "object", "required": [ + "status", "error" ], "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Always `\"error\"` for error responses." + }, "error": { "type": "string", "description": "Human-readable error message." From 15fb54b8ded93fdb1c698bb14684c9df7dae57c2 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Mon, 4 May 2026 16:20:59 -0500 Subject: [PATCH 7/8] docs(sessions): add POST /api/sessions reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- api-reference/openapi/sessions.json | 197 +++++++++++++++++++++++++++- api-reference/sessions/create.mdx | 4 + docs.json | 1 + 3 files changed, 200 insertions(+), 2 deletions(-) create mode 100644 api-reference/sessions/create.mdx diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index e30ebcd..9163890 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -22,6 +22,64 @@ } ], "paths": { + "/api/sessions": { + "post": { + "summary": "Create session", + "description": "Creates a new agent session and an initial empty chat in a single transaction. The session is created in the `provisioning` lifecycle state — a separate orchestration step claims it and starts the sandbox.", + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSessionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Session and initial chat created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSessionResponse" + } + } + } + }, + "400": { + "description": "Invalid request body — either malformed JSON or a field failed validation.", + "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" + } + } + } + }, + "500": { + "description": "Server error — the session could not be persisted.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, "/api/sessions/{sessionId}": { "get": { "summary": "Get session by id", @@ -106,6 +164,114 @@ } } }, + "CreateSessionRequest": { + "type": "object", + "description": "All fields are optional. An empty body is valid and creates a session with default settings.", + "properties": { + "title": { + "type": "string", + "description": "Display title for the session. When omitted, the server generates one." + }, + "repoOwner": { + "type": "string", + "description": "GitHub repository owner (user or org). Validated against GitHub's owner-name rules." + }, + "repoName": { + "type": "string", + "description": "GitHub repository name. Validated against GitHub's repo-name rules." + }, + "branch": { + "type": "string", + "description": "Branch the session should check out. Ignored when `isNewBranch` is true — the server generates a new branch name in that case." + }, + "cloneUrl": { + "type": "string", + "description": "Clone URL the sandbox should fetch from." + }, + "isNewBranch": { + "type": "boolean", + "description": "When true, the server generates a fresh branch name (e.g. `xx/abcdef12`) instead of using `branch`." + }, + "sandboxType": { + "type": "string", + "enum": [ + "vercel" + ], + "description": "Which sandbox provider to use. Currently only `vercel` is accepted." + }, + "autoCommitPush": { + "type": "boolean", + "description": "Per-session override for automatic commit + push. When omitted, the account's default preference applies." + }, + "autoCreatePr": { + "type": "boolean", + "description": "Per-session override for opening a PR after auto-commit. Only meaningful when `autoCommitPush` is true. When omitted, the account's default preference applies." + } + } + }, + "CreateSessionResponse": { + "type": "object", + "required": [ + "session", + "chat" + ], + "properties": { + "session": { + "$ref": "#/components/schemas/Session" + }, + "chat": { + "$ref": "#/components/schemas/Chat" + } + } + }, + "Chat": { + "type": "object", + "required": [ + "id", + "sessionId", + "title", + "modelId", + "createdAt", + "updatedAt" + ], + "properties": { + "id": { + "type": "string", + "description": "Chat id (nanoid)." + }, + "sessionId": { + "type": "string", + "description": "Owning session id." + }, + "title": { + "type": "string", + "description": "Display title for the chat. The initial chat created with a session is titled `New chat`." + }, + "modelId": { + "type": "string", + "description": "AI Gateway model identifier the chat is configured to use (e.g. `openai/gpt-5.4`)." + }, + "activeStreamId": { + "type": "string", + "nullable": true, + "description": "Id of an in-flight assistant stream, if one is active." + }, + "lastAssistantMessageAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp of the most recent assistant message in this chat." + }, + "createdAt": { + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "type": "string", + "format": "date-time" + } + } + }, "Session": { "type": "object", "required": [ @@ -163,6 +329,16 @@ "type": "boolean", "description": "True when this session created and pushed a new branch (not committing back to the original)." }, + "autoCommitPushOverride": { + "type": "boolean", + "nullable": true, + "description": "Per-session override for auto commit + push behavior. `null` means use the account's default preference." + }, + "autoCreatePrOverride": { + "type": "boolean", + "nullable": true, + "description": "Per-session override for creating a PR after auto-commit. `null` means use the account's default preference." + }, "globalSkillRefs": { "type": "array", "description": "Skills attached to the agent at provision time.", @@ -220,11 +396,28 @@ }, "linesAdded": { "type": "integer", - "nullable": true + "nullable": true, + "description": "Lines added across the session's diff. Defaults to 0; null when stats have not been computed." }, "linesRemoved": { "type": "integer", - "nullable": true + "nullable": true, + "description": "Lines removed across the session's diff. Defaults to 0; null when stats have not been computed." + }, + "prNumber": { + "type": "integer", + "nullable": true, + "description": "GitHub pull request number, set after the session has opened a PR." + }, + "prStatus": { + "type": "string", + "nullable": true, + "enum": [ + "open", + "merged", + "closed" + ], + "description": "Lifecycle of the linked pull request." }, "snapshotUrl": { "type": "string", diff --git a/api-reference/sessions/create.mdx b/api-reference/sessions/create.mdx new file mode 100644 index 0000000..f73e290 --- /dev/null +++ b/api-reference/sessions/create.mdx @@ -0,0 +1,4 @@ +--- +title: "Create Session" +openapi: "/api-reference/openapi/sessions.json POST /api/sessions" +--- diff --git a/docs.json b/docs.json index 9b01739..147ee00 100644 --- a/docs.json +++ b/docs.json @@ -268,6 +268,7 @@ { "group": "Sessions", "pages": [ + "api-reference/sessions/create", "api-reference/sessions/get" ] } From bdf89d9c6887eeb578e911cf032029d3bcc1781d Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Mon, 4 May 2026 16:50:10 -0500 Subject: [PATCH 8/8] 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) --- api-reference/openapi/sessions.json | 70 ----------------------------- api-reference/sessions/get.mdx | 4 -- docs.json | 3 +- 3 files changed, 1 insertion(+), 76 deletions(-) delete mode 100644 api-reference/sessions/get.mdx diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 9163890..3f5689f 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -79,65 +79,6 @@ } } } - }, - "/api/sessions/{sessionId}": { - "get": { - "summary": "Get session by id", - "description": "Returns a single agent session by its id.", - "parameters": [ - { - "name": "sessionId", - "in": "path", - "required": true, - "description": "The id of the session to fetch.", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Session retrieved successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GetSessionResponse" - } - } - } - }, - "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" - } - } - } - } - } - } } }, "components": { @@ -153,17 +94,6 @@ } }, "schemas": { - "GetSessionResponse": { - "type": "object", - "required": [ - "session" - ], - "properties": { - "session": { - "$ref": "#/components/schemas/Session" - } - } - }, "CreateSessionRequest": { "type": "object", "description": "All fields are optional. An empty body is valid and creates a session with default settings.", diff --git a/api-reference/sessions/get.mdx b/api-reference/sessions/get.mdx deleted file mode 100644 index 483ac1b..0000000 --- a/api-reference/sessions/get.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Get Session" -openapi: "/api-reference/openapi/sessions.json GET /api/sessions/{sessionId}" ---- diff --git a/docs.json b/docs.json index 147ee00..57c9737 100644 --- a/docs.json +++ b/docs.json @@ -268,8 +268,7 @@ { "group": "Sessions", "pages": [ - "api-reference/sessions/create", - "api-reference/sessions/get" + "api-reference/sessions/create" ] } ]