The public API powers the widget and all SDKs. It is client-key authenticated and CORS-enabled.

​
Base URL

All public endpoints are under /api/v1/public. Open protocols (/mcp, /a2a/knowledge-bases/:knowledgeBaseId) are root-level.

​
Endpoints

​
Conventions

  • JSON everywhere; chat responses stream Server-Sent Events.
  • Restricted documents are always excluded from public-API retrieval.
  • group_ids — chat, search, form-deflect, and WebSocket requests accept an optional group_ids array to scope retrieval to source groups. The server intersects it with the client key’s allowed_groups: requests can narrow but never widen. Group IDs must belong to the knowledge base and the key’s allowed set, otherwise the request fails with 403.

​
Errors

The envelope is a flat string, with an appropriate HTTP status:
A few responses carry a machine-readable code alongside it, where a client has to branch on the reason rather than display it — KNOWLEDGE_BASE_INTERNAL when a key points at an internal knowledge base, and MCP_NOT_ENABLED when a key without the MCP permission calls the MCP server. The WebSocket transport sends its own error frames. MCP and A2A return JSON-RPC error objects instead, per those protocols. Rate limits return 429 with X-RateLimit-Limit and X-RateLimit-Remaining headers. Set a key’s rate_limit_per_min at creation; 0 or unset applies the deployment default of 600/min, and a negative value means unlimited.

​
Local development

Every endpoint is available on a locally-run API server at http://localhost:8280 (WebSocket: ws://localhost:8280). All SDKs accept a baseUrl override.