file_metadata

Describe one uploaded file without opening it: what it is, its category, and the parts you can ask about.

Cost class: fast.

path is the file's full path relative to the workspace root, exactly as it was uploaded and as folder-metadata, GET .../files and search results (source_path) print it — for example evidence/doc-7f83/contract.pdf. A bare file name (contract.pdf), a folder, a file id, or a path that starts with the workspace id is not found. file_not_found is final for that value: do not retry it or guess variants — list the folder with folder-metadata (name_contains= a part of the name) and use the path it prints.

The response gives the file's category, a summary of its first section or tab, page or tab counts, and its components: each section, tab, image or recording with its own summary, categories, page range or table shape, and key_terms — keywords whose role the source states (who a name is, what a date marks). A recording reports its duration. 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 to it.

component narrows this response to one section or tab by name; a name that matches nothing is refused with invalid_request listing the valid names. A file that is not ingested yet answers 200 with its ingestion_status and no components; a failed one carries ingestion_error.