Ask questions

Every option of the chat request, every field of the answer, and how SQL, rows and charts are controlled.

POST /v1/agents/{agent_id}/chat asks one question and returns one answer. It starts a new conversation unless you pass a session_id.

Request

Field	Type	Default	Meaning
`query`	string	— (required)	The question, in plain language.
`session_id`	string	new conversation	Continue an existing conversation. A `session_id` that belongs to another agent returns `404`.
`debug_info`	boolean	agent setting, else `false`	Return the SQL, the tables used and the result rows in `debug_info`.
`chart_output`	boolean	agent setting, else `true`	Return a chart suggestion when the result suits one.
`follow_up`	boolean	agent setting, else `false`	Return suggested next questions in `follow_up`.
`allowed_charts`	string[]	agent setting	Limit which chart types may be suggested.
`user_id`	string	the key's user	Who asked, as recorded in analytics and conversation history.

Query parameter stream (default false) switches the response to server-sent events. See Streaming.

A field you leave out (or send as null) falls back to the agent's own setting in the app, then to the default above.

Python

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
AGENT_ID = os.environ["DATABASE_AGENT_ID"]

r = requests.post(
    f"{API_ROOT}/v1/agents/{AGENT_ID}/chat",
    headers={"X-API-Key": os.environ["DATABASE_AGENT_API_KEY"]},
    json={
        "query": "How many orders were placed in each month of 2025? Show a bar chart.",
        "debug_info": True,
        "chart_output": True,
        "follow_up": True,
    },
    timeout=180,
)
r.raise_for_status()
answer = r.json()

print(answer["response"])
result = answer["debug_info"]["db_result"]
print([c["name"] for c in result["columns"]], result["row_count"], "rows")
if answer["chart_output"]:
    print("Chart:", answer["chart_output"]["chart_suggestion"])
print("Try next:", answer["follow_up"])

JavaScript

const API_ROOT = "https://futuresmart.ai/database-agent/api";
const AGENT_ID = process.env.DATABASE_AGENT_ID;

const res = await fetch(`${API_ROOT}/v1/agents/${AGENT_ID}/chat`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.DATABASE_AGENT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "How many orders were placed in each month of 2025? Show a bar chart.",
    debug_info: true,
    chart_output: true,
    follow_up: true,
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const answer = await res.json();

console.log(answer.response);
const result = answer.debug_info.db_result;
console.log(result.columns.map((c) => c.name), result.row_count, "rows");
if (answer.chart_output) console.log("Chart:", answer.chart_output.chart_suggestion);
console.log("Try next:", answer.follow_up);

Shell

curl -sS -X POST "https://futuresmart.ai/database-agent/api/v1/agents/$DATABASE_AGENT_ID/chat" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How many orders were placed in each month of 2025? Show a bar chart.",
    "debug_info": true,
    "chart_output": true,
    "follow_up": true
  }'

Response

Field	Type	Meaning
`response`	string	The answer, in Markdown (it may contain headings, bold text and tables).
`session_id`	string	The conversation this answer belongs to.
`chat_id`	string	This question-and-answer turn. Used to rate an answer and to export rows.
`is_answered`	boolean	`false` when the agent could not answer from the data — for example the question is about something the database does not hold.
`follow_up`	string[] \| null	Suggested next questions, when `follow_up` was requested.
`debug_info`	object \| null	Present when `debug_info` was requested. See below.
`chart_output`	object \| null	A chart suggestion, when charts are on and the result suits one.
`graph_output`	object \| null	The same object as `chart_output`, kept for older clients.
`trace_id`	string \| null	Internal trace reference; quote it when reporting a problem.

`debug_info`

Field	Meaning
`query`, `refined_query`	Your question, and the self-contained version the agent answered (follow-ups are rewritten to stand alone).
`selected_db_id`, `selected_db_name`	The database the agent chose, when the agent has several.
`sql_query`	The SQL that was run. Only when the agent's Settings → Answers shows SQL.
`selected_tables`	Tables the query used. Only with `sql_query`.
`db_result`	`columns` (name and type), `rows` (one object per row, keyed by column name), `row_count` and `truncated`. Only when the agent shows results.

When a result has more than 50 rows, db_result.rows carries a 10-row preview and debug_info.export_url is a pre-signed link to the full result as CSV.

If the agent hides SQL or results in its settings, those fields are left out even when you ask for debug_info. That setting is the agent owner's choice and the API enforces it.

`chart_output`

JSON

{
  "chart_suggestion": "Column Chart",
  "chart_data": {
    "data": [
      { "category": "2025-01-01", "value": 216.0 },
      { "category": "2025-02-01", "value": 211.0 }
    ],
    "metadata": {
      "title": "Orders Placed by Month in 2025",
      "x_axis": { "label": "Month", "field": "month" },
      "y_axis": { "label": "Number of Orders", "field": "order_count" },
      "legend": { "show": false, "position": null },
      "colors": ["#3498db", "#e74c3c"]
    }
  },
  "metadata": null
}

chart_data.data is ready to hand to a charting library: one point per category. Asking for a chart in the question ("Show a bar chart") makes one more likely; the agent still picks the type that suits the data.

Rating an answer

Send a thumbs up or down for a turn with POST /v1/agents/{agent_id}/feedback, using the chat_id from the answer. Ratings appear in the app's analytics. See the Chat reference.

Writing good questions

Name the measure and the period. "Revenue by month in 2025" beats "how are sales".
Use the words your data uses. If the table says region, ask about regions.
Follow up instead of repeating context. Send "and for 2024?" to the same session_id.
Teach the agent your vocabulary. Table and column descriptions and example questions, set in the app or through the API reference, make answers more accurate.

Ask questions

#Request

#Response

#debug_info

#chart_output

#Rating an answer