12 Chat
4 operations.
12.0.1 getAgUiChatCapabilities
GET /api/ag-ui-chat
Reports the chat endpoint’s capabilities (no login; static status information).
Why it exists. ‡ Report whether the chat surface is ready and which capabilities and tools it currently offers, for health checks and for the interface to adapt to what the engine supports.
Called by — components/chat/ai-chat-interface.tsx
Unauthenticated — static capability/health descriptor for the AG-UI chat endpoint. No backend call is made.
Authentication: none
Returns — status · capabilities · timestamp
Field names as the handler returns them; the source states no types for them.
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Capability descriptor | |
500 |
The descriptor could not be built. | Error |
12.0.2 sendAgUiChatMessage
POST /api/ag-ui-chat
Sends a chat message to the AI and streams the reply back live — the main assistant pipeline (no login at this door; identity travels inside the message).
Why it exists. ‡ Ask the AI engine a question about the caller’s data and stream the answer back as it is produced, together with the tool calls it made. The interface’s main conversational surface.
Called by — components/chat-sidebar.tsx · components/chat/ai-chat-interface.tsx
Main chat entrypoint. Ensures a chat session, persists the user message, proxies the prompt to the AI backend’s /chat/agui/stream (AI_SERVER_URL), and either relays AG-UI events as SSE (stream: true) or returns a collected JSON result. Credentials travel in the request body (auth.jwt_token), not in headers; the token is verified (signature-checked against Supabase), then forwarded to the AI backend as a bearer token. The streaming response always has HTTP status 200 — errors are delivered in-band as RUN_ERROR events. The event contract is CONTRACT-CDC-001 (see the Web Handbook’s AG-UI chapters).
Authentication: none
Returns — response · events · datasets · metadata · sessionId · timestamp
Field names as the handler returns them; the source states no types for them.
Effect — writes (insert, update) chat_sessions · messages
Request body
| Field | Type | Required |
|---|---|---|
message |
string | no |
auth |
no | |
stream |
boolean | no |
sessionId |
string (uuid) | no |
system_type |
string | no |
dataset_scope |
no | |
conversation_history |
array of object | no |
workspace_context |
no | |
attachments |
array of object | no |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Collected result (stream=false, application/json) or an SSE event stream (stream=true, text/event-stream) of AG-UI events terminated by a CUSTOM/SESSION_METADATA event carrying the sessionId. | |
400 |
Missing message, auth config, or JWT token. | Error |
401 |
JWT expired or expiring within 5 minutes. | Error |
500 |
Server error (upstream AI-server errors are passed through with their status on the non-streaming path). | Error |
12.0.3 sendMcpChatMessage
POST /api/mcp-chat
The older, legacy chat pipeline, kept for compatibility (no login at this door).
Why it exists. † Forward a question to the tool server over its own protocol, refreshing the caller’s token if it has expired. An alternative path to the AI engine.
Legacy/alternate chat proxy to the AI backend’s /chat and /chat/stream. Persists nothing (history/save are stubs). Requires auth.jwt_token in the body (the former admin_mode exemption is removed); with auth.user_password present an expired token is refreshed via the backend’s /auth/refresh. Streaming responses are SSE-formatted frames served as text/plain. The token is forwarded to the legacy server unverified locally — checked for presence only, not signature.
Authentication: none
Returns — response · sessionId · timestamp
Field names as the handler returns them; the source states no types for them.
Request body
| Field | Type | Required |
|---|---|---|
message |
string | no |
auth |
no | |
stream |
boolean | no |
sessionId |
string | no |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Chat response (JSON) or SSE-formatted stream (text/plain) with lowercase event types (run_started, thinking_update, run_completed, error…). | |
400 |
Message is required. | Error |
401 |
No jwt_token supplied. | Error |
500 |
Server or upstream error. | Error |
12.0.4 listAgentSystems
GET /api/systems
Lists the available AI agent systems the user can choose from (no login; falls back to a built-in list if the AI backend is unreachable).
Why it exists. ‡ List the AI engines the backend offers, optionally only those that have passed end-to-end verification, so the engine selector is driven by the backend rather than hardcoded. Falls back to a fixed list when the backend is unreachable.
Called by — hooks/use-ai-engines.ts
Reached from — /settings
Unauthenticated — proxies the AI backend’s /systems (or /systems/verified when verified=true) and reports no engines, rather than inventing three, when the backend is unreachable. Never returns an error status.
Authentication: none
Returns — not readable from the source: the handler returns a value assembled at run time rather than a literal.
Parameters
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
verified |
query | no | string — one of true |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Available systems and the default system id. |