Local Folder

Required

Fields required for a valid configuration.

Path	Type	Required	Description	Default	Constraints
required	object	Yes	—	—	no extra properties
required.path	string	Yes	Absolute path of the local folder to scan (for example, /Users/jane/Documents)	—	—

Masked

Sensitive fields under(secrets/credentials).

Path	Type	Required	Description	Default	Constraints
masked	object	No	Local folder scans run with the desktop application's filesystem permissions; no credentials are required.	—	no extra properties

Optional

Optional configuration fields.

Path	Type	Required	Description	Default	Constraints
optional	object	No	—	—	no extra properties
optional.scope	object	No	Object scope and filtering controls.	—	no extra properties
optional.scope.exclude_extensions	array	No	Optional extension denylist	—	—
optional.scope.exclude_extensions[]	string	No	—	—	—
optional.scope.include_content_preview	boolean	No	Download object bytes to infer MIME and extract detector-ready text previews	true	—
optional.scope.include_empty_objects	boolean	No	Include zero-byte objects in extraction results	false	—
optional.scope.include_extensions	array	No	Optional extension allowlist (for example, .pdf, .csv, .parquet)	—	—
optional.scope.include_extensions[]	string	No	—	—	—
optional.scope.include_object_metadata	boolean	No	Attach provider metadata (etag, size, content-type hints, timestamps) to asset checksums	true	—
optional.scope.prefix	string	No	Object key prefix filter (for example, exports/2026/)	—	—
optional.traversal	object	No	Directory traversal controls.	—	no extra properties
optional.traversal.follow_symlinks	boolean	No	Follow symbolic links while traversing (loops are not detected; leave off unless needed)	false	—
optional.traversal.include_hidden	boolean	No	Include hidden files and dot-directories (names starting with a dot)	false	—
optional.traversal.max_depth	integer	No	Maximum directory depth below the selected folder (unset scans all levels)	—	min 1, max 64
optional.traversal.max_file_bytes	integer	No	Maximum bytes read per file for MIME detection and text extraction	10485760	min 1024, max 104857600

Extracted Metadata

File

Field	Type	Required	Description
size_bytes	integer	Yes	Raw byte size of the content
mime_type	string	Yes	Resolved MIME type
parse_error	string	No	Set when content extraction failed
image_width	integer	No	Width in pixels
image_height	integer	No	Height in pixels
page_count	integer	No	Number of pages (pdf)
paragraph_count	integer	No	Number of paragraphs (docx)
table_count	integer	No	Number of tables (docx)
row_count	integer	No	Number of data rows
columns	object[]	No	Columns as {name, type} objects (type may be empty for csv/xlsx)
encoding	string	No	Detected character encoding
json_root_type	string	No	Root JSON type: object, array, or scalar
top_level_keys	integer	No	Number of top-level keys when the root is an object
array_length	integer	No	Length when the root is an array
provider	string	Yes	Storage provider label
object_key	string	Yes	File path relative to the scanned folder
etag	string	No	Change signature derived from file size and modification time

Image

Field	Type	Required	Description
size_bytes	integer	Yes	Raw byte size of the content
mime_type	string	Yes	Resolved MIME type
parse_error	string	No	Set when content extraction failed
provider	string	No	Storage provider label
object_key	string	No	File path relative to the scanned folder
etag	string	No	Change signature derived from file size and modification time
source_hash	string	No	Hash of the parent file asset (embedded images only)
location	string	No	Location of the embedded image within the parent (embedded images only)

Audio

Field	Type	Required	Description
size_bytes	integer	Yes	Raw byte size of the content
mime_type	string	Yes	Resolved MIME type
parse_error	string	No	Set when content extraction failed
provider	string	Yes	Storage provider label
object_key	string	Yes	File path relative to the scanned folder
etag	string	No	Change signature derived from file size and modification time

Video

Field	Type	Required	Description
size_bytes	integer	Yes	Raw byte size of the content
mime_type	string	Yes	Resolved MIME type
parse_error	string	No	Set when content extraction failed
provider	string	Yes	Storage provider label
object_key	string	Yes	File path relative to the scanned folder
etag	string	No	Change signature derived from file size and modification time

Examples

Documents folder scan

Scan a local folder on this computer for documents, spreadsheets, and images (desktop app only)

Config Payload

{
  "type": "LOCAL_FOLDER",
  "required": {
    "path": "/Users/you/Documents"
  },
  "optional": {
    "scope": {
      "include_content_preview": true
    }
  },
  "sampling": {
    "strategy": "AUTOMATIC"
  }
}

Project folder scan with file-type filter

Scan a project folder restricted to office documents, skipping hidden files and very large files

Config Payload

{
  "type": "LOCAL_FOLDER",
  "required": {
    "path": "/Users/you/Projects/reports"
  },
  "optional": {
    "traversal": {
      "include_hidden": false,
      "max_depth": 10,
      "max_file_bytes": 10485760
    },
    "scope": {
      "include_extensions": [
        ".pdf",
        ".docx",
        ".xlsx",
        ".csv",
        ".txt"
      ],
      "include_content_preview": true
    }
  },
  "sampling": {
    "strategy": "ALL"
  },
  "detectors": [
    {
      "type": "PII",
      "enabled": true
    },
    {
      "type": "SECRETS",
      "enabled": true
    }
  ]
}