NAnace
tools

folder_metadata

List one folder of the workspace: file counts, categories, subfolders, and the files' exact paths.

Cost class: fast.

Explore in steps instead of listing everything at once:

  1. Call with the defaults on / (the workspace root): the folder's own files plus one summary per subfolder (file count, top categories, failed-ingestion count).
  2. Descend with directory=<folder>, or narrow with name_contains= (find a file by part of its name), category=, ingestion_status= (e.g. failed) or kind=. Counts and listing narrow together, and a narrow covers the whole subtree unless recursive=false is sent.
  3. Pass a file_entries[].path to file-metadata to see what is inside that file, then ask with qa-file or query-tables.

Every path is relative to the workspace root and never includes the workspace id. name_contains finds files by what they are called — files whose ingestion failed included; the search tools find them by what they contain.

A directory that names a file is refused with invalid_request pointing at file-metadata. An unfiltered call that matches nothing answers with a hint naming the nearest existing folder and what it holds, so a mistyped folder is not a dead end.

file_entries comes one page_size page at a time, sorted by path; files_truncated reports a cut — resume with start_after=<last path> or narrow. Counts and listing only include files the caller's access labels allow; coverage says how many were withheld.

Args: body: Folder, recursion flag, the narrows (category, ingestion_status, kind, name_contains), page size, cursor. 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/folder-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

directorystring

Folder to describe, relative to the workspace root: / (the default) is the root, evidence/2025 a folder under it. Never prefix it with the workspace id.

recursiveboolean

Describe the folder's whole subtree instead of its own files only. A narrow implies true unless sent.

categorystring nullable

Omit to include every file. Use a name exactly as a previous response's categories[].name printed it, e.g. minutes/meeting_minutes.

ingestion_status'discovered' | 'queued' | 'ingesting' | 'ingested' | 'stale' | 'expired' | 'failed' | 'not_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.

kind'document' | 'table' | 'media' | 'json'

The processing lane a file routes through — exactly one per file.

DOCUMENT covers everything the categorize pipeline can split into logical documents (PDF, Office, Visio diagrams, images, text, markdown, HTML, email); TABLE covers spreadsheets and CSV; MEDIA covers audio and video, which become one speaker-attributed timeline plus sampled frames; JSON preserves arbitrary nested structure and may add a table projection for a top-level record array.

name_containsstring nullable

Only files whose path contains this text, case-insensitively — how to find a file you know by name. % and _ match literally.

page_sizeinteger

File entries per page. The counts always cover the whole scope.

start_afterstring nullable

Resume the file listing strictly after this path: the last file_entries path of the previous page.

Response

Successful Response

directorystring required

The folder described, relative to the workspace root (/ is the root).

overall_filesinteger required

Files in scope that the caller can see: the folder, or its subtree when recursive.

ingestion_summaryobject required

File counts per ingestion status across the scope.

files_truncatedboolean required

True when file_entries is one page of a longer listing; resume with start_after.

hintstring nullable

Present only when a call matched nothing: unfiltered, the nearest existing folder and what it holds; filtered, how many files the folder holds and their categories.

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.