Chat Query

​

Request Notes

• user_id (required) — your application’s identifier for the end-user making the request. Each (API key, user_id) pair is limited to one concurrent request. If the same user already has a request in flight, the endpoint returns 429.
• chat_id (optional) — must be a valid UUID. Behavior:
  • Omitted → the server mints a fresh UUID and creates a new chat.
  • UUID matches an existing chat in your organization → the new turn is appended to that thread.
  • UUID is well-formed but not yet used → the server creates a new chat under that UUID. This lets clients pin their own thread IDs for idempotency or app-side correlation.
  • UUID already belongs to a chat you cannot resume (different org or soft-deleted) → 409.
  • UUID malformed → 400.
• reasoning_level controls how thorough the agent should be. Defaults to medium.
  • low — favor quick answers and minimal tool use.
  • medium — default.
  • high — favor thorough multi-step reasoning with more tool calls.
  Unknown values fall back to medium.
• mode is a legacy field kept for backwards compatibility. The current agent pipeline does not branch on it; whatever you send is echoed back unchanged on the response. Use reasoning_level instead.
• topic_names (optional) — list of knowledge topic names to scope retrieval to (e.g. ["Family A", "Family B"]). Each name must match a topic in your organization (case-insensitive). If omitted or [], topic scope is chosen automatically. If any name does not match a topic, the endpoint returns 400.
• topic_name (deprecated) — singular alias for topic_names. When topic_names is omitted, topic_name is wrapped into a one-element list. Prefer topic_names for new integrations.

​

Response Notes

• The endpoint returns a single JSON object, not an array.
• final_answer is the cleaned answer text. Internal markup (<answer>, <ref>, <abbr>, citation tokens) is stripped.
• chat_id is the chat thread UUID. Pass it back on subsequent requests to continue the conversation.
• chat_url is the web UI link for this thread: https://voltai.ai/{org_name}/chat/{chat_id}, where {org_name} is the resolved organization’s name.
• conversation_id is the integer identifier of this specific question/answer turn. A new conversation_id is returned for every /chat/query/ request, including follow-ups in the same chat_id. Use it to fetch the same turn later via GET /chat/conversation/{conversation_id}/.
• sources lists evidence cited by the agent. Each entry includes:
  • id — stable identifier; use it to join citation tokens that appear in final_answer (e.g. [0351-E1]) back to a specific source.
  • source_name — filename for library / PDF chunks; page or item title for web, fetched URLs, and connector sources (Slack, Jira, Confluence, Salesforce, SharePoint, Assembla); display label for part sources.
  • page — 1-indexed page number for paginated library sources; null otherwise.
  • type — source type tag (text, web, part, etc.).
  • url — link to view the source. May be null for sources without a canonical link.
  • display_name — human-readable label for the tool that surfaced the source (e.g. "Library Search", "Web Search", "Part Detail").
• tools is the ordered list of tool calls the agent made while answering — same data SSE clients receive as tool_call / tool_output frames. Each entry has id, name, display_name, title, input, output, status, and an optional subagent_instance_id.
• content is the raw transcript of the turn: an ordered list of text and tool items as the agent produced them. text items concatenate to final_answer; tool items mirror tools.
• thinking is retained for backwards compatibility with the legacy multi-agent orchestrator. Under the current agent pipeline it is always "" — use tools and content to inspect the reasoning trail.
• mode echoes whatever value you sent (or "AUTO" if omitted). It does not reflect any internal routing decision.

​

Concurrency & Sessions

​

Streaming with Server-Sent Events

​

Example Request

{
  "query": "What is EMEM?",
  "user_id": "usr_82af91",
  "reasoning_level": "medium"
}

​

Scoped to one or more topics (optional)

{
  "query": "What is the maximum operating temperature?",
  "user_id": "usr_82af91",
  "topic_names": ["Example Product Family"]
}

​

Follow-up Request (continuing a thread)

{
  "query": "What is the maximum operating temperature?",
  "user_id": "usr_82af91",
  "chat_id": "2d8a39d8-29d6-4f0f-bc5f-4c5f0f9c9d54"
}

​

Example Response

{
  "final_answer": "EMEM is embedded memory integrated into the device for storing code and data.",
  "thinking": "",
  "chat_id": "2d8a39d8-29d6-4f0f-bc5f-4c5f0f9c9d54",
  "chat_url": "https://voltai.ai/ExampleOrg/chat/2d8a39d8-29d6-4f0f-bc5f-4c5f0f9c9d54",
  "conversation_id": 184217,
  "sources": [
    {
      "id": "0351-E1",
      "source_name": "example-datasheet.pdf",
      "page": 12,
      "type": "text",
      "url": "https://voltai.ai/ExampleOrg/library?source_name=example-datasheet.pdf&source_type=text&source_page=12",
      "display_name": "Library Search"
    }
  ],
  "mode": "AUTO",
  "tools": [
    {
      "id": "call_8c2f",
      "name": "search_library",
      "display_name": "Library Search",
      "title": "Searching \"EMEM\" in Datasheets",
      "input": { "query": "EMEM", "topic_id": 17 },
      "output": "Found 3 matching chunks…",
      "status": "success",
      "subagent_instance_id": null
    }
  ],
  "content": [
    {
      "type": "tool",
      "id": "call_8c2f",
      "name": "search_library",
      "display_name": "Library Search",
      "title": "Searching \"EMEM\" in Datasheets",
      "input": { "query": "EMEM", "topic_id": 17 },
      "output": "Found 3 matching chunks…",
      "status": "success",
      "subagent_instance_id": null
    },
    {
      "type": "text",
      "text": "EMEM is embedded memory integrated into the device for storing code and data.",
      "subagent_instance_id": null
    }
  ]
}

​

Example SSE Stream

data: {"type":"start","chat_id":"2d8a…","chat_url":"https://voltai.ai/ExampleOrg/chat/2d8a…","conversation_id":184217}

data: {"type":"tool_call","msg":{"id":"call_8c2f","name":"search_library","display_name":"Library Search","title":"Searching \"EMEM\" in Datasheets","input":{"query":"EMEM"},"subagent_instance_id":null}}

data: {"type":"tool_output","msg":{"id":"call_8c2f","output":"Found 3 matching chunks…","status":"success"}}

data: {"type":"text","msg":{"delta":"EMEM is embedded memory","subagent_instance_id":null}}

data: {"type":"text","msg":{"delta":" integrated into the device.","subagent_instance_id":null}}

data: {"type":"done","final_answer":"EMEM is embedded memory integrated into the device.","thinking":"","chat_id":"2d8a…","chat_url":"https://voltai.ai/ExampleOrg/chat/2d8a…","conversation_id":184217,"sources":[...],"mode":"AUTO","tools":[...],"content":[...]}

​

409 — Chat ID conflict

{
  "detail": "chat_id is already in use."
}

​

429 — Per-User Limit

{
  "error": "user_session_limit_exceeded",
  "message": "user_id 'usr_82af91' already has an active request. Please wait for it to complete.",
  "user_id": "usr_82af91"
}

​

429 — Org-Level Limit

{
  "error": "session_limit_exceeded",
  "message": "You have exceeded the session quota limit for your organization. Please try again later.",
  "total_seats": 10,
  "active_seats": 10,
  "available_seats": 0
}