Ask questions
Get answers written from your documents, with the sources they came from, follow-ups that keep context, and saved conversations.
POST /v1/{knowledge_id}/chat answers a question from the collection: it finds the relevant documents and sections, reads their extracted fields, and writes an answer citing its sources.
Request
| Field | Type | Default | Meaning |
|---|---|---|---|
query | string | — (required) | The question. |
stream | boolean | true | false returns one JSON object; true returns server-sent events. |
session_id | string | new conversation | Continue a conversation. A session_id from another collection returns 404. |
model, provider, temperature, max_tokens, system_prompt | — | collection settings | Override the collection's answer settings for this call only. |
Python
import os
import requests
API_ROOT = "https://futuresmart.ai/document-intelligence/api"
COLLECTION_ID = os.environ["DOCUMENT_INTELLIGENCE_COLLECTION_ID"]
HEADERS = {"x-api-key": os.environ["DOCUMENT_INTELLIGENCE_API_KEY"]}
def ask(query, session_id=None):
body = {"query": query, "stream": False}
if session_id:
body["session_id"] = session_id
r = requests.post(f"{API_ROOT}/v1/{COLLECTION_ID}/chat", headers=HEADERS, json=body, timeout=120)
r.raise_for_status()
return r.json()
first = ask("What is the total due on the invoice?")
print(first["response"])
follow_up = ask("And when is it due?", session_id=first["session_id"])
print(follow_up["response"])
print("Sources:", [s["title"] for s in follow_up["data"]["knowledge"]["relevant_sources"]["data"]])JavaScript
const API_ROOT = "https://futuresmart.ai/document-intelligence/api";
const COLLECTION_ID = process.env.DOCUMENT_INTELLIGENCE_COLLECTION_ID;
async function ask(query, session_id) {
const res = await fetch(`${API_ROOT}/v1/${COLLECTION_ID}/chat`, {
method: "POST",
headers: {
"x-api-key": process.env.DOCUMENT_INTELLIGENCE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ query, session_id, stream: false }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
return res.json();
}
const first = await ask("What is the total due on the invoice?");
console.log(first.response);
const followUp = await ask("And when is it due?", first.session_id);
console.log(followUp.response);
console.log("Sources:", followUp.data.knowledge.relevant_sources.data.map((s) => s.title));Shell
curl -sS -X POST "https://futuresmart.ai/document-intelligence/api/v1/$DOCUMENT_INTELLIGENCE_COLLECTION_ID/chat" \
-H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "What is the total due on the invoice?", "stream": false}'Response
| Field | Meaning |
|---|---|
response | The answer, in Markdown. |
query, refined_query | Your question, and the self-contained version that was answered (follow-ups are rewritten to stand alone). |
session_id, chat_id | The conversation, and this question-and-answer turn. |
is_answered | "yes" or "no" — whether the documents held an answer. |
follow_up | Suggested next questions. |
data.knowledge.relevant_sources.data[] | The documents the answer drew on: id (the document's object_id), title (its file name or URL) and context (its summary). |
data.knowledge.summaries | Per source document: its summary and its extracted fields. |
data.knowledge.detailed_chunks | The sections read to answer. |
usage | Tokens used by this answer. |
error | Set instead of an answer when generation failed. |
Sources are left out when the collection's owner has turned off showing sources.
Conversations
Every question without a session_id starts a new conversation. Saved conversations — from the API, the app and any shared chat — can be read back:
GET /v1/{knowledge_id}/sessionslists them withtitle,exchange_count,source(api,widget, …) and timestamps, paginated.GET /v1/{knowledge_id}/sessions/{session_id}returns one conversation's messages.
Deleting conversations and rating answers are done in the app.
Getting better answers
- Ask about what the fields capture. Questions such as "Which invoices are due before December?" are answered from the extracted fields across every document, not only from passages.
- Name the document when you mean one. "On invoice INV-2026-0142, …" keeps the answer to that document.
- Follow up instead of repeating context. Send "and the due date?" with the same
session_id.