qa_file

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.

Args: body: Source path, the natural-language question, whether to include citations, and the optional component scope. workspace: Resolved workspace and caller access predicate. A non-existent workspace returns workspace_not_found before the body executes. session: Database session. temporal: Temporal client, used to dispatch the durable qa-file job. response: The response, whose status and job headers the submission sets. prefer: respond-async returns the accepted job instead of waiting. idempotency_key: Recovers the same job after a lost response.