Chat & Query API

The primary endpoint for natural language queries against your connected databases. Synthesizes queries through the semantic layer, inlines formulas with Rust WASM, validates schema integrity, and executes against target databases.

Headers & Authentication

Authorization: Bearer <YOUR_API_KEY> // Or use x-api-key header

Content-Type: application/json

Origin: https://your-allowed-domain.com // If CORS restrictions apply

Request Body

json

{
  "messages": [
    {
      "role": "user",
      "content": "Give me the top 3 most expensive products in stock"
    }
  ],
  "configIds": ["db_config_northwind_01"],
  "modelId": "claude-haiku-4.5",
  "showResults": true
}

• messages (Array, required): Chat conversation history with standard role/content objects.

• configIds (Array of strings, optional): Scopes the query to specific connected database IDs. Defaults to the key's mapped databases.

• modelId (String, optional): Specific model alias (e.g. claude-haiku-4.5, gpt-4o-mini).

• showResults (Boolean, optional): Whether to execute and include tabular dataset rows (default: true).

Response Format (Synchronous)

json

{
  "text": "Here are the top 3 most expensive products currently in stock:",
  "reasoning": [
    "Identified user query: list products sorted by price descending with limit 3",
    "Pruned schema to table 'Products' with columns [ProductName, UnitPrice, UnitsInStock]",
    "Generated MDL query and transpiled via DataFusion WASM engine",
    "Dry-plan static validation passed with zero errors"
  ],
  "sql": "SELECT ProductName, UnitPrice, UnitsInStock FROM Products ORDER BY UnitPrice DESC LIMIT 3;",
  "tokensSpent": 1052,
  "executionTimeMs": 38,
  "resultSet": {
    "columns": ["ProductName", "UnitPrice", "UnitsInStock"],
    "rows": [
      { "ProductName": "Côte de Blaye", "UnitPrice": 263.5, "UnitsInStock": 17 },
      { "ProductName": "Thüringer Rostbratwurst", "UnitPrice": 123.79, "UnitsInStock": 0 },
      { "ProductName": "Mishi Kobe Niku", "UnitPrice": 97.0, "UnitsInStock": 29 }
    ]
  }
}

Streaming Responses

For interactive web applications using the Vercel AI SDK (useChat), /api/chat supports Server-Sent Events (SSE) streaming reasoning steps and tokens in real time.

HTTP Error Status Codes

401 UnauthorizedMissing or invalid API key / Clerk session token

403 ForbiddenRequest Origin domain not allowed for this API key

429 Too Many RequestsOrganization or API key request rate limit exceeded

500 Internal ErrorDatabase connection failure or unparseable query