docs: make POST /api/chat canonical; deprecate /api/chat/workflow alias

Merged
SW
5mo ago
+5-5

Contract-first step of the /api/chat/workflow → /api/chat rename (chat#1767). This PR establishes the contract; api + consumers fulfill it in follow-ups.

Why

The workflow chat endpoint should own the canonical /api/chat name now that the legacy streaming endpoint was deleted (api#632 / docs#230). Three independently-deployed consumers (chat useChatTransport, open-agents chat-api-client, plus external API-key callers) still call /api/chat/workflow, so the rename must be additive — both paths answer during migration.

Changes

  • OpenAPI (research.json): rename the canonical path → POST /api/chat; add a deprecated: true /api/chat/workflow alias (identical request/responses) with a note that it's retained for backward compatibility and will be removed once consumers migrate.
  • api-reference/chat/workflow.mdx: frontmatter now targets POST /api/chat (page kept to avoid nav churn).
  • credits.mdx: the two streaming-cost rows reference POST /api/chat.

Follow-ups (not in this PR)

  1. api — add POST /api/chat (+OPTIONS) delegating to handleChatWorkflowStream, keep /api/chat/workflow.
  2. chat — repoint useChatTransport → /api/chat.
  3. open-agents — repoint CHAT_API_POST_PATH → /api/chat.
  4. cleanup (later) — remove /api/chat/workflow once prod is fully migrated.

Verification

  • research.json parses as valid JSON; both /api/chat and /api/chat/workflow (deprecated) present.
  • Reviewer: optional npx mintlify dev to confirm the Stream Chat page renders under POST /api/chat.

Summary by cubic

Make POST /api/chat the canonical chat streaming endpoint in OpenAPI and docs, and stop documenting /api/chat/workflow. Simplifies the Stream Chat page title and updates credits to point to POST /api/chat.

  • Refactors

    • OpenAPI: replace /api/chat/workflow with POST /api/chat; remove alias and deprecation notes.
    • Docs: retarget Stream Chat frontmatter to POST /api/chat and rename title to "Stream Chat".
    • Credits: update streaming cost links to POST /api/chat.

  • Migration

    • Use POST /api/chat; the API still serves /api/chat/workflow for backward compatibility.
    • No API/consumer changes in this PR; follow-ups will repoint callers.