Workspaces
Describe a folder
Other errors (500, 502, 503, 504) are on Errors.
Other errors (500, 502, 503, 504) are on Errors.
Authorization
bearerAuth Your API key, sent as Authorization: Bearer nace_sk_...
- Where: the dashboard's API Keys page. It is shown once, when you create it.
- Format:
nace_sk_followed by 43 URL-safe characters (A-Z,a-z,0-9,_and-). - Limit: an account can hold at most 3 active keys.
- Wrong or missing key: returns
401 authentication_error.
In: header
Path Parameters
The workspace's workspace_id.
Header Parameters
Up to 200 characters, unique per account. A call that timed out keeps running: send it again with the same key and body to get its answer instead of running it twice.
length <= 200Request Body
application/json
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.
length <= 1024"/"Describe the folder's whole subtree instead of its own files only. A narrow implies true unless sent.
falseOmit to include every file. Use a name exactly as a previous response's categories[].name printed it, e.g. minutes/meeting_minutes.
nullShow variants
Only files in this ingestion status — e.g. failed to list what did not ingest.
null"discovered""queued""ingesting""ingested""stale""expired""failed""not_required"Show variants
Only files of this kind: document (paged or prose), table, or media.
null"document""table""media""json"Show variants
Only files whose path contains this text, case-insensitively — how to find a file you know by name. % and _ match literally.
1 <= length <= 256nullShow variants
File entries per page. The counts always cover the whole scope.
1 <= value <= 500100Resume the file listing strictly after this path: the last file_entries path of the previous page.
length <= 1024nullShow variants
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/workspaces/string/tools/folder-metadata" \ -H "Content-Type: application/json" \ -d '{ "directory": "invoices", "recursive": true, "kind": "document" }'{ "directory": "string", "overall_files": 0, "categories": [ {} ], "subdirectories": [ {} ], "ingestion_summary": {}, "files_truncated": true, "file_entries": [ {} ], "hint": "string", "coverage": {}, "job_id": "string"}