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

Scope registration is target-aware. A single-domain runtime builds internal plus that target's external scope; the all target builds all five. A supported scope in the schema can therefore still be unavailable when its docs-chat agent was not included by the active loader target. Use /agents.json or startup logs to confirm the running deployment.

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

Regenerate/check the shared MCP/docs-chat inventory when scopes or tool registries change:

npm run docs:mcp:check
npm run docs:context:check

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