# Return directory content

This function returns a sorted list of files and directories.

Important:

When you disable the FileStorage role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Endpoint: GET /Fileman/list_files
Version: 11.137.9999.96
Security: BasicAuth

## Query parameters:

  - `dir` (string, required)
    The directory from which to list files.
    Example: "public_html"

  - `check_for_leaf_directories` (integer)
    Whether to return directories that contain subdirectories.

* 1 — Return subdirectories.
* 0 — Do not retain subdirectories.
    Enum: 0, 1

  - `include_mime` (integer)
    Whether to return the file's MIME type.

* 1 — Include MIME type.
* 0 — Do not include MIME type.

Note:

 If you set this value to 0 but also include the mime_types or raw_mime_types parameters, the function overrides your specified value and sets this parameter to 1.
    Enum: 0, 1

  - `include_permissions` (integer)
    Whether to parse the file owner's read and write permissions.

* 1 — Parse file permissions.
* 0 — Do not parse file permissions.
    Enum: 0, 1

  - `limit_to_list` (integer)
    Whether to return only entries that begin with the filepath- prefix.

* 1 — Return only files that begin with the filepath- prefix.
* 0 — Return all files.

If you do not use this parameter, the function returns all filenames.
    Enum: 0, 1

  - `mime_types` (string)
    The MIME types to return.

* If you use this parameter, the function returns the specified MIME types
and sets the include_mime parameter's value to 1.
* If you do not use this parameter, the function returns all MIME types.
    Example: "text-plain"

  - `only_these_files` (string)
    A comma-separated list of files to return.

If you do not use this parameter, the function returns all files.
    Example: "cpbackup-exclude.conf"

  - `raw_mime_types` (string)
    The raw MIME types to return.

* If you use this parameter, the function returns the specified MIME types
and sets the include_mime parameter's value to 1.
* If you do not use this parameter, the function returns all MIME types.
    Example: "text/plain"

  - `show_hidden` (integer)
    Whether to include hidden files in the output.

* 1 — Include hidden files.
* 0 — Do not include hidden files.
    Enum: 0, 1

  - `types` (array)
    A pipe-separated list of file types to return.

* file — A file.
* dir — A directory.
* char — A character special device.
* block — A block special device.
* fifo — A named pipe (FIFO).
* link — A symbolic link.
* socket — A Unix domain socket.

If you do not use this parameter, the function returns all file types.
    Example: ["file|dir"]

## Response 200 fields (application/json):

  - `apiversion` (integer)
    The version of the API.
    Example: 3

  - `func` (string)
    The name of the method called.
    Example: "list_files"

  - `module` (string)
    The name of the module called.
    Example: "Fileman"

  - `result` (object)

  - `result.data` (object)

  - `result.data.dirs` (array)
    An array of objects containing information about each directory.

  - `result.data.dirs.absdir` (string)
    The file path to the user's home directory.
    Example: "/home/user"

  - `result.data.dirs.ctime` (integer)
    The directory's creation date.
    Example: 1400573272

  - `result.data.dirs.exists` (integer)
    Whether the directory exists in the directory.

* 1 — Exists.
* 0 — Does not exist.
    Enum: 0, 1

  - `result.data.dirs.file` (string)
    The directory name.
    Example: "cgi-bin"

  - `result.data.dirs.fullpath` (string)
    The directory's full directory path.
    Example: "/home/user/public_html/cgi-bin"

  - `result.data.dirs.gid` (integer)
    The directory owner's system group ID.
    Example: 503

  - `result.data.dirs.humansize` (string)
    The formatted size of the directory. The function returns the size with
one of the following symbols:

* KB — Kilobytes.
* MB — Megabytes.
* GB — Gigabytes.
    Example: "5 KB"

  - `result.data.dirs.isleaf` (integer)
    Whether the directory contains subdirectories.

* 1 — Contains subdirectories.
* 0 — Does not contain subdirectories.
    Enum: 0, 1

  - `result.data.dirs.isparent` (integer)
    Whether the directory is a parent record.

* 1 — A parent record.
* 0 — Not a parent record.
    Enum: 0, 1

  - `result.data.dirs.mimename` (string)
    The MIME type's name.
    Example: "text-plain"

  - `result.data.dirs.mimetype` (string)
    The directory's MIME's type.
    Example: "text/plain"

  - `result.data.dirs.mode` (string)
    The directory's textual permissions in [Unix format](http://en.wikipedia.org/wiki/File_system_permissions#Notation_of_traditional_Unix_permissions).
    Example: "16877"

  - `result.data.dirs.mtime` (integer)
    The directory's last modification time.
    Example: 1400573272

  - `result.data.dirs.nicemode` (integer)
    The directory's numerical permissions.
    Example: 755

  - `result.data.dirs.path` (string)
    The path to the directory.
    Example: "/home/user/public.html"

  - `result.data.dirs.rawmimename` (string)
    The directory's raw MIME type's name.
    Example: "text-plain"

  - `result.data.dirs.rawmimetype` (string)
    The directory's raw MIME type.
    Example: "text/plain"

  - `result.data.dirs.read` (integer)
    Whether the directory is readable.

