Chat Endpoints
The Chat API powers the conversational analytics experience in the BI Workbench. It manages multi-turn chat sessions, routes messages through the AnalyticsOrchestrator state machine, and returns structured responses with SQL, data, visualizations, and natural language explanations.
Create Session
Creates a new chat session for conversational analytics.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/bi/chat/sessions |
| Auth | JWT required |
Request Body
{
"tenant_id": "acme-corp",
"user_id": "user-456"
}Response
{
"session_id": "sess-abc123",
"tenant_id": "acme-corp",
"user_id": "user-456",
"created_at": "2025-03-15T10:00:00Z",
"message_count": 0
}Send Message
Sends a natural language message to an existing chat session. The message is routed through the AnalyticsOrchestrator which classifies intent and delegates to specialized agents.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/bi/chat/sessions/:session_id/messages |
| Auth | JWT required |
Request Body
{
"message": "What were our top 10 customers by revenue last month?"
}Response
{
"success": true,
"response": "Here are your top 10 customers by revenue for last month...",
"intent": "sql_query",
"sql": "SELECT customer_name, SUM(amount) as revenue FROM orders WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1' MONTH) GROUP BY customer_name ORDER BY revenue DESC LIMIT 10",
"visualization": {
"type": "bar",
"x_axis": "customer_name",
"y_axis": "revenue"
},
"data": {
"columns": ["customer_name", "revenue"],
"rows": [["Acme Inc", 150000], ["Beta Corp", 120000]]
},
"insights": ["Revenue is concentrated in the top 3 customers (60% of total)"],
"agents_visited": ["router", "sql_agent", "viz_agent"],
"execution_time_ms": 3200
}Get Session History
Retrieves the full conversation history for a session.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/bi/chat/sessions/:session_id/history |
| Auth | JWT required |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | no | Maximum messages to return (default 50) |
| offset | integer | no | Skip first N messages |
Response
{
"session_id": "sess-abc123",
"messages": [
{
"role": "user",
"content": "What were our top 10 customers?",
"timestamp": "2025-03-15T10:00:05Z",
"metadata": {}
},
{
"role": "assistant",
"content": "Here are your top 10 customers...",
"timestamp": "2025-03-15T10:00:08Z",
"metadata": {"intent": "sql_query", "agents_visited": ["router", "sql_agent"]}
}
],
"total_count": 2
}Refine Query
Refines the most recent query within a session without starting a new analytical path.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/bi/chat/sessions/:session_id/refine |
| Auth | JWT required |
Request Body
{
"refinement": "Filter to only US customers"
}Change Visualization
Changes the chart type for the current query result without re-executing the SQL.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/bi/chat/sessions/:session_id/visualize |
| Auth | JWT required |
Request Body
{
"chart_type": "pie"
}WebSocket Chat
Opens a WebSocket connection for real-time bidirectional chat with streaming responses.
| Property | Value |
|---|---|
| Protocol | WebSocket |
| Path | /ws/chat/:session_id |
| Auth | JWT token as query parameter |
Client Message
{
"type": "message",
"content": "Show revenue by region"
}Server Events
{
"type": "stream_start",
"agent": "sql_agent"
}{
"type": "text",
"content": "Generating SQL query..."
}{
"type": "result",
"data": {"sql": "...", "visualization": {}, "insights": []}
}