> ## Documentation Index > Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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=`` (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. ## OpenAPI ````yaml /openapi.json post /v1/workspaces/{workspace_id}/tools/qa-file openapi: 3.1.0 info: description: >- Document intelligence: parse, split, classify, extract, and ground files, or build a searchable workspace. Authenticate with ``X-API-Key``. title: NDI Platform API version: 0.1.0 servers: - url: https://ndi-api.nace.ai security: [] tags: [] paths: /v1/workspaces/{workspace_id}/tools/qa-file: post: tags: - tools summary: qa_file description: >- 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=`` (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. operationId: qa_file_v1_workspaces__workspace_id__tools_qa_file_post parameters: - description: Workspace identifier. in: path name: workspace_id required: true schema: description: Workspace identifier. format: uuid title: Workspace Id type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/QaFileRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/QaFileResponse' description: Successful Response '504': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Gateway Timeout default: content: application/json: example: error: code: invalid_request detail: null message: >- Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false schema: $ref: '#/components/schemas/ErrorEnvelope' description: >- Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. security: - APIKeyHeader: [] components: schemas: QaFileRequest: additionalProperties: false description: |- 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). properties: component: anyOf: - type: string - type: 'null' title: Component include_citations: default: true title: Include Citations type: boolean path: title: Path type: string query: maxLength: 4096 minLength: 1 title: Query type: string required: - path - query title: QaFileRequest type: object QaFileResponse: additionalProperties: false description: >- 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. properties: answer: title: Answer type: string citations: items: $ref: '#/components/schemas/Evidence' title: Citations type: array confidence: anyOf: - $ref: '#/components/schemas/ConfidenceLevel' - type: 'null' description: >- 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). engine: enum: - recursive_llm - vision - agent title: Engine type: string job_id: anyOf: - format: uuid type: string - type: 'null' title: Job Id timed_out: default: false title: Timed Out type: boolean unavailable: default: [] items: $ref: '#/components/schemas/UnavailableTable' title: Unavailable type: array required: - answer - citations - engine title: QaFileResponse type: object ErrorEnvelope: description: Every non-2xx body on ``/v1``. example: error: code: invalid_request detail: null message: Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false properties: error: $ref: '#/components/schemas/Error' required: - error title: ErrorEnvelope type: object Evidence: additionalProperties: false description: >- The citation primitive. Every result that asserts something about a document or the corpus carries it. A synthesised sentence with no evidence behind it is a bug, not a degraded mode. ``path`` is always the uploaded **source** path — that is what every external audience (``/v1`` bodies, the console, the search-agent result) is shown. The two ``exclude=True`` fields below are the host's internal twin of it, for the audience that must not see source paths at all (the agent's tools address ingestion derivatives); they are never serialized, so the ``/v1`` wire shape is exactly what it was before they existed. ``component`` closes the loop from a hit back to the file tools: it is the public component name of the hit — exactly the vocabulary ``file-metadata`` lists and ``qa-file`` / ``read-file`` accept as ``component=`` (the tab name for a spreadsheet, the section/subcategory for a split document). ``None`` means a single-component file or that attribution was unavailable. ``locator`` is present only when the producer actually located the snippet. ``None`` is not a degraded mode: an engine that answered from a whole component (the QA agent's quotes, the DuckDB agent's SQL receipts) asserts the file and ``component``, nothing finer. Pinning such a snippet to a region — a page bbox, a sheet cell range — is a separate ``ground`` call on ``path`` with ``snippet`` as the target text (and ``component`` as the ``sheet`` hint when the file is a spreadsheet). properties: component: anyOf: - type: string - type: 'null' description: >- Public component of the hit, in the vocabulary file-metadata lists and qa-file/read-file accept as component= (tab name for spreadsheets, section for split documents); None for a single-component file or when attribution is unavailable. title: Component file_id: format: uuid title: File Id type: string locator: anyOf: - discriminator: mapping: audio_range: $ref: '#/components/schemas/AudioRange' json_pointer: $ref: '#/components/schemas/JsonPointer' jsonl_record: $ref: '#/components/schemas/JsonlRecord' row_range: $ref: '#/components/schemas/RowRange' spreadsheet_range: $ref: '#/components/schemas/SpreadsheetRange' text_range: $ref: '#/components/schemas/TextRange' visual_region: $ref: '#/components/schemas/VisualRegion' propertyName: kind oneOf: - $ref: '#/components/schemas/TextRange' - $ref: '#/components/schemas/VisualRegion' - $ref: '#/components/schemas/SpreadsheetRange' - $ref: '#/components/schemas/JsonlRecord' - $ref: '#/components/schemas/JsonPointer' - $ref: '#/components/schemas/AudioRange' - $ref: '#/components/schemas/RowRange' - type: 'null' description: >- Where the snippet sits, when the producer located it. None means the citation is component-level: ground the snippet against path (sheet=component for spreadsheets) to place it. title: Locator page: anyOf: - type: integer - type: 'null' description: >- The 1-based page the producer attributed the snippet to when it produced no locator; None when unknown or when the locator already carries the page. title: Page path: title: Path type: string relevance_score: title: Relevance Score type: number snippet: title: Snippet type: string why: description: Which retrieval leg matched, or which graph path led here. title: Why type: string required: - file_id - path - relevance_score - snippet - why title: Evidence type: object ConfidenceLevel: description: How well the retrieved evidence supports the answer, worst-case wins. enum: - certain - very_high - high - medium - low - speculative title: ConfidenceLevel type: string UnavailableTable: additionalProperties: false description: >- A requested path (or one of its ingested sheets) that could not be queried. ``error_kind`` is ``None`` only when the failure happened before ingest could even classify it (an access or resolution error, which raises as a typed HTTP error instead of reaching this list). Lives here rather than beside the tool responses because a stored job result reports the same unusable inputs the synchronous response did — one definition, so a reopened run cannot describe them differently. properties: error: title: Error type: string error_kind: anyOf: - enum: - conversion_rejected - conversion_failed - profile_rejected - profile_failed type: string - type: 'null' title: Error Kind path: title: Path type: string required: - path - error title: UnavailableTable type: object Error: description: The error object, per spec 12 §1.8. properties: code: $ref: '#/components/schemas/ErrorCode' detail: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured payload, when the code carries one. title: Detail message: description: Human- and model-readable; says what to do differently. title: Message type: string request_id: description: Per-request correlation id; matches the ``X-Request-Id`` header. title: Request Id type: string retryable: description: Whether retrying the identical request could succeed. title: Retryable type: boolean required: - code - message - retryable - request_id title: Error type: object AudioRange: additionalProperties: false properties: end_ms: title: End Ms type: integer kind: const: audio_range default: audio_range title: Kind type: string start_ms: title: Start Ms type: integer required: - start_ms - end_ms title: AudioRange type: object JsonPointer: additionalProperties: false description: An RFC 6901 pointer into a JSON source; an empty string means the root. properties: kind: const: json_pointer default: json_pointer title: Kind type: string pointer: pattern: ^(?:$|/) title: Pointer type: string required: - pointer title: JsonPointer type: object JsonlRecord: additionalProperties: false properties: column: anyOf: - type: string - type: 'null' title: Column kind: const: jsonl_record default: jsonl_record title: Kind type: string row_offset: title: Row Offset type: integer required: - row_offset title: JsonlRecord type: object RowRange: additionalProperties: false description: A 0-based inclusive row run on a parquet table. properties: column: anyOf: - type: string - type: 'null' title: Column end_row: minimum: 0 title: End Row type: integer kind: const: row_range default: row_range title: Kind type: string start_row: minimum: 0 title: Start Row type: integer required: - start_row - end_row title: RowRange type: object SpreadsheetRange: additionalProperties: false properties: a1_range: title: A1 Range type: string kind: const: spreadsheet_range default: spreadsheet_range title: Kind type: string sheet: title: Sheet type: string required: - sheet - a1_range title: SpreadsheetRange type: object TextRange: additionalProperties: false description: >- A character span in a derivative's text, with the page(s) it falls on. ``pages`` is every page the span overlaps — a chunk that straddles a page marker belongs to both, and a reader handed only the first would miss the part of the span that carries the match. ``page`` is the first of them, kept because most producers and consumers only ever deal in one page. properties: char_end: title: Char End type: integer char_start: title: Char Start type: integer kind: const: text_range default: text_range title: Kind type: string page: anyOf: - type: integer - type: 'null' title: Page pages: items: type: integer title: Pages type: array required: - char_start - char_end title: TextRange type: object VisualRegion: additionalProperties: false properties: bbox: maxItems: 4 minItems: 4 prefixItems: - type: number - type: number - type: number - type: number title: Bbox type: array kind: const: visual_region default: visual_region title: Kind type: string page: title: Page type: integer required: - page - bbox title: VisualRegion type: object ErrorCode: description: |- Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. enum: - invalid_request - unsupported_file_type - file_too_large - invalid_schema - invalid_sql - invalid_path_prefix - command_not_permitted - batch_too_large - domain_validation_failed - default_label_required - wait_required_for_zero_retention - workspace_not_found - file_not_found - job_not_found - upload_not_found - node_not_found - schema_not_found - domain_not_found - session_not_found - access_label_not_found - path_conflict - schema_version_conflict - access_label_name_taken - workspace_name_taken - access_label_in_use - upload_expired - file_not_ingested - workspace_deleting - workspace_not_deletable - ingestion_in_progress - job_not_cancellable - confirmation_required - domain_not_published - domain_in_use - reserved_domain_slug - kg_not_built - kg_build_in_progress - session_busy - range_not_satisfiable - result_expired - access_denied - access_backstop_violation - access_mode_not_implemented - rate_limited - concurrency_limit_reached - quota_exceeded - corrupt_file - zero_byte_file - encrypted_file - parse_failed - ocr_failed - conversion_failed - sheetless_workbook - unplayable_media - unclassified_pages - job_cancelled - job_timeout - upstream_unavailable - internal_error - unauthorized - not_implemented title: ErrorCode type: string securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ````