tools

qa_file

Changed on Nov 7, 2026

Answer a natural-language question about one uploaded file — document, media, image, or table.

Cost class: slow.

path names an uploaded source file — the same full path file_metadata takes, exactly as folder_metadata lists it; a bare file name is not found, and a workspace-internal path is refused with invalid_request.

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 workbook with several tabs, a recording with attachments) or with rows (a spreadsheet tab, a csv/parquet/jsonl upload, a pdf's long table) is worked by a QA agent that searches within the file, reads the relevant parts, and writes its own SQL over the file's tables. 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.

Execution survives HTTP disconnects. By default the route waits and returns the original answer shape. Send Prefer: respond-async to return a Job immediately, then poll its Location URL. Idempotency-Key recovers the same job after a lost response. Only explicit job cancellation stops it.

post/v1/workspaces/{workspace_id}/tools/qa-file

Request

Base URL
https://ndi-api.nace.ai
Auth
API key in header X-API-Key
TypeScript
https://skmtc.dev/nace/apis/ndi-platform-api/docs/v1/workspaces/:workspace_id/tools/qa-file/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

preferstring nullable

Idempotency-Keystring nullable

Use the same key to recover an earlier request. A replay returned as a Job carries Idempotent-Replayed: true and replayed: true without a new charge; Job credits keeps the original cost. Re-serving a settled inline tool answer reports zero credits for that call and also carries Idempotent-Replayed: true; a fresh re-execution after a transient failure carries no header. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

componentstring nullable

include_citationsboolean

output_schemaobject nullable

A JSON Schema (Draft 2020-12, object root, local non-recursive $ref only, no pattern, patternProperties or unevaluated*) the answer must follow. When set, the agent writes answer as JSON text conforming to it, the run checks that and asks the agent to correct a mismatch, and the result carries the parsed value in structured_answer. A field the source does not state comes back null, whatever type the schema gives it. Explanation goes to reasoning where the result has one, and evidences are unchanged. If the answer still misses the schema, the run succeeds with answer as written and structured_answer null. Omit for a prose answer.

pathstring required

The uploaded file's full path relative to the workspace root, exactly as it was uploaded and as listings and search results print it — e.g. evidence/doc-7f83/contract.pdf. Not a bare file name (a file's file_name), a folder, a file id, or a path that starts with the workspace id.

querystring required

Response

Successful Response

Changes

Nov 7, 2026d002a3589a67 Revision changes
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status

Operation history