Get directory entries. Path or ID must reference a directory.
Parameters
Name
Description
Required
ref
The file ID or the absolute path to the file system object. File IDs can be found in the id field of responses of APIs that return file attributes. You must URL-encode the paths. The APIs & Tools page in the Qumulo Core Web UI URL-encodes the paths.
Yes
snapshot
The snapshot ID that specifies the version of the filesystem to use. If not specified, use the head version.
No
smb-pattern
Return only entries matching the give SMB pattern
No
skip-atime-update
If true, suppress the update of the directory's access time for this read.
No
include-acls
If set to true, include the ACL for each entry in the response. To retrieve the ACL for files[i], look up file_acls.acl_pool[file_acls.acl_indices[i]]. When the caller doesn't have the READ_ACL permission for a file, the entry in acl.acl_indices is null. False by default.
No
after
Return entries after the given key (keys are returned in the paging object)
No
limit
Return no more than this many entries; the system may choose a smaller limit.
No
Response
Codes
Code
Description
200
Return value on success
Schema
{"description":"api_files_directory_entries","type":"object","properties":{"path":{"description":"path","type":"string"},"id":{"description":"Unique ID of this directory","type":"string"},"child_count":{"description":"child_count","type":"number"},"files":{"type":"array","items":{"description":"files","type":"object","properties":{"path":{"description":"Filesystem path of the object","type":"string"},"name":{"description":"Name of this file","type":"string"},"num_links":{"description":"How many directory entries are associated with this file","type":"number"},"type":{"type":"string","enum":["FS_FILE_TYPE_FILE","FS_FILE_TYPE_DIRECTORY","FS_FILE_TYPE_SYMLINK","FS_FILE_TYPE_UNIX_PIPE","FS_FILE_TYPE_UNIX_CHARACTER_DEVICE","FS_FILE_TYPE_UNIX_BLOCK_DEVICE","FS_FILE_TYPE_UNIX_SOCKET"],"description":"Resource type:\n * `FS_FILE_TYPE_DIRECTORY` - FS_FILE_TYPE_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - FS_FILE_TYPE_FILE,\n * `FS_FILE_TYPE_SYMLINK` - FS_FILE_TYPE_SYMLINK,\n * `FS_FILE_TYPE_UNIX_BLOCK_DEVICE` - FS_FILE_TYPE_UNIX_BLOCK_DEVICE,\n * `FS_FILE_TYPE_UNIX_CHARACTER_DEVICE` - FS_FILE_TYPE_UNIX_CHARACTER_DEVICE,\n * `FS_FILE_TYPE_UNIX_PIPE` - FS_FILE_TYPE_UNIX_PIPE,\n * `FS_FILE_TYPE_UNIX_SOCKET` - FS_FILE_TYPE_UNIX_SOCKET"},"major_minor_numbers":{"description":"The major and minor numbers for UNIX device files","type":"object","properties":{"major":{"description":"major","type":"number"},"minor":{"description":"minor","type":"number"}}},"symlink_target_type":{"type":"string","enum":["FS_FILE_TYPE_UNKNOWN","FS_FILE_TYPE_FILE","FS_FILE_TYPE_DIRECTORY"],"description":"The type of the target file if this file is a symlink:\n * `FS_FILE_TYPE_DIRECTORY` - API_SYMLINK_TARGET_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - API_SYMLINK_TARGET_FILE,\n * `FS_FILE_TYPE_UNKNOWN` - API_SYMLINK_TARGET_UNKNOWN"},"file_number":{"description":"Unique ID of this file","type":"string"},"id":{"description":"Unique ID of this file","type":"string"},"mode":{"description":"POSIX-style file mode (octal)","type":"string"},"owner":{"description":"File owner","type":"string"},"owner_details":{"description":"File owner details","type":"object","properties":{"id_type":{"type":"string","enum":["LOCAL_USER","LOCAL_GROUP","NFS_GID","NFS_UID","SMB_SID","INTERNAL","QUMULO_OPERATOR","QUMULO_SUPPORT"],"description":"id_type:\n * `INTERNAL` - INTERNAL,\n * `LOCAL_GROUP` - LOCAL_GROUP,\n * `LOCAL_USER` - LOCAL_USER,\n * `NFS_GID` - NFS_GID,\n * `NFS_UID` - NFS_UID,\n * `QUMULO_OPERATOR` - QUMULO_OPERATOR,\n * `QUMULO_SUPPORT` - QUMULO_SUPPORT,\n * `SMB_SID` - SMB_SID"},"id_value":{"description":"id_value","type":"string"}}},"group":{"description":"File group","type":"string"},"group_details":{"description":"File group details","type":"object","properties":{"id_type":{"type":"string","enum":["LOCAL_USER","LOCAL_GROUP","NFS_GID","NFS_UID","SMB_SID","INTERNAL","QUMULO_OPERATOR","QUMULO_SUPPORT"],"description":"id_type:\n * `INTERNAL` - INTERNAL,\n * `LOCAL_GROUP` - LOCAL_GROUP,\n * `LOCAL_USER` - LOCAL_USER,\n * `NFS_GID` - NFS_GID,\n * `NFS_UID` - NFS_UID,\n * `QUMULO_OPERATOR` - QUMULO_OPERATOR,\n * `QUMULO_SUPPORT` - QUMULO_SUPPORT,\n * `SMB_SID` - SMB_SID"},"id_value":{"description":"id_value","type":"string"}}},"blocks":{"description":"Number of blocks used by the file on this cluster","type":"string"},"datablocks":{"description":"Number of data blocks used by the file on this cluster","type":"string"},"metablocks":{"description":"Number of meta blocks used by the file on this cluster","type":"string"},"logical_datablocks":{"description":"Number of data blocks used by the file","type":"string"},"size":{"description":"File size in bytes","type":"string"},"access_time":{"description":"Last time content was read, RFC 3339 format","type":"string"},"modification_time":{"description":"Last time content was modified, RFC 3339 format","type":"string"},"change_time":{"description":"Last time content or attributes were modified, RFC 3339 format","type":"string"},"creation_time":{"description":"File creation time, RFC 3339 format","type":"string"},"child_count":{"description":"Count of children (valid for directories)","type":"number"},"extended_attributes":{"description":"SMB extended file attributes","type":"object","properties":{"read_only":{"description":"read_only","type":"boolean"},"hidden":{"description":"hidden","type":"boolean"},"system":{"description":"system","type":"boolean"},"archive":{"description":"archive","type":"boolean"},"temporary":{"description":"temporary","type":"boolean"},"compressed":{"description":"compressed","type":"boolean"},"not_content_indexed":{"description":"not_content_indexed","type":"boolean"},"sparse_file":{"description":"sparse_file","type":"boolean"},"offline":{"description":"offline","type":"boolean"}}},"directory_entry_hash_policy":{"type":"string","enum":["FS_DIRECTORY_HASH_VERSION_LOWER","FS_DIRECTORY_HASH_VERSION_FOLDED"],"description":"Hash policy for directory entries:\n * `FS_DIRECTORY_HASH_VERSION_FOLDED` - FS_DIRECTORY_HASH_VERSION_FOLDED,\n * `FS_DIRECTORY_HASH_VERSION_LOWER` - FS_DIRECTORY_HASH_VERSION_LOWER"},"data_revision":{"description":"The revision for changes to the underlying file data.","type":"string"},"user_metadata_revision":{"description":"The revision for changes to the user defined metadata of the file.","type":"string"}}}},"file_acls":{"description":"Provides the ACL for each file. When include_acls is not requested, file_acls is null.","type":"object","properties":{"acl_pool":{"type":"array","items":{"description":"The ACL pool which acl_indices references. To retrieve the ACL for files[i] look up acl_pool[acl_indices[i]].","type":"object","properties":{"control":{"description":"control","type":"array","items":{"type":"string","enum":["PRESENT","DEFAULTED","TRUSTED","AUTO_INHERIT","PROTECTED","ALL"],"description":"control:\n * `ALL` - All ACL controls,\n * `AUTO_INHERIT` - Set whether the ACL was created through inheritance,\n * `DEFAULTED` - Sets whether the ACL was established by default means,\n * `PRESENT` - Set when ACL is present on the object,\n * `PROTECTED` - Protects ACL from inherit operations,\n * `TRUSTED` - Set when ACL is provided by a trusted source"}},"posix_special_permissions":{"type":"array","items":{"type":"string","enum":["STICKY_BIT","SET_GID","SET_UID"],"description":"posix_special_permissions:\n * `SET_GID` - SET_GID,\n * `SET_UID` - SET_UID,\n * `STICKY_BIT` - STICKY_BIT"}},"aces":{"type":"array","items":{"description":"aces","type":"object","properties":{"type":{"type":"string","enum":["ALLOWED","DENIED"],"description":"Type of this ACL entry:\n * `ALLOWED` - An ACL entry that grants rights,\n * `DENIED` - An ACL entry that denies rights"},"flags":{"description":"ACE flags for this ACL entry","type":"array","items":{"type":"string","enum":["OBJECT_INHERIT","CONTAINER_INHERIT","NO_PROPAGATE_INHERIT","INHERIT_ONLY","INHERITED","ALL"],"description":"ACE flags for this ACL entry:\n * `ALL` - All ACE flags,\n * `CONTAINER_INHERIT` - Children that are containers inherit as effective ACE,\n * `INHERITED` - Indicates the ACE was inherited,\n * `INHERIT_ONLY` - Indicates an inherit-only ACE that doesn't control access to the attached object,\n * `NO_PROPAGATE_INHERIT` - Prevent subsequent children from inheriting ACE,\n * `OBJECT_INHERIT` - Non-container children inherit as effective ACE. Container objects inherit as inherit-only ACE"}},"trustee":{"description":"Trustee for this ACL entry","type":"object","properties":{"domain":{"type":"string","enum":["LOCAL","API_NULL_DOMAIN","WORLD","POSIX_USER","POSIX_GROUP","ACTIVE_DIRECTORY","API_INVALID_DOMAIN","API_RESERVED_DOMAIN","API_INTERNAL_DOMAIN","API_OPERATOR_DOMAIN","API_QUMULO_SUPPORT_DOMAIN","API_CREATOR_DOMAIN"],"description":"domain:\n * `ACTIVE_DIRECTORY` - ACTIVE_DIRECTORY,\n * `API_CREATOR_DOMAIN` - API_CREATOR_DOMAIN,\n * `API_INTERNAL_DOMAIN` - API_INTERNAL_DOMAIN,\n * `API_INVALID_DOMAIN` - API_INVALID_DOMAIN,\n * `API_NULL_DOMAIN` - API_NULL_DOMAIN,\n * `API_OPERATOR_DOMAIN` - API_OPERATOR_DOMAIN,\n * `API_QUMULO_SUPPORT_DOMAIN` - API_QUMULO_SUPPORT_DOMAIN,\n * `API_RESERVED_DOMAIN` - API_RESERVED_DOMAIN,\n * `LOCAL` - LOCAL,\n * `POSIX_GROUP` - POSIX_GROUP,\n * `POSIX_USER` - POSIX_USER,\n * `WORLD` - WORLD"},"auth_id":{"description":"auth_id","type":"string"},"uid":{"description":"uid","type":"number"},"gid":{"description":"gid","type":"number"},"sid":{"description":"sid","type":"string"},"name":{"description":"name","type":"string"}}},"rights":{"description":"Rights granted or denied for this ACL entry","type":"array","items":{"type":"string","enum":["READ","READ_EA","READ_ATTR","READ_ACL","WRITE_EA","WRITE_ATTR","WRITE_ACL","CHANGE_OWNER","WRITE_GROUP","DELETE","EXECUTE","MODIFY","EXTEND","ADD_FILE","ADD_SUBDIR","DELETE_CHILD","SYNCHRONIZE","ALL"],"description":"Rights granted or denied for this ACL entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - File read access,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"}}}}}}}},"acl_indices":{"type":"array","items":{"description":"Same length as files. acl_indices[i] is the index in acl_pool for files[i]. When the caller doesn't have the READ_ACL permission for a file, acl_indices[i] is null.","type":"number"}}}}}}
POST
Create a new file, link, or directory. In addition, this method can be use to rename an existing file. The return value is an attribute structure for the new file; refer to the 'Set Attributes' method for field descriptions.
Parameters
Name
Description
Required
ref
The file ID or the absolute path to the file system object. File IDs can be found in the id field of responses of APIs that return file attributes. You must URL-encode the paths. The APIs & Tools page in the Qumulo Core Web UI URL-encodes the paths.
Yes
Request
Schema
{"description":"api_files_create_entry","type":"object","properties":{"name":{"description":"Name of file to create","type":"string"},"action":{"type":"string","enum":["CREATE_FILE","CREATE_DIRECTORY","CREATE_SYMLINK","CREATE_LINK","RENAME","CREATE_UNIX_FILE"],"description":"Operation to perform:\n * `CREATE_DIRECTORY` - API_FILES_CREATE_DIRECTORY,\n * `CREATE_FILE` - API_FILES_CREATE_FILE,\n * `CREATE_LINK` - API_FILES_CREATE_LINK,\n * `CREATE_SYMLINK` - API_FILES_CREATE_SYMLINK,\n * `CREATE_UNIX_FILE` - API_FILES_CREATE_UNIX_FILE,\n * `RENAME` - API_FILES_RENAME"},"old_path":{"description":"Rename source or link target","type":"string"},"clobber":{"description":"When action is RENAME, setting this to true will clobber the destination if it exists.","type":"boolean"},"symlink_target_type":{"type":"string","enum":["FS_FILE_TYPE_UNKNOWN","FS_FILE_TYPE_FILE","FS_FILE_TYPE_DIRECTORY"],"description":"The file type of the target to which the symbolic link points. If you don't specify the file type, or if it is FS_FILE_TYPE_UNKNOWN, the effect is the same as running the 'ln -s' command on a Unix NFS client. If the file type is FS_FILE_TYPE_FILE or FS_FILE_TYPE_DIRECTORY, the effect is the same as running the 'mklink' or 'mklink /D' command on a Windows SMB client.:\n * `FS_FILE_TYPE_DIRECTORY` - API_SYMLINK_TARGET_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - API_SYMLINK_TARGET_FILE,\n * `FS_FILE_TYPE_UNKNOWN` - API_SYMLINK_TARGET_UNKNOWN"},"unix_file_type":{"type":"string","enum":["FS_FILE_TYPE_FILE","FS_FILE_TYPE_DIRECTORY","FS_FILE_TYPE_SYMLINK","FS_FILE_TYPE_UNIX_PIPE","FS_FILE_TYPE_UNIX_CHARACTER_DEVICE","FS_FILE_TYPE_UNIX_BLOCK_DEVICE","FS_FILE_TYPE_UNIX_SOCKET"],"description":"Required when the action is CREATE_UNIX_FILE. You are given the choice of FS_FILE_TYPE_UNIX_BLOCK_DEVICE, FS_FILE_TYPE_UNIX_CHARACTER_DEVICE, FS_FILE_TYPE_UNIX_PIPE or FS_FILE_TYPE_UNIX_SOCKET:\n * `FS_FILE_TYPE_DIRECTORY` - FS_FILE_TYPE_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - FS_FILE_TYPE_FILE,\n * `FS_FILE_TYPE_SYMLINK` - FS_FILE_TYPE_SYMLINK,\n * `FS_FILE_TYPE_UNIX_BLOCK_DEVICE` - FS_FILE_TYPE_UNIX_BLOCK_DEVICE,\n * `FS_FILE_TYPE_UNIX_CHARACTER_DEVICE` - FS_FILE_TYPE_UNIX_CHARACTER_DEVICE,\n * `FS_FILE_TYPE_UNIX_PIPE` - FS_FILE_TYPE_UNIX_PIPE,\n * `FS_FILE_TYPE_UNIX_SOCKET` - FS_FILE_TYPE_UNIX_SOCKET"},"major_minor_numbers":{"description":"When creating a UNIX device file, these are the major and minor numbers","type":"object","properties":{"major":{"description":"major","type":"number"},"minor":{"description":"minor","type":"number"}}}}}
Response
Codes
Code
Description
200
Return value on success
Schema
{"description":"api_files_attributes","type":"object","properties":{"path":{"description":"Filesystem path of the object","type":"string"},"name":{"description":"Name of this file","type":"string"},"num_links":{"description":"How many directory entries are associated with this file","type":"number"},"type":{"type":"string","enum":["FS_FILE_TYPE_FILE","FS_FILE_TYPE_DIRECTORY","FS_FILE_TYPE_SYMLINK","FS_FILE_TYPE_UNIX_PIPE","FS_FILE_TYPE_UNIX_CHARACTER_DEVICE","FS_FILE_TYPE_UNIX_BLOCK_DEVICE","FS_FILE_TYPE_UNIX_SOCKET"],"description":"Resource type:\n * `FS_FILE_TYPE_DIRECTORY` - FS_FILE_TYPE_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - FS_FILE_TYPE_FILE,\n * `FS_FILE_TYPE_SYMLINK` - FS_FILE_TYPE_SYMLINK,\n * `FS_FILE_TYPE_UNIX_BLOCK_DEVICE` - FS_FILE_TYPE_UNIX_BLOCK_DEVICE,\n * `FS_FILE_TYPE_UNIX_CHARACTER_DEVICE` - FS_FILE_TYPE_UNIX_CHARACTER_DEVICE,\n * `FS_FILE_TYPE_UNIX_PIPE` - FS_FILE_TYPE_UNIX_PIPE,\n * `FS_FILE_TYPE_UNIX_SOCKET` - FS_FILE_TYPE_UNIX_SOCKET"},"major_minor_numbers":{"description":"The major and minor numbers for UNIX device files","type":"object","properties":{"major":{"description":"major","type":"number"},"minor":{"description":"minor","type":"number"}}},"symlink_target_type":{"type":"string","enum":["FS_FILE_TYPE_UNKNOWN","FS_FILE_TYPE_FILE","FS_FILE_TYPE_DIRECTORY"],"description":"The type of the target file if this file is a symlink:\n * `FS_FILE_TYPE_DIRECTORY` - API_SYMLINK_TARGET_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - API_SYMLINK_TARGET_FILE,\n * `FS_FILE_TYPE_UNKNOWN` - API_SYMLINK_TARGET_UNKNOWN"},"file_number":{"description":"Unique ID of this file","type":"string"},"id":{"description":"Unique ID of this file","type":"string"},"mode":{"description":"POSIX-style file mode (octal)","type":"string"},"owner":{"description":"File owner","type":"string"},"owner_details":{"description":"File owner details","type":"object","properties":{"id_type":{"type":"string","enum":["LOCAL_USER","LOCAL_GROUP","NFS_GID","NFS_UID","SMB_SID","INTERNAL","QUMULO_OPERATOR","QUMULO_SUPPORT"],"description":"id_type:\n * `INTERNAL` - INTERNAL,\n * `LOCAL_GROUP` - LOCAL_GROUP,\n * `LOCAL_USER` - LOCAL_USER,\n * `NFS_GID` - NFS_GID,\n * `NFS_UID` - NFS_UID,\n * `QUMULO_OPERATOR` - QUMULO_OPERATOR,\n * `QUMULO_SUPPORT` - QUMULO_SUPPORT,\n * `SMB_SID` - SMB_SID"},"id_value":{"description":"id_value","type":"string"}}},"group":{"description":"File group","type":"string"},"group_details":{"description":"File group details","type":"object","properties":{"id_type":{"type":"string","enum":["LOCAL_USER","LOCAL_GROUP","NFS_GID","NFS_UID","SMB_SID","INTERNAL","QUMULO_OPERATOR","QUMULO_SUPPORT"],"description":"id_type:\n * `INTERNAL` - INTERNAL,\n * `LOCAL_GROUP` - LOCAL_GROUP,\n * `LOCAL_USER` - LOCAL_USER,\n * `NFS_GID` - NFS_GID,\n * `NFS_UID` - NFS_UID,\n * `QUMULO_OPERATOR` - QUMULO_OPERATOR,\n * `QUMULO_SUPPORT` - QUMULO_SUPPORT,\n * `SMB_SID` - SMB_SID"},"id_value":{"description":"id_value","type":"string"}}},"blocks":{"description":"Number of blocks used by the file on this cluster","type":"string"},"datablocks":{"description":"Number of data blocks used by the file on this cluster","type":"string"},"metablocks":{"description":"Number of meta blocks used by the file on this cluster","type":"string"},"logical_datablocks":{"description":"Number of data blocks used by the file","type":"string"},"size":{"description":"File size in bytes","type":"string"},"access_time":{"description":"Last time content was read, RFC 3339 format","type":"string"},"modification_time":{"description":"Last time content was modified, RFC 3339 format","type":"string"},"change_time":{"description":"Last time content or attributes were modified, RFC 3339 format","type":"string"},"creation_time":{"description":"File creation time, RFC 3339 format","type":"string"},"child_count":{"description":"Count of children (valid for directories)","type":"number"},"extended_attributes":{"description":"SMB extended file attributes","type":"object","properties":{"read_only":{"description":"read_only","type":"boolean"},"hidden":{"description":"hidden","type":"boolean"},"system":{"description":"system","type":"boolean"},"archive":{"description":"archive","type":"boolean"},"temporary":{"description":"temporary","type":"boolean"},"compressed":{"description":"compressed","type":"boolean"},"not_content_indexed":{"description":"not_content_indexed","type":"boolean"},"sparse_file":{"description":"sparse_file","type":"boolean"},"offline":{"description":"offline","type":"boolean"}}},"directory_entry_hash_policy":{"type":"string","enum":["FS_DIRECTORY_HASH_VERSION_LOWER","FS_DIRECTORY_HASH_VERSION_FOLDED"],"description":"Hash policy for directory entries:\n * `FS_DIRECTORY_HASH_VERSION_FOLDED` - FS_DIRECTORY_HASH_VERSION_FOLDED,\n * `FS_DIRECTORY_HASH_VERSION_LOWER` - FS_DIRECTORY_HASH_VERSION_LOWER"},"data_revision":{"description":"The revision for changes to the underlying file data.","type":"string"},"user_metadata_revision":{"description":"The revision for changes to the user defined metadata of the file.","type":"string"}}}
