POST /api/v1/chat/query — ask a business question

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

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?"

string

default:"default"

The workspace to query. Workspaces define which database and which tables are accessible. Use "default" unless you have configured multiple workspaces.

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.

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)

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

string

The executive-summary answer written by the AI model in plain language.

string | null

The SQL query generated by the AI before the row limit was applied. Present only when include_sql is true.

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.

string

The name of the AI provider that processed the request (e.g., "openai", "ollama", "mock").

object | null

The query results as a structured table.

Show QueryResultTable fields

string[]

Ordered list of column names returned by the query.

object[]

Array of row objects. Each object maps column name to value.

integer

Total number of rows returned (after the row limit is applied).

object | null

A chart specification if the AI determined the data is best presented visually.

Show ChartSpec fields

string

Chart type. One of "line", "bar", "pie", or "table".

string

The chart title.

string

Label for the horizontal axis.

string

Label for the vertical axis.

object[]

Array of data points, each with a label (string) and value (number).

string | null

A base64-encoded PNG rendering of the chart, if image generation is enabled.

object[]

List of downloadable export files generated for this response.

Show ExportArtifact fields

string

File format. The current pipeline generates "csv" and "xlsx".

string

The filename used to download the file via the exports endpoint.

string

Full URL to download the file via GET /api/v1/exports/{filename}.

string[]

Any non-fatal warnings generated during processing, such as a row limit being applied.

object

Metadata about how the query was processed.

Show meta fields

string

The SQL dialect of the source database (e.g., "postgresql").

string[]

The tables that were available to the query.

integer

Number of rows in the result set.

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"
}

Overview

Endpoints

POST /api/v1/chat/query — ask a business question

Request

Body parameters

Response

Example

​Request

​Body parameters

​Response

​Example

Request

Body parameters

Response

Example