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

FieldTypeDefaultMeaning
querystring— (required)The question.
streambooleantruefalse returns one JSON object; true returns server-sent events.
session_idstringnew conversationContinue a conversation. A session_id from another collection returns 404.
model, provider, temperature, max_tokens, system_prompt—collection settingsOverride 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"]])

Response

FieldMeaning
responseThe answer, in Markdown.
query, refined_queryYour question, and the self-contained version that was answered (follow-ups are rewritten to stand alone).
session_id, chat_idThe conversation, and this question-and-answer turn.
is_answered"yes" or "no" — whether the documents held an answer.
follow_upSuggested 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.summariesPer source document: its summary and its extracted fields.
data.knowledge.detailed_chunksThe sections read to answer.
usageTokens used by this answer.
errorSet 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}/sessions lists them with title, 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.