* 1 — Readable.
* 0 — Not readable.

Note:

The function only returns this value if the include_permissions value is 1.
    Enum: 0, 1

  - `result.data.dirs.size` (integer)
    The directory's size, in bytes.
    Example: 4096

  - `result.data.dirs.type` (string)
    The item's type.

* file — A file.
* dir — A directory.
* char — A character special device.
* block — A block special device.
* fifo - A named pipe (FIFO).
* link — A symbolic link.
* socket — A Unix domain socket.
    Enum: "file", "dir", "char", "block", "fifo", "link", "socket"

  - `result.data.dirs.uid` (integer)
    The directory owner's system user ID.
    Example: 502

  - `result.data.dirs.write` (integer)
    Whether the directory is writable.

* 1 — Writable.
* 0 — Not writable.

Note:

The function only returns this value if the include_permissions value is 1.
    Enum: 0, 1

  - `result.data.files` (array)
    An array of objects containing information about each file.

  - `result.data.files.absdir` (string)
    The file path to the user's home directory.
    Example: "/home/user"

  - `result.data.files.ctime` (integer)
    The file's creation time.
    Example: 1400573272

  - `result.data.files.exists` (integer)
    Whether the file exists in the directory.

* 1 — Exists.
* 0 — Does not exist.
    Enum: 0, 1

  - `result.data.files.file` (string)
    The filename.
    Example: "cgi-bin"

  - `result.data.files.fullpath` (string)
    The file's full file path.
    Example: "/home/user/public_html/cgi-bin"

  - `result.data.files.gid` (integer)
    The file owner's system group ID.
    Example: 503

  - `result.data.files.humansize` (string)
    The formatted size of the file. The function returns the size with
one of the following symbols:

* KB — Kilobytes.
* MB — Megabytes.
* GB — Gigabytes.
    Example: "5 KB"

  - `result.data.files.isleaf` (integer)
    Whether the directory contains subdirectories.

* 1 — Contains subdirectories.
* 0 — Does not contain subdirectories.
    Enum: 0, 1

  - `result.data.files.isparent` (integer)
    Whether the file is a parent record.

* 1 — A parent record.
* 0 — Not a parent record.
    Enum: 0, 1

  - `result.data.files.mimename` (string)
    The file's MIME type name.
    Example: "text-plain"

  - `result.data.files.mimetype` (string)
    The file's MIME type.
    Example: "text/plain"

  - `result.data.files.mode` (string)
    The file's textual permissions.
    Example: "16877"

  - `result.data.files.mtime` (integer)
    The file's last modification time.
    Example: 1400573272

  - `result.data.files.nicemode` (integer)
    The file's numerical permissions.
    Example: 755

  - `result.data.files.path` (string)
    The absolute path to the file.
    Example: "/home/user/public.html"

  - `result.data.files.rawmimename` (string)
    The file's raw MIME type's name.
    Example: "text-plain"

  - `result.data.files.rawmimetype` (string)
    The file's raw MIME type.
    Example: "text/plain"

  - `result.data.files.read` (integer)
    Whether the file is readable.

* 1 — Readable.
* 0 — Not readable.

Note:

The function only returns this value if the include_permissions value is 1.
    Enum: 0, 1

  - `result.data.files.size` (integer)
    The file's size, in bytes.
    Example: 4096

  - `result.data.files.type` (string)
    The item's type.

* file — A file.
* dir — A directory.
* char — A character special device.
* block — A block special device.
* fifo - A named pipe (FIFO).
* link — A symbolic link.
* socket — A Unix domain socket.
    Enum: "file", "dir", "char", "block", "fifo", "link", "socket"

  - `result.data.files.uid` (integer)
    The file owner's system user ID.
    Example: 502

  - `result.data.files.write` (integer)
    Whether the file is writable.

* 1 — Writable.
* 0 — Not writable.

Note:

The function only returns this value if the include_permissions value is 1.
    Enum: 0, 1

  - `result.errors` (array,null)
    List of errors if the API failed.

  - `result.messages` (array,null)
    List of messages generated by the API.

  - `result.metadata` (object)

  - `result.status` (integer)
    * 1 — Success
* 0 — Failed: Check the errors field for more details.
    Enum: 0, 1

  - `result.warnings` (array,null)
    List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.