List Tree

Lists the complete file and directory tree recursively from metadata storage.

Unlike /api/list/files and /api/list/dirs, this endpoint does not inspect the physical storage directly.

Instead, the endpoint returns metadata entries stored in the ftpGrid metadata database. This makes the endpoint significantly faster for large directory structures, while also returning additional metadata such as checksums, protocol source and timestamps.

The endpoint is eventually consistent.

Required Scope

file.list

Endpoint

POST /api/list/tree

Example Request (HTTPie)

http POST https://webN.ftpgrid.com/api/list/tree \
    Authorization:"Bearer YOUR_TOKEN" \
    Params="/documents"

Raw JSON Body

{
    "Params": "/documents"
}

Request Parameters

Parameter	Type	Description
Params	string	Root path where recursive metadata listing should start

If Params is omitted it will default to root /.

Example Response

[
    {
        "checksum": "",
        "created_at": 1778917919299,
        "is_dir": true,
        "mtime": 1778917919276,
        "path": "/documents",
        "protocol": "API",
        "size": 0,
        "updated_at": null
    },
    {
        "checksum": "",
        "created_at": 1778917919343,
        "is_dir": true,
        "mtime": 1778917919319,
        "path": "/documents/projects",
        "protocol": "API",
        "size": 0,
        "updated_at": null
    },
    {
        "checksum": "3276eedceca35eb0a664761c58ce1be8293f32e0953ad1f4361f2096c3a3552e",
        "created_at": 1778904550670,
        "is_dir": false,
        "mtime": 1778904550410,
        "path": "/documents/projects/my file 1.txt",
        "protocol": "SFTP",
        "size": 271,
        "updated_at": null
    },
    {
        "checksum": "842a4a98ef8d6343274dd7d6ebf3561c76629c111198d179c160f1ddd74d87dd",
        "created_at": 1778819733775,
        "is_dir": false,
        "mtime": 1778819733676,
        "path": "/documents/projects/archive/report-final.pdf",
        "protocol": "FTP",
        "size": 355,
        "updated_at": 1778917450886
    }
]

Response Fields

Field	Type	Description
path	string	Full file or directory path
is_dir	boolean	Indicates whether the entry is a directory
checksum	string	SHA256 checksum for files, checksum is calcualated eventually
size	integer	File size in bytes
protocol	string	Protocol or source which created or modified the entry
mtime	integer	Last modified UNIX timestamp in milliseconds
created_at	integer	Creation UNIX timestamp in milliseconds
updated_at	integer/null	Last metadata update timestamp

Notes

• The endpoint is recursive
• The endpoint returns both files and directories
• Results are based on metadata storage, not direct filesystem inspection
• Metadata is eventually consistent
• The endpoint is typically much faster than traversing physical storage
• Full paths are always returned
• Object names are not returned separately
• Directories have is_dir=true and size 0
• Files include SHA256 checksums when available
• Paths are UNIX-style paths
• Paths may contain spaces and UTF-8 characters
• The root path / lists the complete metadata tree
• Very large storage structures may generate substantial response payloads