NAnace
tools

folder_metadata

Changed on

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.

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

Request

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

Idempotency-Keystring nullable

Use the same key to recover an earlier request. A replay returned as a Job carries Idempotent-Replayed: true and replayed: true without a new charge; Job credits keeps the original cost. Re-serving a settled inline tool answer reports zero credits for that call and also carries Idempotent-Replayed: true; a fresh re-execution after a transient failure carries no header. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

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.

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.

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.

recursiveboolean

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

start_afterstring nullable

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

Response

Successful Response

creditsinteger nullable

Credits billed for this call; zero for a free answer or replay, null when a billing receipt is unavailable.

directorystring required

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

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.

ingestion_summaryobject required

File counts per ingestion status across the scope.

job_idstring uuid nullable

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

overall_filesinteger required

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

waiver'repeat_of_job' | 'no_job' nullable

Why this call is free: repeat_of_job reuses an earlier answer; no_job answers without creating a job.

Changes

  • d002a3589a67Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status