From 7152595f00678c178b6d4bc81e86782eb8eb2de2 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Thu, 4 Jun 2026 18:33:50 -0500 Subject: [PATCH 1/2] docs: make POST /api/chat canonical; deprecate /api/chat/workflow alias MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Contract-first step of the /api/chat/workflow → /api/chat rename (chat#1767). - OpenAPI: rename the canonical path to /api/chat; add a deprecated /api/chat/workflow alias (identical behaviour) retained for backward compatibility while consumers (chat, open-agents, API-key callers) migrate. - Repoint the Stream Chat page + credits references to POST /api/chat. No api/consumer change in this PR — those follow against this contract. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/chat/workflow.mdx | 2 +- api-reference/openapi/research.json | 52 +++++++++++++++++++++++++++-- credits.mdx | 4 +-- 3 files changed, 53 insertions(+), 5 deletions(-) diff --git a/api-reference/chat/workflow.mdx b/api-reference/chat/workflow.mdx index ed1c1c09..11933d14 100644 --- a/api-reference/chat/workflow.mdx +++ b/api-reference/chat/workflow.mdx @@ -1,4 +1,4 @@ --- title: 'Stream Chat (Workflow + Sandbox)' -openapi: 'POST /api/chat/workflow' +openapi: 'POST /api/chat' --- diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 277003b7..7deccfb9 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -753,10 +753,10 @@ } } }, - "/api/chat/workflow": { + "/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> **Note:** `POST /api/chat/workflow` is a deprecated alias of this endpoint, retained for backward compatibility while consumers migrate. Prefer `POST /api/chat`.", "security": [ { "apiKeyAuth": [] @@ -846,6 +846,54 @@ } } }, + "/api/chat/workflow": { + "post": { + "deprecated": true, + "summary": "Deprecated alias of POST /api/chat", + "description": "**Deprecated — use [POST /api/chat](/api-reference/chat/workflow).** This path is a backward-compatible alias retained while consumers migrate off `/api/chat/workflow`; it will be removed in a future release. Behaviour, request body, and responses are identical to `POST /api/chat`.", + "security": [ + { + "apiKeyAuth": [] + } + ], + "requestBody": { + "description": "Chat workflow request (identical to POST /api/chat)", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatWorkflowRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Identical to POST /api/chat — Server-Sent Events stream of UI message parts with an `x-workflow-run-id` response header." + }, + "400": { + "description": "Bad request — missing required fields, invalid body, or sandbox not initialized.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatStreamErrorResponse" + } + } + } + }, + "401": { + "description": "Missing or invalid API key.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatStreamErrorResponse" + } + } + } + } + } + } + }, "/api/research": { "get": { "description": "Unified music research search. This is the discovery primitive for the detail-lookup endpoints — use `type=artists` to find an `id` for [GET /api/research/albums](/api-reference/research/albums), `type=tracks` for [GET /api/research/track](/api-reference/research/track), `type=playlists` for [GET /api/research/playlist](/api-reference/research/playlist), etc. Pick the right `id` from the returned results and pass it to the appropriate detail endpoint.\n\nSearches the configured research data source. Use the `type` and `limit` parameters to narrow results before passing a returned `id` to a detail endpoint.", diff --git a/credits.mdx b/credits.mdx index 3a1409e7..c1ae93c7 100644 --- a/credits.mdx +++ b/credits.mdx @@ -13,7 +13,7 @@ Some Recoup endpoints are billed in **credits** — primarily endpoints that hit |--------|---------|-------| | **Research** ([`/api/research/*`](/api-reference/research/search)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). | | **Content generation** ([`/api/image/generate`](/api-reference/image/generation)) | Yes | Image generation is priced per call. | -| **AI Chat — streaming** ([`POST /api/chat/workflow`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. | +| **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. | | **Everything else** | Free at the API layer | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [social integrations](/api-reference/social/scrape), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. | Failed calls (4xx / 5xx) do **not** deduct credits. Deduction happens only after the upstream call succeeds. @@ -175,7 +175,7 @@ Current as of this revision of the page. The authoritative source is the per-end | Endpoint | Cost | |----------|------| -| [`POST /api/chat/workflow`](/api-reference/chat/workflow) (streaming) | ≥1 credit per turn — variable based on model token usage | +| [`POST /api/chat`](/api-reference/chat/workflow) (streaming) | ≥1 credit per turn — variable based on model token usage | | [`GET /api/research/*`](/api-reference/research/search) (artist & non-artist research) | 5 credits per call | | [`POST /api/research/people`](/api-reference/research/people) | 5 credits per call | | [`POST /api/research/web`](/api-reference/research/web) | 5 credits per call | From 74609780ac3c6ad7f663d674d1f9a31957d8f75b Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Thu, 4 Jun 2026 18:37:55 -0500 Subject: [PATCH 2/2] docs: drop deprecation notes (YAGNI) + simplify Stream Chat title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review on #235: - Remove the deprecation note from the /api/chat description and drop the deprecated /api/chat/workflow alias block — docs now document only the canonical /api/chat (api still serves /workflow for backward compat). - Simplify page title "Stream Chat (Workflow + Sandbox)" → "Stream Chat". Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/chat/workflow.mdx | 2 +- api-reference/openapi/research.json | 50 +---------------------------- 2 files changed, 2 insertions(+), 50 deletions(-) diff --git a/api-reference/chat/workflow.mdx b/api-reference/chat/workflow.mdx index 11933d14..6e6b7804 100644 --- a/api-reference/chat/workflow.mdx +++ b/api-reference/chat/workflow.mdx @@ -1,4 +1,4 @@ --- -title: 'Stream Chat (Workflow + Sandbox)' +title: 'Stream Chat' openapi: 'POST /api/chat' --- diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 7deccfb9..397d0999 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -756,7 +756,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> **Note:** `POST /api/chat/workflow` is a deprecated alias of this endpoint, retained for backward compatibility while consumers migrate. Prefer `POST /api/chat`.", + "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).", "security": [ { "apiKeyAuth": [] @@ -846,54 +846,6 @@ } } }, - "/api/chat/workflow": { - "post": { - "deprecated": true, - "summary": "Deprecated alias of POST /api/chat", - "description": "**Deprecated — use [POST /api/chat](/api-reference/chat/workflow).** This path is a backward-compatible alias retained while consumers migrate off `/api/chat/workflow`; it will be removed in a future release. Behaviour, request body, and responses are identical to `POST /api/chat`.", - "security": [ - { - "apiKeyAuth": [] - } - ], - "requestBody": { - "description": "Chat workflow request (identical to POST /api/chat)", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChatWorkflowRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Identical to POST /api/chat — Server-Sent Events stream of UI message parts with an `x-workflow-run-id` response header." - }, - "400": { - "description": "Bad request — missing required fields, invalid body, or sandbox not initialized.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChatStreamErrorResponse" - } - } - } - }, - "401": { - "description": "Missing or invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChatStreamErrorResponse" - } - } - } - } - } - } - }, "/api/research": { "get": { "description": "Unified music research search. This is the discovery primitive for the detail-lookup endpoints — use `type=artists` to find an `id` for [GET /api/research/albums](/api-reference/research/albums), `type=tracks` for [GET /api/research/track](/api-reference/research/track), `type=playlists` for [GET /api/research/playlist](/api-reference/research/playlist), etc. Pick the right `id` from the returned results and pass it to the appropriate detail endpoint.\n\nSearches the configured research data source. Use the `type` and `limit` parameters to narrow results before passing a returned `id` to a detail endpoint.",