curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/tools/qa-file \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"path": "<string>",
"query": "<string>"
}
'{
"answer": "<string>",
"citations": [
{
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"path": "<string>",
"relevance_score": 123,
"snippet": "<string>",
"why": "<string>",
"component": "<string>",
"locator": {
"char_end": 123,
"char_start": 123,
"kind": "text_range",
"page": 123,
"pages": [
123
]
},
"page": 123
}
],
"engine": "recursive_llm",
"confidence": "certain",
"job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"timed_out": false,
"unavailable": []
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}qa_file
Answer a natural-language question about one uploaded document, media, or image file.
Cost class: slow.
path names an uploaded source file — the same addressing as
read_file; a workspace-internal path is refused with
invalid_request. So is a table file — a spreadsheet (xlsx, xls,
xlsm, xlsb, ods) or record file (csv, tsv, parquet, jsonl, ndjson, json):
questions about tables belong to query-tables, single file or
several, whatever each tab ingested with.
The engine is picked from what the file (or the selected component) is:
an image goes to vision QA, and text — of any length — to a recursive LLM
built for long documents. A file with several parts (a pdf split into
sections, a recording with attachments) is worked by a QA agent that
searches within the file and reads the relevant parts. The response’s
engine field reports which one ran.
Scope the question with component=<name> (the names file_metadata
lists) to ask about one section directly. Use this when you need a
direct, cited answer about a file’s contents rather than search hits.
curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/tools/qa-file \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"path": "<string>",
"query": "<string>"
}
'{
"answer": "<string>",
"citations": [
{
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"path": "<string>",
"relevance_score": 123,
"snippet": "<string>",
"why": "<string>",
"component": "<string>",
"locator": {
"char_end": 123,
"char_start": 123,
"kind": "text_range",
"page": 123,
"pages": [
123
]
},
"page": 123
}
],
"engine": "recursive_llm",
"confidence": "certain",
"job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"timed_out": false,
"unavailable": []
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}Authorizations
Path Parameters
Workspace identifier.
Body
Request body for qa-file.
path names an uploaded source file — the same addressing as
read-file; a workspace-internal derivative path is refused with
invalid_request, and so is a table file (spreadsheet or record
upload — ask those with query-tables). component scopes the
question to one public component by name (a pdf section — the names
file-metadata lists).
Response
Successful Response
Response body for qa-file.
engine reports what answered: recursive_llm for prose, vision
for an image, and agent when the file has several parts and a QA agent
worked across them. Citations always name the uploaded file, never
anything internal.
job_id is the durable job row created for this run; poll or retrieve
it via GET /v1/jobs/{job_id} to get the stored answer after the fact.
unavailable is always empty since table files moved to query-tables
(which reports unqueryable selections there); the field is retained for
wire compatibility.
Show child attributes
Show child attributes
recursive_llm, vision, agent The engine's self-graded confidence in the answer — how well the file content it read supports it, on the shared six-level scale (certain / very_high / high / medium / low / speculative). Null when the engine could not grade (a timeout's partial answer, a legacy run).
certain, very_high, high, medium, low, speculative Show child attributes
Show child attributes