Docs Chat Contract

The documentation assistant calls the Mastra runtime docs chat route. This page documents the callable contract so agents can use the assistant without needing the full backend environment.

Route

Field	Value
Method	`POST`
Direct runtime route	`/docs/chat`
Testing APIM route	`https://test-aitools-llfc-apim.azure-api.net/docs/chat` when APIM publishes the runtime route
Content type	`application/json`
Response type	`text/event-stream`
Source	`packages/platform-runtime/src/server/routes/docs-chat.routes.ts`
Frontend client	`docusaurus-docs/src/components/DocsChat/useDocsChat.js`

The Docusaurus client builds the URL as ${DOCS_CHAT_API_BASE_URL}/docs/chat. For testing, set DOCS_CHAT_API_BASE_URL to the APIM gateway root if the route is published there.

Auth

Send the subscription key in the Ocp-Apim-Subscription-Key header.

Scope family	Expected backend key
External scopes	`APIM_SUBSCRIPTION_KEY`
`internal` scope	`INTERNAL_DOCS_CHAT_API_KEY`

Shared Replit workspaces should use external scopes with the testing APIM key. Do not enable the internal scope in a shared Replit workspace unless a maintainer explicitly approves exposing internal docs/code-reference access.

Request Body

{
  "message": "How do I call the SDAC widget upload endpoint?",
  "scope": "sdac-external",
  "messages": [
    { "role": "user", "content": "Optional prior message" },
    { "role": "assistant", "content": "Optional prior answer" }
  ]
}

Supported scopes are:

internal
k12-external
tap-external
sdac-external
re-external

Stream Events

The route streams Server-Sent Events. Clients should handle these event types:

Event	Meaning
`tool-start`	A docs/code search tool started.
`tool-result`	A tool completed.
`source`	A cited docs or code source.
`delta`	Assistant text token/content.
`error`	Recoverable stream error payload.
`done`	Stream complete.

Errors

Status	Meaning
`400`	Invalid request body or unsupported scope.
`401`	Missing `Ocp-Apim-Subscription-Key`.
`403`	Invalid key for the requested scope.
`503`	Docs chat authentication is not configured in the runtime.
`500`	Runtime failed while processing the chat request.

Validation

Source-backed validation lives in docs/internal/documentation-revival/mcp-docs-chat-validation.md.

Recommended checks:

npm run test:run -- \
  tests/shared/unit/routes/docs-chat-routes.test.ts \
  tests/shared/unit/agents/docs-chat-agents.test.ts \
  tests/shared/unit/docusaurus/useDocsChat.test.ts \
  tests/shared/unit/docusaurus/docs-chat-sse-parser.test.ts

node bruno/scripts/run-bruno-suite.mjs --env testing --folder 70-docs-chat

Route​

Auth​

Request Body​

Stream Events​

Errors​