Skip to main content
POST
cURL
Use POST /chat/query/ to ask a question. Send X-API-KEY in the header; the body must include query and user_id. To continue a conversation, pass back the chat_id from a previous response.

Request

  • user_id (required) — your identifier for the end-user. Each (API key, user_id) pair allows one concurrent request; a second in-flight request returns 429.
  • chat_id (optional) — UUID of the thread to continue. Omit to start a new thread; the server returns a fresh chat_id. A malformed UUID returns 400; a UUID you can’t access returns 409.
  • reasoning_level (optional) — low, medium (default), or high. Higher levels favor more thorough answers.
  • topic_names (optional) — list of knowledge topic names to scope retrieval to (e.g. ["Family A"]). Names are case-insensitive; an unknown name returns 400. Omit to let the agent choose.

Response

  • final_answer — the answer text.
  • chat_id — thread UUID; pass it back to continue the conversation.
  • chat_url — web link to view this thread.
  • conversation_id — integer ID for this specific turn. Use it to fetch the turn later via GET /chat/conversation/{conversation_id}/.
  • sources — evidence cited in the answer. Each entry has id, source_name, page, type, url, and display_name. Join a source’s id to citation tokens in final_answer (e.g. [0351-E1]).
  • tools — ordered list of tool calls the agent made, each with id, name, display_name, title, input, output, and status.

Streaming

Set Accept: text/event-stream to receive incremental output instead of a single JSON response. The stream opens with a start event, emits text, tool_call, tool_output, and todos (progress) events as the agent runs, and ends with a done event (whose payload matches the JSON response) or an error event.

Example Request

Continuing a thread

Example Response

Errors

  • 409chat_id belongs to a thread you can’t resume.
  • 429 — per-user (user_session_limit_exceeded) or org-wide (session_limit_exceeded) session limit reached. Use GET /chat/sessions/ to check usage.

Authorizations

x-api-key
string
header
required

Headers

Accept
enum<string>

Set to text/event-stream to opt into Server-Sent Events streaming. Any other value (or omitting the header) returns the standard JSON response.

Available options:
application/json,
text/event-stream

Body

application/json

Query payload for the Voltai agent.

Provide query and user_id. Topic scope is chosen automatically unless you pass topic_names. The agent decides its own reasoning depth — use reasoning_level to bias it.

query
string
required

The user's question.

user_id
string
required

Your application's identifier for the end-user making the request. Used for per-user session tracking and concurrency enforcement. Each (API key, user_id) pair is limited to one concurrent request.

Maximum string length: 255
chat_id
string<uuid>

Existing chat thread to continue. Must be a valid UUID. If it matches a chat in your organization, the new turn is appended; if the UUID is well-formed but not yet used, the server creates a new chat under that UUID (useful for client-side idempotency / correlation). Omit to let the server mint a fresh UUID. A UUID that already belongs to a chat the API key cannot resume returns 409.

reasoning_level
enum<string>
default:medium

Bias for how much intermediate reasoning the agent should do. low favors quick answers, high favors thorough multi-step reasoning. Unknown values fall back to medium.

Available options:
low,
medium,
high
topic_names
string[]

Optional. Names of knowledge topics to scope retrieval to. Each must match a topic in your organization (case-insensitive). If omitted or empty, topic scope is chosen automatically. If any name does not match a topic, the request returns 400.

topic_name
string
deprecated

Deprecated singular alias for topic_names. When topic_names is omitted, topic_name (if present) is wrapped into a one-element list. Prefer topic_names for new integrations.

Response

Agent response. Returned as a single JSON object by default, or as a Server-Sent Events stream when the request includes Accept: text/event-stream.

Agent response.

final_answer
string
required

Cleaned answer text returned by the agent. Internal markup (<answer>, <ref>, <abbr>, citation tokens) is stripped.

thinking
string
required

Aggregated reasoning string from the legacy multi-agent orchestrator: per-agent entries are concatenated in execution order, each prefixed by a header line and separated by a blank line. Empty under the current agent pipeline — use tools and content to inspect the reasoning trail instead.

chat_id
string<uuid>
required

Thread identifier: the Chat UUID for this conversation. Reuse this value in subsequent requests to continue the same thread.

chat_url
string<uri>
required

Web UI link to this thread: https://voltai.ai/{organization_name}/chat/{chat_id} using the resolved organization's name.

conversation_id
integer
required

Identifier of the specific question/answer turn within the thread. A new conversation_id is generated for every /chat/query/ request. Use it with GET /chat/conversation/{conversation_id}/ to fetch this exact turn later.

sources
object[]
required

Evidence cited by the agent. Each entry is annotated with the tool that surfaced it (display_name) and a stable id for joining back to citation tokens in final_answer.

tools
object[]
required

Every tool call the agent made while answering this turn, in execution order. Lets non-streaming clients see the same reasoning trail that SSE clients receive as live tool_call / tool_output frames.

content
object[]
required

Raw agent transcript for the turn: an ordered list of text and tool items as the agent produced them. text items concatenate to final_answer; tool items mirror the entries in tools.

Text fragment emitted by the agent (main agent or a subagent). Concatenate all main-agent text items in order to reconstruct the agent's prose.