Ask a question of your documents
const url = 'http://localhost:11044/api/v1/documents/ask';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"answer":true,"history":["example"],"intent":"example","maxSnippet":1,"minScore":1,"question":"example","tag":"example","topK":1,"uri":"example","window":{"field":"example","from":"example","to":"example"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/documents/ask \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "answer": true, "history": [ "example" ], "intent": "example", "maxSnippet": 1, "minScore": 1, "question": "example", "tag": "example", "topK": 1, "uri": "example", "window": { "field": "example", "from": "example", "to": "example" } }'Agentic retrieval over the caller’s documents, answered in prose with verified citations. An optional window object bounds the search by date: window.field is modified (default), created, or ingested, with window.from inclusive and window.to exclusive. topK defaults to 6 (clamped to 1..25); answer=false skips the composition call and returns sources only; history carries prior turns as Q:/A: lines.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”The question to answer from the caller’s own documents, and how to search for them. question must not be blank (400). window, tag and uri narrow which documents are searched, and a uri the caller’s world does not hold is 404. topK defaults to 6 and is clamped to 1..25; maxSnippet raises the per-passage cap from its 400-character default, up to 8000; minScore (default 0.25) applies only when answer is false. answer=false skips composing an answer and returns ranked sources only. history carries prior turns, oldest first, of which the last six reach the prompt
Body of POST /documents/ask: a question for the caller’s own documents, and what narrows the search.
object
False to skip composing an answer and return sources only, from a deterministic search with no language-model call. Defaults to true.
Prior turns, oldest first, each a Q: line followed by an A: line, so a follow-up needs no session. Only the last 6 are used, and only when an answer is composed.
A brief for the retrieval’s judgement. Accepted, but not currently read by either retrieval path.
Cap on each returned passage, in characters. Defaults to 400 and is clamped to 400..8000; raise it to get whole chunks back, as span-scored retrieval evaluation needs.
Lowest similarity score, 0 to 1, a chunk must reach to count. Read on the sources-only path (answer false) only, where it defaults to 0.25.
The question to answer, or on the sources-only path the text to search for. A blank question is answered 400.
Narrow to documents carrying this tag, whether or not an answer is composed.
Most documents to return. Defaults to 6; clamped to 1..25.
Narrow to the one document at this uri, as GET /documents lists it, whether or not an answer is composed. A uri the caller’s world does not hold is answered 404.
Bounds the search by one of the document’s dates. Absent means no date bound.
object
Which date to bound: modified (the default, the document’s own last-changed date), created, or ingested. An unrecognised value applies no date bound.
Inclusive lower bound, as a date (2026-01-01) or an ISO-8601 instant.
Exclusive upper bound, in the same forms as from.
Example generated
{ "answer": true, "history": [ "example" ], "intent": "example", "maxSnippet": 1, "minScore": 1, "question": "example", "tag": "example", "topK": 1, "uri": "example", "window": { "field": "example", "from": "example", "to": "example" }}Responses
Section titled “Responses”An answer, its sources, or both
What POST /documents/ask answers: the composed answer, the documents it came from, and what constrained the search.
object
The composed answer alone, without the passages the model quoted before it. Null when answer was false, when nothing was retrieved, and on a 400 or 404.
What constrained the search, echoed back: dateField, from, to, tag and uri when given, and topK; then the effort behind it: documents (also as retrieved), chunks and searches. On a 400 or 404, only error, with the reason.
object
The model this endpoint composes answers with (the world’s agentic-RAG role, not the chat model). Reported even when no answer was composed; null on a 400 or 404.
Why there is no answer, set only when the model was asked to answer and returned no text. Null otherwise, including when nothing matched.
Exactly what the model composed, quoted passages and all, before the server split out answer. Null when no answer was composed.
The documents retrieved, in retrieval order, numbered by n. Empty when nothing matched.
One document a POST /documents/ask retrieved, with the passages read from it.
object
True on every source of a composed answer: each is a document the answering model was observed to retrieve. False when answer was false.
The document’s modified, created and ingested dates.
object
When the document itself was created, as an ISO-8601 instant. Null when unknown.
When this appliance ingested the document, as an ISO-8601 instant. Null when unknown.
When the document itself last changed, as an ISO-8601 instant. Null when unknown.
Citation number, from 1 in retrieval order: the [n] an answer cites this document by.
Verbatim text of the chunks of this document that retrieval read, best first, each cut to maxSnippet characters, with the provenance lines added at ingest removed.
Relevance of the document’s best-matching chunk, normally 0 to 1. Vector and full-text scores are not calibrated against each other, so n gives the order, not this.
The heading the first passage sits under, by the id GET /documents/outline lists it with, so a reader can open the document there. Null when the passage does not say.
The document’s title. ? or null when the matched chunk did not record one.
The document’s uri, as GET /documents lists it. Empty or null when the matched chunk did not record it.
Citation markers removed because they named no retrieved document. Currently always 0: sources are taken from the retrieval the server observed, not from markers in the answer.
Example generated
{ "answer": "example", "filters": { "additionalProperty": "example" }, "model": "example", "note": "example", "raw": "example", "sources": [ { "cited": true, "dates": { "createdAt": "example", "ingestedAt": "example", "modifiedAt": "example" }, "n": 1, "passages": [ "example" ], "score": 1, "sectionId": "example", "title": "example", "uri": "example" } ], "unresolvedCitations": 1}Blank question. The usual body, empty, with the reason under filters.error
What POST /documents/ask answers: the composed answer, the documents it came from, and what constrained the search.
object
The composed answer alone, without the passages the model quoted before it. Null when answer was false, when nothing was retrieved, and on a 400 or 404.
What constrained the search, echoed back: dateField, from, to, tag and uri when given, and topK; then the effort behind it: documents (also as retrieved), chunks and searches. On a 400 or 404, only error, with the reason.
object
The model this endpoint composes answers with (the world’s agentic-RAG role, not the chat model). Reported even when no answer was composed; null on a 400 or 404.
Why there is no answer, set only when the model was asked to answer and returned no text. Null otherwise, including when nothing matched.
Exactly what the model composed, quoted passages and all, before the server split out answer. Null when no answer was composed.
The documents retrieved, in retrieval order, numbered by n. Empty when nothing matched.
One document a POST /documents/ask retrieved, with the passages read from it.
object
True on every source of a composed answer: each is a document the answering model was observed to retrieve. False when answer was false.
The document’s modified, created and ingested dates.
object
When the document itself was created, as an ISO-8601 instant. Null when unknown.
When this appliance ingested the document, as an ISO-8601 instant. Null when unknown.
When the document itself last changed, as an ISO-8601 instant. Null when unknown.
Citation number, from 1 in retrieval order: the [n] an answer cites this document by.
Verbatim text of the chunks of this document that retrieval read, best first, each cut to maxSnippet characters, with the provenance lines added at ingest removed.
Relevance of the document’s best-matching chunk, normally 0 to 1. Vector and full-text scores are not calibrated against each other, so n gives the order, not this.
The heading the first passage sits under, by the id GET /documents/outline lists it with, so a reader can open the document there. Null when the passage does not say.
The document’s title. ? or null when the matched chunk did not record one.
The document’s uri, as GET /documents lists it. Empty or null when the matched chunk did not record it.
Citation markers removed because they named no retrieved document. Currently always 0: sources are taken from the retrieval the server observed, not from markers in the answer.
Example generated
{ "answer": "example", "filters": { "additionalProperty": "example" }, "model": "example", "note": "example", "raw": "example", "sources": [ { "cited": true, "dates": { "createdAt": "example", "ingestedAt": "example", "modifiedAt": "example" }, "n": 1, "passages": [ "example" ], "score": 1, "sectionId": "example", "title": "example", "uri": "example" } ], "unresolvedCitations": 1}The uri scope names no document in this world. The usual body, empty, with the reason under filters.error
What POST /documents/ask answers: the composed answer, the documents it came from, and what constrained the search.
object
The composed answer alone, without the passages the model quoted before it. Null when answer was false, when nothing was retrieved, and on a 400 or 404.
What constrained the search, echoed back: dateField, from, to, tag and uri when given, and topK; then the effort behind it: documents (also as retrieved), chunks and searches. On a 400 or 404, only error, with the reason.
object
The model this endpoint composes answers with (the world’s agentic-RAG role, not the chat model). Reported even when no answer was composed; null on a 400 or 404.
Why there is no answer, set only when the model was asked to answer and returned no text. Null otherwise, including when nothing matched.
Exactly what the model composed, quoted passages and all, before the server split out answer. Null when no answer was composed.
The documents retrieved, in retrieval order, numbered by n. Empty when nothing matched.
One document a POST /documents/ask retrieved, with the passages read from it.
object
True on every source of a composed answer: each is a document the answering model was observed to retrieve. False when answer was false.
The document’s modified, created and ingested dates.
object
When the document itself was created, as an ISO-8601 instant. Null when unknown.
When this appliance ingested the document, as an ISO-8601 instant. Null when unknown.
When the document itself last changed, as an ISO-8601 instant. Null when unknown.
Citation number, from 1 in retrieval order: the [n] an answer cites this document by.
Verbatim text of the chunks of this document that retrieval read, best first, each cut to maxSnippet characters, with the provenance lines added at ingest removed.
Relevance of the document’s best-matching chunk, normally 0 to 1. Vector and full-text scores are not calibrated against each other, so n gives the order, not this.
The heading the first passage sits under, by the id GET /documents/outline lists it with, so a reader can open the document there. Null when the passage does not say.
The document’s title. ? or null when the matched chunk did not record one.
The document’s uri, as GET /documents lists it. Empty or null when the matched chunk did not record it.
Citation markers removed because they named no retrieved document. Currently always 0: sources are taken from the retrieval the server observed, not from markers in the answer.
Example generated
{ "answer": "example", "filters": { "additionalProperty": "example" }, "model": "example", "note": "example", "raw": "example", "sources": [ { "cited": true, "dates": { "createdAt": "example", "ingestedAt": "example", "modifiedAt": "example" }, "n": 1, "passages": [ "example" ], "score": 1, "sectionId": "example", "title": "example", "uri": "example" } ], "unresolvedCitations": 1}