Ask

POST /api/v1/ask supports grounded QA over one document or multiple uploaded files. Use it when reviewers need one answer across a packet or document set.

For multi-document conversations, the first response includes session_id. Send that session_id back with the same ordered inputs on follow-up questions to reuse the prepared parse and vector index instead of preparing the same documents again.

cURL

curl -sS -X POST "https://api.docspeed.ai/api/v1/ask" \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"file_id": "file_invoice_april"},
      {"file_id": "file_invoice_may"}
    ],
    "execution_mode": "sync",
    "query": "Which supplier billed the higher total amount?",
    "include_grounding": true
  }'

Python

import requests

response = requests.post(
    "https://api.docspeed.ai/api/v1/ask",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "inputs": [
            {"file_id": "file_invoice_april"},
            {"file_id": "file_invoice_may"},
        ],
        "execution_mode": "sync",
        "query": "Which supplier billed the higher total amount?",
        "include_grounding": True,
    },
    timeout=300,
)
print(response.json())

TypeScript

const response = await fetch("https://api.docspeed.ai/api/v1/ask", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inputs: [
      { file_id: "file_invoice_april" },
      { file_id: "file_invoice_may" },
    ],
    execution_mode: "sync",
    query: "Which supplier billed the higher total amount?",
    include_grounding: true,
  }),
});

console.log(await response.json());

Follow-up questions

{
  "inputs": [
    {"file_id": "file_invoice_april"},
    {"file_id": "file_invoice_may"}
  ],
  "session_id": "session_id_abc123",
  "execution_mode": "sync",
  "query": "What changed month over month?",
  "include_grounding": true
}

Example response

{
  "answer": "April GST Invoice has the higher total amount.",
  "citations": [
    {
      "doc_id": "file_invoice_april",
      "regions": [
        {
          "page_index": 0,
          "page_width": 1653,
          "page_height": 2500,
          "bbox": {"x": 680, "y": 920, "width": 260, "height": 48}
        }
      ]
    }
  ],
  "doc_ids": ["file_invoice_april", "file_invoice_may"],
  "session_id": "session_id_abc123"
}