NAnace
tools

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.

Args: body: The uploaded file's path, and optionally one component name to scope the response to. workspace: Resolved workspace and caller access predicate. A non-existent workspace returns workspace_not_found before the body executes. session: Database session.

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

Request

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

Idempotency-Keystring nullable

Replaying a request with the same key returns the original job with 200, never a second job. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

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.

componentstring nullable

Describe only this section or tab, named exactly as an unscoped call lists it.

Response

Successful Response

pathstring required

The uploaded file's path relative to the workspace root, as requested.

file_idstring uuid required

The uploaded file's id, as the files endpoints address it.

kindstring nullable

Ingestion lane (document / table / media), when known.

ingestion_status'discovered' | 'queued' | 'ingesting' | 'ingested' | 'stale' | 'expired' | 'failed' | 'not_required' required

The only thing that says whether a file is searchable.

expired cannot be derived from the hash pair: retention clears ingested_hash, so an aged-out file and a never-ingested file look identical. They call for different customer actions, so the status carries the distinction the hashes cannot.

ingestion_errorstring nullable

Why ingestion failed, when the ledger recorded a reason.

size_bytesinteger required

Byte size of the uploaded source object.

categorystring nullable

The file's primary category path, when classified.

page_countinteger nullable

Pages in a paged document; absent for other files.

tab_countinteger nullable

Tabs in a workbook; absent for other files.

summarystring

Summary of the file's first section or tab; each component has its own.

job_idstring uuid nullable

The external operation job; absent for commands inside a search job.

Changes

No recorded changes to this operation across all 1 revision of this API.