Chat

Query your data with natural language and get AI-generated insights.

The Chat API lets you query your data using natural language. It searches your collections, analyzes results, and can generate visualizations.

Endpoint

POST /api/v1/analytics/chat

Send a natural language query and receive search results with optional AI analysis.

Request:

curl -X POST https://api.ballast.sh/v1/analytics/chat 
  -H "Authorization: Bearer <token>" 
  -H "Content-Type: application/json" 
  -d '{
    "query": "Show me revenue trends by month",
    "collectionIds": ["col_abc123"],
    "conversationId": "conv_xyz789"
  }'

Parameters:

Field	Type	Required	Description
`query`	string	Yes	Natural language query
`collectionIds`	array	Yes	Collections to search
`conversationId`	string	No	Continue existing conversation

Response:

{
  "success": true,
  "conversationId": "conv_xyz789",
  "messageId": "msg_123",
  "response": "Based on the data...",
  "charts": [
    {
      "chartType": "line",
      "title": "Monthly Revenue",
      "data": {...}
    }
  ],
  "sources": [
    {
      "id": "doc_456",
      "title": "Q3 Report",
      "snippet": "..."
    }
  ]
}

Conversation Flow

The Chat API maintains conversation context:

Start conversation - Omit conversationId to start new
Continue conversation - Include conversationId from previous response
Reference prior context - AI remembers previous messages

Chart Generation

When your query involves data analysis, the API can generate Chart.js-compatible visualizations:

Line charts
Bar charts
Pie charts
Area charts
Scatter plots
And more

Charts are returned in the charts array with full configuration for rendering.

Saving as Dashboard

Chat conversations with charts can be saved as dashboards using the Dashboard API. See Dashboards API for details.

Error Responses

Status	Error	Description
`400`	`invalid_request`	Missing required fields
`401`	`unauthorized`	Invalid authentication
`403`	`forbidden`	No access to collection
`500`	`chat_failed`	AI processing error