From 812a281cd65d27794b7e473b5256c7914ae2efff Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 09:43:41 -0500 Subject: [PATCH 01/10] =?UTF-8?q?docs:=20POST=20/api/chat/generate=20?= =?UTF-8?q?=E2=86=92=20202=20{=20runId=20}=20(async=20workflow=20run)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The scheduled chat-generation path is moving onto the durable runAgentWorkflow (recoupable/chat#1813). POST /api/chat/generate now starts a workflow run and returns { runId } with 202 instead of the synchronous completion body — message persistence + side effects (email) happen server-side after the response. - Replace the 200 ChatGenerateResponse with 202 ChatGenerateAcceptedResponse { runId }. - Drop the now-unused ChatGenerateResponse / ChatGenerateResponseMeta / ChatGenerateUsage / ContentPart schemas (each referenced only by the old 200). - Contract-first: this docs change leads the api re-point PR (docs → api). Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 126 ++++------------------------ 1 file changed, 18 insertions(+), 108 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index f149a2d..286bb0f 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -648,7 +648,7 @@ }, "/api/chat/generate": { "post": { - "description": "Generate AI-powered text responses using the Recoup chat system. This endpoint processes chat requests and returns generated text along with metadata about the generation process.", + "description": "Start an asynchronous chat-generation run on the durable agent workflow (the same `runAgentWorkflow` that powers interactive `/api/chat`). The request provisions a session + sandbox and starts the run, then returns immediately with a `runId` (HTTP 202) — generation, message persistence, and any side effects (e.g. email) happen server-side after the response.", "security": [ { "apiKeyAuth": [] @@ -666,12 +666,12 @@ } }, "responses": { - "200": { - "description": "Chat generated successfully", + "202": { + "description": "Run accepted. A durable workflow run was started; `runId` identifies it. Assistant messages are persisted server-side as the run streams.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatGenerateResponse" + "$ref": "#/components/schemas/ChatGenerateAcceptedResponse" } } } @@ -3090,91 +3090,6 @@ } } }, - "ChatGenerateResponse": { - "type": "object", - "description": "Response from the chat generation endpoint", - "properties": { - "text": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentPart" - }, - "description": "Array of content parts from the AI model response" - }, - "reasoningText": { - "type": "string", - "nullable": true, - "description": "Optional reasoning or explanation for the response" - }, - "sources": { - "type": "array", - "items": { - "type": "object" - }, - "description": "Optional array of sources used for the response" - }, - "finishReason": { - "type": "string", - "description": "The reason why the generation finished", - "example": "stop" - }, - "usage": { - "$ref": "#/components/schemas/ChatGenerateUsage", - "description": "Token usage information" - }, - "response": { - "$ref": "#/components/schemas/ChatGenerateResponseMeta", - "description": "Additional response metadata" - } - } - }, - "ChatGenerateResponseMeta": { - "type": "object", - "description": "Additional response metadata", - "properties": { - "messages": { - "type": "array", - "items": { - "type": "object" - }, - "description": "Response messages" - }, - "headers": { - "type": "object", - "description": "Response headers" - }, - "body": { - "type": "object", - "description": "Response body" - } - } - }, - "ChatGenerateUsage": { - "type": "object", - "description": "Token usage information with detailed breakdown", - "properties": { - "inputTokens": { - "type": "integer", - "description": "Number of input tokens processed" - }, - "outputTokens": { - "type": "integer", - "description": "Number of output tokens generated" - }, - "totalTokens": { - "type": "integer", - "description": "Total tokens used (input + output)" - }, - "reasoningTokens": { - "type": "integer", - "description": "Number of reasoning tokens used" - }, - "cachedInputTokens": { - "type": "integer", - "description": "Number of cached input tokens" - } - } - }, "ChatMessage": { "type": "object", "required": [ @@ -3359,25 +3274,6 @@ } } }, - "ContentPart": { - "type": "object", - "description": "A part of the response content. See https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#content for details.", - "properties": { - "type": { - "type": "string", - "enum": [ - "text", - "tool-call", - "tool-result" - ], - "description": "The type of content part" - }, - "text": { - "type": "string", - "description": "The text content (present when type is 'text')" - } - } - }, "CopyChatMessagesErrorResponse": { "type": "object", "required": [ @@ -5291,6 +5187,20 @@ "description": "`current`: scraper cost estimate before spend." } } + }, + "ChatGenerateAcceptedResponse": { + "type": "object", + "required": [ + "runId" + ], + "description": "Confirmation that an asynchronous chat-generation run has been started on the durable agent workflow.", + "properties": { + "runId": { + "type": "string", + "description": "Durable workflow run id for the started generation. Same identifier surfaced as the `x-workflow-run-id` header on interactive `/api/chat`.", + "example": "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ" + } + } } }, "responses": { From 43c3dbc0a1e3fd6b2c2f627c101dc445d5694aa2 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 12:03:47 -0500 Subject: [PATCH 02/10] docs: /api/chat/generate 202 returns { runId, chatId, sessionId } MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add chatId + sessionId to ChatGenerateAcceptedResponse and document reading the result via GET /api/chat/{chatId}/stream (or the chat's persisted messages) — the workflow runId alone can't be resolved back to the output. Matches the api#704 contract update. (chat#1813, review follow-up.) Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 286bb0f..ce5aabd 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -667,7 +667,7 @@ }, "responses": { "202": { - "description": "Run accepted. A durable workflow run was started; `runId` identifies it. Assistant messages are persisted server-side as the run streams.", + "description": "Run accepted. A durable workflow run was started; `runId` identifies it. `chatId` / `sessionId` identify the persisted output — read the result via `GET /api/chat/{chatId}/stream` (resume the stream) or the chat's persisted messages. Assistant messages are persisted server-side as the run streams.", "content": { "application/json": { "schema": { @@ -5191,7 +5191,9 @@ "ChatGenerateAcceptedResponse": { "type": "object", "required": [ - "runId" + "runId", + "chatId", + "sessionId" ], "description": "Confirmation that an asynchronous chat-generation run has been started on the durable agent workflow.", "properties": { @@ -5199,6 +5201,18 @@ "type": "string", "description": "Durable workflow run id for the started generation. Same identifier surfaced as the `x-workflow-run-id` header on interactive `/api/chat`.", "example": "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ" + }, + "chatId": { + "type": "string", + "format": "uuid", + "description": "Chat the run writes its assistant messages to. Use with `GET /api/chat/{chatId}/stream` to resume the stream, or to fetch the persisted messages.", + "example": "24830c6c-76d8-43be-ae22-1dfd545421ab" + }, + "sessionId": { + "type": "string", + "format": "uuid", + "description": "Session (workspace + sandbox) provisioned for the run.", + "example": "fa9c1516-35f0-4efd-a62c-01af26324e72" } } } From c17c08adcb67de2677568f25d0d0f8dee15ffd8f Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 12:50:22 -0500 Subject: [PATCH 03/10] =?UTF-8?q?docs:=20rename=20/api/chat/generate=20?= =?UTF-8?q?=E2=86=92=20/api/chat/runs;=20add=20GET=20/api/chat/runs/{runId?= =?UTF-8?q?}?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit REST cleanup (chat#1813): the headless async endpoint creates a *run*, so it's modeled as a run resource rather than a `generate` verb. - Rename POST /api/chat/generate → POST /api/chat/runs (202 { runId, chatId, sessionId } + Location header pointing at the run-status resource). - Add GET /api/chat/runs/{runId} — point-in-time run status (ChatRunStatusResponse: status/chatId/sessionId/timestamps/error). Documentation-driven: the api for the status endpoint lands in a follow-up after this contract merges. - Rename the reference page (generate.mdx → runs.mdx), add runs-status.mdx, update docs.json nav + index.mdx. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/chat/generate.mdx | 4 - api-reference/chat/runs-status.mdx | 4 + api-reference/chat/runs.mdx | 4 + api-reference/openapi/research.json | 124 +++++++++++++++++++++++++++- docs.json | 3 +- index.mdx | 2 +- 6 files changed, 133 insertions(+), 8 deletions(-) delete mode 100644 api-reference/chat/generate.mdx create mode 100644 api-reference/chat/runs-status.mdx create mode 100644 api-reference/chat/runs.mdx diff --git a/api-reference/chat/generate.mdx b/api-reference/chat/generate.mdx deleted file mode 100644 index c84a9df..0000000 --- a/api-reference/chat/generate.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Generate Chat -openapi: post /api/chat/generate ---- diff --git a/api-reference/chat/runs-status.mdx b/api-reference/chat/runs-status.mdx new file mode 100644 index 0000000..fe3cca7 --- /dev/null +++ b/api-reference/chat/runs-status.mdx @@ -0,0 +1,4 @@ +--- +title: Get Chat Run Status +openapi: get /api/chat/runs/{runId} +--- diff --git a/api-reference/chat/runs.mdx b/api-reference/chat/runs.mdx new file mode 100644 index 0000000..56cd7d5 --- /dev/null +++ b/api-reference/chat/runs.mdx @@ -0,0 +1,4 @@ +--- +title: Start Chat Run +openapi: post /api/chat/runs +--- diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index ce5aabd..6f3e577 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -646,9 +646,9 @@ } } }, - "/api/chat/generate": { + "/api/chat/runs": { "post": { - "description": "Start an asynchronous chat-generation run on the durable agent workflow (the same `runAgentWorkflow` that powers interactive `/api/chat`). The request provisions a session + sandbox and starts the run, then returns immediately with a `runId` (HTTP 202) — generation, message persistence, and any side effects (e.g. email) happen server-side after the response.", + "description": "Start an asynchronous chat-generation run on the durable agent workflow (the same `runAgentWorkflow` that powers interactive `/api/chat`). The request provisions a session + sandbox and starts the run, then returns immediately with `runId` / `chatId` / `sessionId` (HTTP 202). Generation, message persistence, and side effects (e.g. email) happen server-side after the response. Read the result via `GET /api/chat/{chatId}/stream` (watch it stream) or poll `GET /api/chat/runs/{runId}` for status.", "security": [ { "apiKeyAuth": [] @@ -674,6 +674,16 @@ "$ref": "#/components/schemas/ChatGenerateAcceptedResponse" } } + }, + "headers": { + "Location": { + "description": "Relative URL of the run-status resource for the started run.", + "schema": { + "type": "string", + "format": "uri-reference" + }, + "example": "/api/chat/runs/wrun_01KVWZNM82NA7XKNEWWHG8VPHJ" + } } }, "400": { @@ -2969,6 +2979,50 @@ } } } + }, + "/api/chat/runs/{runId}": { + "get": { + "description": "Get the status of an asynchronous chat-generation run started via `POST /api/chat/runs`. Returns a point-in-time snapshot — not the generated content. Fetch the produced messages via `chatId` (`GET /api/chat/{chatId}/stream`, or the chat's persisted messages).", + "security": [ + { + "apiKeyAuth": [] + } + ], + "parameters": [ + { + "name": "runId", + "in": "path", + "required": true, + "description": "The durable workflow run id returned by `POST /api/chat/runs`.", + "schema": { + "type": "string" + }, + "example": "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ" + } + ], + "responses": { + "200": { + "description": "Run status snapshot", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatRunStatusResponse" + } + } + } + }, + "404": { + "description": "No run found for the given runId", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatGenerateErrorResponse" + } + } + } + } + } + } } }, "components": { @@ -5215,6 +5269,72 @@ "example": "fa9c1516-35f0-4efd-a62c-01af26324e72" } } + }, + "ChatRunStatusResponse": { + "type": "object", + "required": [ + "runId", + "status", + "chatId", + "sessionId" + ], + "description": "Point-in-time status of an asynchronous chat-generation run.", + "properties": { + "runId": { + "type": "string", + "description": "The durable workflow run id.", + "example": "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ" + }, + "status": { + "type": "string", + "enum": [ + "queued", + "running", + "completed", + "failed", + "cancelled" + ], + "description": "Lifecycle state of the run." + }, + "chatId": { + "type": "string", + "format": "uuid", + "description": "Chat the run writes its assistant messages to.", + "example": "24830c6c-76d8-43be-ae22-1dfd545421ab" + }, + "sessionId": { + "type": "string", + "format": "uuid", + "description": "Session (workspace + sandbox) provisioned for the run.", + "example": "fa9c1516-35f0-4efd-a62c-01af26324e72" + }, + "startedAt": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "When the run started.", + "example": "2026-06-24T15:07:40Z" + }, + "completedAt": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "When the run reached a terminal state; null while in-flight.", + "example": null + }, + "error": { + "type": [ + "string", + "null" + ], + "description": "Failure reason when status is `failed`; otherwise null.", + "example": null + } + } } }, "responses": { diff --git a/docs.json b/docs.json index 719ac1e..ab8874f 100644 --- a/docs.json +++ b/docs.json @@ -64,7 +64,8 @@ "group": "Streaming", "pages": [ "api-reference/chat/stop", - "api-reference/chat/generate", + "api-reference/chat/runs", + "api-reference/chat/runs-status", "api-reference/chat/workflow", "api-reference/chat/workflow-stream" ] diff --git a/index.mdx b/index.mdx index c100000..ed3c621 100644 --- a/index.mdx +++ b/index.mdx @@ -173,7 +173,7 @@ If you are an LLM navigating these docs, here is a summary of the endpoint struc - **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile) - **`/api/research/*`** — Artist research (search, lookup, profile, metrics, audience, cities, similar, urls, instagram-posts, playlists, albums, track, tracks, career, insights, genres, festivals, web, deep, people, extract, enrich, milestones, venues, rank, charts, radio, discover, curator, playlist) - **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate) -- **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, generate, stream, compact) +- **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, runs, runs-status, stream, compact) - **`/api/songs/*`** — Songs and catalogs (songs, create, analyze, analyze-presets, catalogs, catalogs-create, catalogs-delete, catalog-songs, catalog-songs-add, catalog-songs-delete) - **`/api/tasks/*`** — Task automation (get, create, update, delete, runs) - **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album) From d94a7d3d3583eed66b6eb02011bbb34d20d002b1 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 13:03:27 -0500 Subject: [PATCH 04/10] docs: bidirectional cross-links between the chat endpoints; KISS run descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review on #249: each related chat endpoint now links to its siblings with a note on when to use which — - POST /api/chat ↔ POST /api/chat/runs (interactive-stream vs headless-job) - POST /api/chat/runs ↔ GET /api/chat/runs/{runId} (start vs status) - POST /api/chat/runs ↔ GET /api/chat/{chatId}/stream (start vs watch-live) - GET /api/chat/runs/{runId} ↔ GET /api/chat/{chatId}/stream (is-it-done vs watch-content) Descriptions trimmed to the essentials (request/response fields auto-render from the schema). Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 6f3e577..e1aef1d 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -648,7 +648,7 @@ }, "/api/chat/runs": { "post": { - "description": "Start an asynchronous chat-generation run on the durable agent workflow (the same `runAgentWorkflow` that powers interactive `/api/chat`). The request provisions a session + sandbox and starts the run, then returns immediately with `runId` / `chatId` / `sessionId` (HTTP 202). Generation, message persistence, and side effects (e.g. email) happen server-side after the response. Read the result via `GET /api/chat/{chatId}/stream` (watch it stream) or poll `GET /api/chat/runs/{runId}` for status.", + "description": "Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [POST /api/chat](/api-reference/chat/workflow). Provisions a session + sandbox and returns immediately (**202**) with `runId`, `chatId`, and `sessionId`; generation and side effects (e.g. email) finish server-side.\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — use that for **interactive, streaming** turns on an existing chat; use this for **headless/programmatic** runs (no browser or pre-provisioned session needed).\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.", "security": [ { "apiKeyAuth": [] @@ -766,7 +766,7 @@ "/api/chat/{chatId}/stream": { "get": { "summary": "Resume a chat response stream", - "description": "Reconnects to an in-progress chat response — the resume counterpart to [POST /api/chat](/api-reference/chat/workflow), which never resumes. Returns the live Server-Sent Events stream when a response is still being generated, or `204 No Content` when there is nothing to resume. The chat must belong to the authenticated account.", + "description": "Reconnects to an in-progress chat response — the resume counterpart to [POST /api/chat](/api-reference/chat/workflow), which never resumes. Returns the live Server-Sent Events stream when a response is still being generated, or `204 No Content` when there is nothing to resume. The chat must belong to the authenticated account.\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — start a **headless** run, then pass the returned `chatId` here to **watch its output live**.\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — check **whether** that run finished (status, not content).", "security": [ { "apiKeyAuth": [] @@ -846,7 +846,7 @@ "/api/chat": { "post": { "summary": "Stream sandbox-driven chat (Vercel Workflow)", - "description": "Streams an agent loop running as a durable [Vercel Workflow](https://vercel.com/docs/workflow) against the session's sandbox. The agent uses sandbox-only tools (`bash`, `read`, `write`, `grep`, `glob`, `todo`, `task`, `ask_user_question`, `skill`, `fetch`) — no MCP or Composio. Requires a sandbox provisioned via [POST /api/sandbox](/api-reference/sandbox/create).", + "description": "Streams an agent loop running as a durable [Vercel Workflow](https://vercel.com/docs/workflow) against the session's sandbox. The agent uses sandbox-only tools (`bash`, `read`, `write`, `grep`, `glob`, `todo`, `task`, `ask_user_question`, `skill`, `fetch`) — no MCP or Composio. Requires a sandbox provisioned via [POST /api/sandbox](/api-reference/sandbox/create).\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — the **headless** counterpart: it provisions its own session + sandbox and runs without a streaming client. Use that for tasks/cron/programmatic runs; use this for **interactive, streaming** turns on an existing chat.\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — reconnect to an in-progress response.", "security": [ { "apiKeyAuth": [] @@ -2982,7 +2982,7 @@ }, "/api/chat/runs/{runId}": { "get": { - "description": "Get the status of an asynchronous chat-generation run started via `POST /api/chat/runs`. Returns a point-in-time snapshot — not the generated content. Fetch the produced messages via `chatId` (`GET /api/chat/{chatId}/stream`, or the chat's persisted messages).", + "description": "Status of an asynchronous run started via [POST /api/chat/runs](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — starts the run this reports on.\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — to read the **content**: poll *this* to know **whether** a run finished; use the stream to **watch the output** as it's produced.", "security": [ { "apiKeyAuth": [] From ca85223113aba7b72450025ce4cf7b8c28a30221 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 13:11:16 -0500 Subject: [PATCH 05/10] docs: hyperlink endpoint refs in run response, param, and schema descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert the remaining bare-`code` endpoint references into reference-page hyperlinks (review #249) so every cross-reference is clickable + bidirectional: - 202 response description → GET /api/chat/{chatId}/stream, GET /api/chat/runs/{runId} - runId path-parameter → POST /api/chat/runs - ChatGenerateAcceptedResponse.runId → POST /api/chat - ChatGenerateAcceptedResponse.chatId → GET /api/chat/{chatId}/stream Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index e1aef1d..5208ee4 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -667,7 +667,7 @@ }, "responses": { "202": { - "description": "Run accepted. A durable workflow run was started; `runId` identifies it. `chatId` / `sessionId` identify the persisted output — read the result via `GET /api/chat/{chatId}/stream` (resume the stream) or the chat's persisted messages. Assistant messages are persisted server-side as the run streams.", + "description": "Run accepted. A durable workflow run was started; `runId` identifies it. `chatId` / `sessionId` identify the persisted output — read the result via [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) (resume the stream) or the chat's persisted messages. Poll [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) for status.", "content": { "application/json": { "schema": { @@ -2993,7 +2993,7 @@ "name": "runId", "in": "path", "required": true, - "description": "The durable workflow run id returned by `POST /api/chat/runs`.", + "description": "The durable workflow run id returned by [POST /api/chat/runs](/api-reference/chat/runs).", "schema": { "type": "string" }, @@ -5253,13 +5253,13 @@ "properties": { "runId": { "type": "string", - "description": "Durable workflow run id for the started generation. Same identifier surfaced as the `x-workflow-run-id` header on interactive `/api/chat`.", + "description": "Durable workflow run id for the started generation. Same identifier surfaced as the `x-workflow-run-id` header on interactive [POST /api/chat](/api-reference/chat/workflow).", "example": "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ" }, "chatId": { "type": "string", "format": "uuid", - "description": "Chat the run writes its assistant messages to. Use with `GET /api/chat/{chatId}/stream` to resume the stream, or to fetch the persisted messages.", + "description": "Chat the run writes its assistant messages to. Use with [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) to resume the stream, or to fetch the persisted messages.", "example": "24830c6c-76d8-43be-ae22-1dfd545421ab" }, "sessionId": { From 651ec32ada88a817ba371390847149619f7b66bf Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 13:14:37 -0500 Subject: [PATCH 06/10] docs: complete bidirectional chat-endpoint cross-links + KISS run description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review #249: - Every chat endpoint's "Related endpoints" list now links the other three siblings (POST /api/chat ↔ POST /api/chat/runs ↔ GET /api/chat/runs/{runId} ↔ GET /api/chat/{chatId}/stream) — full symmetry. - Applied the KISS suggestion: trimmed the POST /api/chat/runs description to the essential sentence + the Related list (provision/202/field details auto-render from the schema). Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 5208ee4..d31198e 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -648,7 +648,7 @@ }, "/api/chat/runs": { "post": { - "description": "Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [POST /api/chat](/api-reference/chat/workflow). Provisions a session + sandbox and returns immediately (**202**) with `runId`, `chatId`, and `sessionId`; generation and side effects (e.g. email) finish server-side.\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — use that for **interactive, streaming** turns on an existing chat; use this for **headless/programmatic** runs (no browser or pre-provisioned session needed).\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.", + "description": "Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [POST /api/chat](/api-reference/chat/workflow).\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — use that for **interactive, streaming** turns on an existing chat; use this for **headless/programmatic** runs (no browser or pre-provisioned session needed).\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.", "security": [ { "apiKeyAuth": [] @@ -766,7 +766,7 @@ "/api/chat/{chatId}/stream": { "get": { "summary": "Resume a chat response stream", - "description": "Reconnects to an in-progress chat response — the resume counterpart to [POST /api/chat](/api-reference/chat/workflow), which never resumes. Returns the live Server-Sent Events stream when a response is still being generated, or `204 No Content` when there is nothing to resume. The chat must belong to the authenticated account.\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — start a **headless** run, then pass the returned `chatId` here to **watch its output live**.\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — check **whether** that run finished (status, not content).", + "description": "Reconnects to an in-progress chat response — the resume counterpart to [POST /api/chat](/api-reference/chat/workflow), which never resumes. Returns the live Server-Sent Events stream when a response is still being generated, or `204 No Content` when there is nothing to resume. The chat must belong to the authenticated account.\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — the interactive turn whose stream this resumes.\n- [POST /api/chat/runs](/api-reference/chat/runs) — start a **headless** run, then pass the returned `chatId` here to **watch its output live**.\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — check **whether** that run finished (status, not content).", "security": [ { "apiKeyAuth": [] @@ -846,7 +846,7 @@ "/api/chat": { "post": { "summary": "Stream sandbox-driven chat (Vercel Workflow)", - "description": "Streams an agent loop running as a durable [Vercel Workflow](https://vercel.com/docs/workflow) against the session's sandbox. The agent uses sandbox-only tools (`bash`, `read`, `write`, `grep`, `glob`, `todo`, `task`, `ask_user_question`, `skill`, `fetch`) — no MCP or Composio. Requires a sandbox provisioned via [POST /api/sandbox](/api-reference/sandbox/create).\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — the **headless** counterpart: it provisions its own session + sandbox and runs without a streaming client. Use that for tasks/cron/programmatic runs; use this for **interactive, streaming** turns on an existing chat.\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — reconnect to an in-progress response.", + "description": "Streams an agent loop running as a durable [Vercel Workflow](https://vercel.com/docs/workflow) against the session's sandbox. The agent uses sandbox-only tools (`bash`, `read`, `write`, `grep`, `glob`, `todo`, `task`, `ask_user_question`, `skill`, `fetch`) — no MCP or Composio. Requires a sandbox provisioned via [POST /api/sandbox](/api-reference/sandbox/create).\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — the **headless** counterpart: it provisions its own session + sandbox and runs without a streaming client. Use that for tasks/cron/programmatic runs; use this for **interactive, streaming** turns on an existing chat.\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — reconnect to an in-progress response.\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — check **whether** a headless run finished (status, not content).", "security": [ { "apiKeyAuth": [] @@ -2982,7 +2982,7 @@ }, "/api/chat/runs/{runId}": { "get": { - "description": "Status of an asynchronous run started via [POST /api/chat/runs](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — starts the run this reports on.\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — to read the **content**: poll *this* to know **whether** a run finished; use the stream to **watch the output** as it's produced.", + "description": "Status of an asynchronous run started via [POST /api/chat/runs](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — starts the run this reports on.\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — read the **content**: poll *this* to know **whether** a run finished; use the stream to **watch the output** as it's produced.\n- [POST /api/chat](/api-reference/chat/workflow) — the interactive, streaming counterpart to a headless run.", "security": [ { "apiKeyAuth": [] From c19609d81eb954ac9e3a77b0229f581a3257a901 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 13:47:52 -0500 Subject: [PATCH 07/10] docs: drop stale excludeTools/roomId from the chat-runs request; fix topic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reconcile the request schema with the re-pointed endpoint (review #249): - Remove excludeTools — legacy ToolLoopAgent tool-filtering; the workflow agent uses native sandbox tools, no exclusion mechanism (the API never accepted it). - Remove roomId — legacy room model; the endpoint mints its own session+chat and returns chatId/sessionId. It was accepted-but-ignored, now dropped api-side too. - topic: corrected the description to "session title for the run" (it no longer creates a chat room). Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index d31198e..82a3ea8 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -3123,24 +3123,9 @@ "description": "The AI model to use for text generation (optional)", "example": "openai/gpt-5-mini" }, - "excludeTools": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Array of tool names to exclude from execution", - "example": [ - "create_scheduled_actions" - ] - }, - "roomId": { - "type": "string", - "format": "uuid", - "description": "UUID of the chat room. If not provided, one will be generated automatically." - }, "topic": { "type": "string", - "description": "Topic name for the new chat room (e.g., 'Pulse Feb 2'). Only applies when creating a new room - ignored if room already exists. To edit the topic of an existing room, use [PATCH /api/chats](/api-reference/chat/update)." + "description": "Optional session title for the run." } } }, From 1af2922586535b03b28e6532142a942b7d22d17f Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 13:56:41 -0500 Subject: [PATCH 08/10] docs: remove topic from chat-runs request to match /api/chat /api/chat has no title param; /api/chat/runs provisions its own session with a default title. Request schema is now prompt | messages, artistId, model. (#1813) Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 82a3ea8..ee56130 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -3122,10 +3122,6 @@ "type": "string", "description": "The AI model to use for text generation (optional)", "example": "openai/gpt-5-mini" - }, - "topic": { - "type": "string", - "description": "Optional session title for the run." } } }, From 4e045dcb888c5c33996b6bef1f3307500fe07245 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 14:04:43 -0500 Subject: [PATCH 09/10] docs: fix MDX double-slash in path links; reorder Streaming nav - Wrap endpoint-path link labels that contain `{param}` in backticks so MDX renders the braces literally instead of evaluating `{chatId}`/`{runId}`/ `{sessionId}` to empty (which showed as e.g. `GET /api/chat//stream`). Fixed 9 labels in research.json + 2 in sessions.json; links stay clickable. - Streaming nav: lead with POST /api/chat (workflow) + its stream, then the runs job pair, then stop. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 12 ++++++------ api-reference/openapi/sessions.json | 7 +++++-- docs.json | 6 +++--- 3 files changed, 14 insertions(+), 11 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index ee56130..d0c2d80 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -648,7 +648,7 @@ }, "/api/chat/runs": { "post": { - "description": "Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [POST /api/chat](/api-reference/chat/workflow).\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — use that for **interactive, streaming** turns on an existing chat; use this for **headless/programmatic** runs (no browser or pre-provisioned session needed).\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.", + "description": "Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [POST /api/chat](/api-reference/chat/workflow).\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — use that for **interactive, streaming** turns on an existing chat; use this for **headless/programmatic** runs (no browser or pre-provisioned session needed).\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.", "security": [ { "apiKeyAuth": [] @@ -667,7 +667,7 @@ }, "responses": { "202": { - "description": "Run accepted. A durable workflow run was started; `runId` identifies it. `chatId` / `sessionId` identify the persisted output — read the result via [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) (resume the stream) or the chat's persisted messages. Poll [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) for status.", + "description": "Run accepted. A durable workflow run was started; `runId` identifies it. `chatId` / `sessionId` identify the persisted output — read the result via [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) (resume the stream) or the chat's persisted messages. Poll [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) for status.", "content": { "application/json": { "schema": { @@ -766,7 +766,7 @@ "/api/chat/{chatId}/stream": { "get": { "summary": "Resume a chat response stream", - "description": "Reconnects to an in-progress chat response — the resume counterpart to [POST /api/chat](/api-reference/chat/workflow), which never resumes. Returns the live Server-Sent Events stream when a response is still being generated, or `204 No Content` when there is nothing to resume. The chat must belong to the authenticated account.\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — the interactive turn whose stream this resumes.\n- [POST /api/chat/runs](/api-reference/chat/runs) — start a **headless** run, then pass the returned `chatId` here to **watch its output live**.\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — check **whether** that run finished (status, not content).", + "description": "Reconnects to an in-progress chat response — the resume counterpart to [POST /api/chat](/api-reference/chat/workflow), which never resumes. Returns the live Server-Sent Events stream when a response is still being generated, or `204 No Content` when there is nothing to resume. The chat must belong to the authenticated account.\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — the interactive turn whose stream this resumes.\n- [POST /api/chat/runs](/api-reference/chat/runs) — start a **headless** run, then pass the returned `chatId` here to **watch its output live**.\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — check **whether** that run finished (status, not content).", "security": [ { "apiKeyAuth": [] @@ -846,7 +846,7 @@ "/api/chat": { "post": { "summary": "Stream sandbox-driven chat (Vercel Workflow)", - "description": "Streams an agent loop running as a durable [Vercel Workflow](https://vercel.com/docs/workflow) against the session's sandbox. The agent uses sandbox-only tools (`bash`, `read`, `write`, `grep`, `glob`, `todo`, `task`, `ask_user_question`, `skill`, `fetch`) — no MCP or Composio. Requires a sandbox provisioned via [POST /api/sandbox](/api-reference/sandbox/create).\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — the **headless** counterpart: it provisions its own session + sandbox and runs without a streaming client. Use that for tasks/cron/programmatic runs; use this for **interactive, streaming** turns on an existing chat.\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — reconnect to an in-progress response.\n- [GET /api/chat/runs/{runId}](/api-reference/chat/runs-status) — check **whether** a headless run finished (status, not content).", + "description": "Streams an agent loop running as a durable [Vercel Workflow](https://vercel.com/docs/workflow) against the session's sandbox. The agent uses sandbox-only tools (`bash`, `read`, `write`, `grep`, `glob`, `todo`, `task`, `ask_user_question`, `skill`, `fetch`) — no MCP or Composio. Requires a sandbox provisioned via [POST /api/sandbox](/api-reference/sandbox/create).\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — the **headless** counterpart: it provisions its own session + sandbox and runs without a streaming client. Use that for tasks/cron/programmatic runs; use this for **interactive, streaming** turns on an existing chat.\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — reconnect to an in-progress response.\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — check **whether** a headless run finished (status, not content).", "security": [ { "apiKeyAuth": [] @@ -2982,7 +2982,7 @@ }, "/api/chat/runs/{runId}": { "get": { - "description": "Status of an asynchronous run started via [POST /api/chat/runs](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — starts the run this reports on.\n- [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) — read the **content**: poll *this* to know **whether** a run finished; use the stream to **watch the output** as it's produced.\n- [POST /api/chat](/api-reference/chat/workflow) — the interactive, streaming counterpart to a headless run.", + "description": "Status of an asynchronous run started via [POST /api/chat/runs](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — starts the run this reports on.\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — read the **content**: poll *this* to know **whether** a run finished; use the stream to **watch the output** as it's produced.\n- [POST /api/chat](/api-reference/chat/workflow) — the interactive, streaming counterpart to a headless run.", "security": [ { "apiKeyAuth": [] @@ -5240,7 +5240,7 @@ "chatId": { "type": "string", "format": "uuid", - "description": "Chat the run writes its assistant messages to. Use with [GET /api/chat/{chatId}/stream](/api-reference/chat/workflow-stream) to resume the stream, or to fetch the persisted messages.", + "description": "Chat the run writes its assistant messages to. Use with [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) to resume the stream, or to fetch the persisted messages.", "example": "24830c6c-76d8-43be-ae22-1dfd545421ab" }, "sessionId": { diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index 9f2bdf3..fa00621 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -1084,7 +1084,7 @@ }, "Session": { "type": "object", - "description": "Agent session returned by [POST /api/sessions](/api-reference/sessions/create), [GET /api/sessions/{sessionId}](/api-reference/sessions/get), and [PATCH /api/sessions/{sessionId}](/api-reference/sessions/patch). The api serializes every field listed in `required` on each response, including `isNewBranch` (boolean, from the non-null `sessions.is_new_branch` column) and `artistId` (UUID or null).", + "description": "Agent session returned by [POST /api/sessions](/api-reference/sessions/create), [`GET /api/sessions/{sessionId}`](/api-reference/sessions/get), and [`PATCH /api/sessions/{sessionId}`](/api-reference/sessions/patch). The api serializes every field listed in `required` on each response, including `isNewBranch` (boolean, from the non-null `sessions.is_new_branch` column) and `artistId` (UUID or null).", "required": [ "id", "userId", @@ -1238,7 +1238,10 @@ "format": "date-time" }, "artistId": { - "type": ["string", "null"], + "type": [ + "string", + "null" + ], "format": "uuid", "description": "Artist account id this session was created in the context of, or `null` when no artist was associated. Set via `POST /api/sessions { artistId }`; surfaces here for clients (e.g. the chat sidebar) that filter sessions/chats by artist." } diff --git a/docs.json b/docs.json index ab8874f..d1c1cef 100644 --- a/docs.json +++ b/docs.json @@ -63,11 +63,11 @@ { "group": "Streaming", "pages": [ - "api-reference/chat/stop", + "api-reference/chat/workflow", + "api-reference/chat/workflow-stream", "api-reference/chat/runs", "api-reference/chat/runs-status", - "api-reference/chat/workflow", - "api-reference/chat/workflow-stream" + "api-reference/chat/stop" ] }, { From e59ca2371f452cf5b5352216f632aeb2f50e3efe Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Wed, 24 Jun 2026 14:10:01 -0500 Subject: [PATCH 10/10] docs: make endpoint-link formatting consistent within the touched descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The double-slash fix backticked only the {param} link labels, leaving plain links (e.g. POST /api/chat) alongside code-styled ones in the same Related list. Backtick the remaining plain method-links — but only in descriptions this PR already edits (the 4 chat endpoints + the Session schema touched by the sessionId fix). Unrelated endpoints (research/*, chats) are left untouched. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/openapi/research.json | 8 ++++---- api-reference/openapi/sessions.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index d0c2d80..5f50e33 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -648,7 +648,7 @@ }, "/api/chat/runs": { "post": { - "description": "Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [POST /api/chat](/api-reference/chat/workflow).\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — use that for **interactive, streaming** turns on an existing chat; use this for **headless/programmatic** runs (no browser or pre-provisioned session needed).\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.", + "description": "Start an asynchronous, headless chat-generation run on the durable agent workflow — the same engine as interactive [`POST /api/chat`](/api-reference/chat/workflow).\n\n**Related endpoints**\n- [`POST /api/chat`](/api-reference/chat/workflow) — use that for **interactive, streaming** turns on an existing chat; use this for **headless/programmatic** runs (no browser or pre-provisioned session needed).\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — poll to learn **whether** the run finished (and if it succeeded).\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — **watch the output live** by passing the returned `chatId`.", "security": [ { "apiKeyAuth": [] @@ -766,7 +766,7 @@ "/api/chat/{chatId}/stream": { "get": { "summary": "Resume a chat response stream", - "description": "Reconnects to an in-progress chat response — the resume counterpart to [POST /api/chat](/api-reference/chat/workflow), which never resumes. Returns the live Server-Sent Events stream when a response is still being generated, or `204 No Content` when there is nothing to resume. The chat must belong to the authenticated account.\n\n**Related endpoints**\n- [POST /api/chat](/api-reference/chat/workflow) — the interactive turn whose stream this resumes.\n- [POST /api/chat/runs](/api-reference/chat/runs) — start a **headless** run, then pass the returned `chatId` here to **watch its output live**.\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — check **whether** that run finished (status, not content).", + "description": "Reconnects to an in-progress chat response — the resume counterpart to [`POST /api/chat`](/api-reference/chat/workflow), which never resumes. Returns the live Server-Sent Events stream when a response is still being generated, or `204 No Content` when there is nothing to resume. The chat must belong to the authenticated account.\n\n**Related endpoints**\n- [`POST /api/chat`](/api-reference/chat/workflow) — the interactive turn whose stream this resumes.\n- [`POST /api/chat/runs`](/api-reference/chat/runs) — start a **headless** run, then pass the returned `chatId` here to **watch its output live**.\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — check **whether** that run finished (status, not content).", "security": [ { "apiKeyAuth": [] @@ -846,7 +846,7 @@ "/api/chat": { "post": { "summary": "Stream sandbox-driven chat (Vercel Workflow)", - "description": "Streams an agent loop running as a durable [Vercel Workflow](https://vercel.com/docs/workflow) against the session's sandbox. The agent uses sandbox-only tools (`bash`, `read`, `write`, `grep`, `glob`, `todo`, `task`, `ask_user_question`, `skill`, `fetch`) — no MCP or Composio. Requires a sandbox provisioned via [POST /api/sandbox](/api-reference/sandbox/create).\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — the **headless** counterpart: it provisions its own session + sandbox and runs without a streaming client. Use that for tasks/cron/programmatic runs; use this for **interactive, streaming** turns on an existing chat.\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — reconnect to an in-progress response.\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — check **whether** a headless run finished (status, not content).", + "description": "Streams an agent loop running as a durable [Vercel Workflow](https://vercel.com/docs/workflow) against the session's sandbox. The agent uses sandbox-only tools (`bash`, `read`, `write`, `grep`, `glob`, `todo`, `task`, `ask_user_question`, `skill`, `fetch`) — no MCP or Composio. Requires a sandbox provisioned via [`POST /api/sandbox`](/api-reference/sandbox/create).\n\n**Related endpoints**\n- [`POST /api/chat/runs`](/api-reference/chat/runs) — the **headless** counterpart: it provisions its own session + sandbox and runs without a streaming client. Use that for tasks/cron/programmatic runs; use this for **interactive, streaming** turns on an existing chat.\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — reconnect to an in-progress response.\n- [`GET /api/chat/runs/{runId}`](/api-reference/chat/runs-status) — check **whether** a headless run finished (status, not content).", "security": [ { "apiKeyAuth": [] @@ -2982,7 +2982,7 @@ }, "/api/chat/runs/{runId}": { "get": { - "description": "Status of an asynchronous run started via [POST /api/chat/runs](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.\n\n**Related endpoints**\n- [POST /api/chat/runs](/api-reference/chat/runs) — starts the run this reports on.\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — read the **content**: poll *this* to know **whether** a run finished; use the stream to **watch the output** as it's produced.\n- [POST /api/chat](/api-reference/chat/workflow) — the interactive, streaming counterpart to a headless run.", + "description": "Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.\n\n**Related endpoints**\n- [`POST /api/chat/runs`](/api-reference/chat/runs) — starts the run this reports on.\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — read the **content**: poll *this* to know **whether** a run finished; use the stream to **watch the output** as it's produced.\n- [`POST /api/chat`](/api-reference/chat/workflow) — the interactive, streaming counterpart to a headless run.", "security": [ { "apiKeyAuth": [] diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json index fa00621..394f84a 100644 --- a/api-reference/openapi/sessions.json +++ b/api-reference/openapi/sessions.json @@ -1084,7 +1084,7 @@ }, "Session": { "type": "object", - "description": "Agent session returned by [POST /api/sessions](/api-reference/sessions/create), [`GET /api/sessions/{sessionId}`](/api-reference/sessions/get), and [`PATCH /api/sessions/{sessionId}`](/api-reference/sessions/patch). The api serializes every field listed in `required` on each response, including `isNewBranch` (boolean, from the non-null `sessions.is_new_branch` column) and `artistId` (UUID or null).", + "description": "Agent session returned by [`POST /api/sessions`](/api-reference/sessions/create), [`GET /api/sessions/{sessionId}`](/api-reference/sessions/get), and [`PATCH /api/sessions/{sessionId}`](/api-reference/sessions/patch). The api serializes every field listed in `required` on each response, including `isNewBranch` (boolean, from the non-null `sessions.is_new_branch` column) and `artistId` (UUID or null).", "required": [ "id", "userId",