Playground ↗ Postman ↗ Dashboard ↗
POST /v2/documents/query

Query documents (RAG)

Runs retrieval-augmented question answering across a set of previously indexed documents. Pass either an explicit list of document_ids or a space_id to scope the search.

Request

Headers

HeaderRequiredNotes
X-API-Keyyes
X-External-User-Idyes (or X-User-Id)Must own the documents
Content-Typeyesapplication/json

Body

question string required
Natural-language question. 1–2000 characters.
document_ids string[]
Up to 20 document IDs from POST /v2/documents/process. Mutually exclusive with space_id.
space_id string
Query every document in this space. Mutually exclusive with document_ids.
top_k integer default 5
Number of source chunks to retrieve. Range 1–20.

Returns

{
  "answer": "The whitepaper recommends a per-tenant Qdrant collection so that customer data is physically isolated…",
  "sources": [
    {
      "document_id": "d_01HW0XYZ…",
      "filename": "whitepaper.pdf",
      "text": "We recommend running one Qdrant collection per tenant. This isolates…",
      "score": 0.81
    },
    {
      "document_id": "d_01HW0XYZ…",
      "filename": "whitepaper.pdf",
      "text": "Cross-tenant retrieval is rejected at the API layer…",
      "score": 0.74
    }
  ]
}

Provide exactly one of document_ids or space_id. Passing both, or neither, returns a 422.

Errors

  • 404 — One or more document_ids aren’t owned by this user.
  • 422 — Validation: empty question, both/neither of the scope params, top_k out of range.
  • 429 — Rate limit exceeded.