These tools read ingested workspace files. Ingest a file before you use them.
A typical agent loop:
- Find the file. Folder metadata lists a folder and
finds files by name. Search results also name files (
source_path).
- See what is inside. File metadata describes one file:
its category, a summary, and its sections or tabs with their own summaries
and key terms.
- Ask. QA file answers a question about one file;
query tables computes across spreadsheets.
File paths
Folder metadata, file metadata, QA file and query tables name a file by its
path: the full path relative to the workspace root, exactly as the file was
uploaded. It is the same string these return:
file_entries[].path from folder metadataitems[].path from GET /v1/workspaces/{workspace_id}/filessource_path on every search evidence item
file_not_found is final for the path you sent. Retrying it, or guessing
variants of it, returns the same error. Find the real path first: call folder
metadata with name_contains set to a distinctive part of the file name, and
use the path it returns.
/ (the workspace root) and descend, or search the whole
workspace by name.
directory is relative to the workspace root. / is the root;
evidence/doc-7f83 is a folder under it.- A call without narrows lists only the folder’s own files, plus a summary per
subfolder. Call again with a subfolder to descend.
name_contains, category, ingestion_status and kind narrow both the
counts and the listing, and search the whole subtree unless you send
"recursive": false. name_contains is case-insensitive, and it also finds
files whose ingestion failed.file_entries comes one page_size page at a time, sorted by path. When
files_truncated is true, call again with start_after set to the last
path you received.- A folder with no matches answers with a
hint naming the nearest existing
folder. A directory that names a file is refused with invalid_request:
use file metadata for it.
Describes one uploaded file without opening it: its category, a summary, and
the parts you can ask about. Pass the file’s path.
category and summary describe the file as a whole. summary is the
summary of the file’s first section or tab; each component has its own.components lists the file’s sections (documents), tabs (spreadsheets), an
image, or a recording. A recording reports duration_ms and
speaker_count.key_terms are up to six of a component’s extracted keywords whose role the
file states: who a name is, what a date or number marks. Files ingested
before key terms existed have none until they are re-ingested with
"reingest_unchanged": true.readable means QA file can answer from the component’s text.
queryable means it is a table query tables can
compute over. Pass a component’s name as component to scope either tool.- Send
"component": "<name>" to describe only that section or tab. An
unknown name is refused with invalid_request listing the valid names.
- A file that is not ingested yet answers with its
ingestion_status and no
components. A failed file carries ingestion_error.
When you hold a file id rather than a path, read the same context from the
files API: the file summary, keywords and their roles, and per-section or
per-sheet detail. The id comes from upload, the file listing, or
source_file_id on search evidence.
keywords remains a list of strings. Each entry in keyword_descriptions has
keyword and description; description is null when the source does not
establish the keyword’s role. Older ingests may have no descriptions. The same
fields appear for logical documents and spreadsheet sheets. native_metadata
contains properties supplied by the source file, such as a PDF creator.
QA file
Ask a natural-language question of one uploaded file: a document, a
workbook, an image, or a recording. For a question across several
spreadsheets, use query tables.
For a document, each citation is a verbatim passage the engine took from the
file. For a spreadsheet or CSV, the snippet is the matching rows as the engine
read them, written as JSON objects (one per row, keyed by column name), so it is
not text you can find byte for byte in the uploaded file. There may be several
citations, or none: an answer the engine assembled by searching the document
rather than reading one passage has nothing to quote, and says so by citing
nothing.
A citation carries a locator only when the engine located the passage as it
read. Otherwise locator is null and the citation names the file, not a span
inside it. To place one of those, pass its snippet to
ground against the same path.
QA file continues after an HTTP disconnect. Current Python and TypeScript SDKs
submit a durable job and poll it; qa_file still returns QaFileResponse, and
they accept direct answers from older servers. Omit Prefer and the request
waits for the original answer response; if your client’s own timeout fires
first, the run keeps going and its answer is kept on the job. For direct HTTP
integrations, send Prefer: respond-async with a stable Idempotency-Key: the
response is a Job (202 while pending, 200 when terminal) with a Location
header pointing to GET /v1/jobs/{job_id}. Retry a lost response with the same
key and body to recover the same job and its answer. POST /v1/jobs/{job_id}/cancel
stops a run and needs a JSON body: send {}, or {"reason": "..."} to record why.
DELETE /v1/jobs/{job_id} also cancels a queued or running job before hiding it.
Structured answers
Pass output_schema, a JSON Schema (or, in Python, a Pydantic model class),
to get the answer as JSON. Every engine honors it: the agent and the recursive
reader are checked and corrected, and a vision answer that misses the schema is
reshaped from what the model read. On success answer is the JSON text and
structured_answer the parsed value. A field the source does not state comes back null, whatever type the schema gives it.
If the answer still misses, the call still
succeeds and structured_answer is null. The schema root must be an object,
and pattern / patternProperties are refused (state a format in description),
as are a recursive $ref and unevaluatedProperties / unevaluatedItems.
Errors
file_not_ingested — ingest firstinvalid_request — qa_file on a derived output path, an unknown or ambiguous component, or a component with no content it can answer about