Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/FloxTBoTyy/BoardPulse-AI/llms.txt

Use this file to discover all available pages before exploring further.

The chat query endpoint is the core of BoardPulse AI. You submit a question in plain English and receive a structured response that includes an AI-written executive summary, the SQL that was generated and executed, a data table, and downloadable export files.

​
Request

Method: POST
Path: /api/v1/chat/query
Content-Type: application/json

​
Body parameters

​
message
string
required
The natural-language question to ask. Must be between 2 and 2,000 characters.Example: "What were total sales by region last month?"
​
workspace_id
string
default:"default"
The workspace to query. Workspaces define which database and which tables are accessible. Use "default" unless you have configured multiple workspaces.
​
model
string
The specific model name to use for this request (e.g., "gpt-4.1-mini" or "qwen3:8b"). If omitted, the server uses the workspace’s configured default model.
​
preferred_provider
string
Forces a specific AI provider for this request. One of "cloud", "local", "hybrid", or "mock". If omitted, the server selects based on configuration.
  • cloud — OpenAI-compatible remote API
  • local — Ollama running locally
  • hybrid — tries local (Ollama) first, falls back to cloud
  • mock — deterministic mock responses (for testing)
​
include_sql
boolean
default:"true"
Whether to include the generated SQL in the response. Set to false if you only need the answer and table data.

​
Response

​
answer
string
The executive-summary answer written by the AI model in plain language.
​
sql
string | null
The SQL query generated by the AI before the row limit was applied. Present only when include_sql is true.
​
executed_sql
string | null
The actual SQL that was executed, including any LIMIT clause added by the guardrail layer. Always returned when a query was executed, regardless of the include_sql flag.
​
provider
string
The name of the AI provider that processed the request (e.g., "openai", "ollama", "mock").
​
table
object | null
The query results as a structured table.
​
chart
object | null
A chart specification if the AI determined the data is best presented visually.
​
exports
object[]
List of downloadable export files generated for this response.
​
warnings
string[]
Any non-fatal warnings generated during processing, such as a row limit being applied.
​
meta
object
Metadata about how the query was processed.
​
timestamp
string
ISO 8601 datetime indicating when the response was generated (UTC).

​
Example

curl -X POST http://localhost:8000/api/v1/chat/query \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What were total sales by region last month?",
    "workspace_id": "default",
    "include_sql": true
  }'

{
  "answer": "Total sales last month were $1,284,500, led by the North region at $512,000 (40%), followed by the South at $398,000 (31%) and the West at $374,500 (29%).",
  "sql": "SELECT region, SUM(amount) AS total_sales FROM sales_orders WHERE order_date >= date_trunc('month', current_date - interval '1 month') AND order_date < date_trunc('month', current_date) GROUP BY region ORDER BY total_sales DESC",
  "executed_sql": "SELECT region, SUM(amount) AS total_sales FROM sales_orders WHERE order_date >= date_trunc('month', current_date - interval '1 month') AND order_date < date_trunc('month', current_date) GROUP BY region ORDER BY total_sales DESC LIMIT 200",
  "provider": "openai",
  "table": {
    "columns": ["region", "total_sales"],
    "rows": [
      {"region": "North", "total_sales": 512000},
      {"region": "South", "total_sales": 398000},
      {"region": "West", "total_sales": 374500}
    ],
    "row_count": 3
  },
  "chart": {
    "type": "bar",
    "title": "Total Sales by Region",
    "x_label": "Region",
    "y_label": "Total Sales ($)",
    "series": [
      {"label": "North", "value": 512000},
      {"label": "South", "value": 398000},
      {"label": "West", "value": 374500}
    ],
    "base64_image": null
  },
  "exports": [
    {
      "format": "csv",
      "filename": "sales-by-region-1714123456.csv",
      "url": "http://localhost:8000/api/v1/exports/sales-by-region-1714123456.csv"
    },
    {
      "format": "xlsx",
      "filename": "sales-by-region-1714123456.xlsx",
      "url": "http://localhost:8000/api/v1/exports/sales-by-region-1714123456.xlsx"
    }
  ],
  "warnings": [],
  "meta": {
    "source_dialect": "postgresql",
    "approved_tables": ["sales_orders", "invoices", "inventory_items"],
    "row_count": 3
  },
  "timestamp": "2026-04-26T14:32:10.123456+00:00"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us