List Directory or Album

Last updated:2026-01-07 14:52:05

List Directory or Album

Last updated: 2026-01-07 14:52:05

Description 
List directory or album content.
Note:
The directory content is listed in the following order: first, subdirectories are listed in dictionary order, followed by media resources in the media library displayed by upload time, or file resources in the file library listed by file names.
Request
Request Example
GET /api/v1/directory/{LibraryId}/{SpaceId}/{DirPath}?page={Page}&page_size={PageSize}&order_by={OrderBy}&order_by_type={OrderByType}&filter={DirectoryFilter}&access_token={AccessToken}&user_id={UserId}
Request Parameter
Request parameters.
Description
Type
Required or Not
LibraryId
Media Library ID, obtain it after creating a media library in the media hosting console, see create media library
String
Yes
SpaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as a hyphen (-); if the media library is in multi-tenant mode, you must specify this parameter. Please refer to create tenant space for retrieval.
String
No
DirPath
Directory path or album name. For multi-level directory, use a slash (/) to separate, such as foo/bar; for root directory, leave this parameter blank.
String
No
Marker
Identification for sequential listing with paginate, cannot be used with page and page_size parameters simultaneously
String
No
Limit
Limit on the number of locally listed projects for sequential pagination, cannot be used with page and page_size parameters simultaneously
String
No
Page
pagination code, default first page, cannot be used with marker and limit parameters simultaneously
String
No
PageSize
page size, default 20, cannot be used with marker and limit parameters simultaneously
String
No
OrderBy
Sorting field: name for sort by name, modificationTime for sort by modification time, size for sort by file size, creationTime for sort by creation time, localCreationTime for sort by local creation time, localModificationTime for sort by local modification time
String
No
OrderByType
Sorting method: asc for ascending, desc for descending
String
No
DirectoryFilter
Filtering method. If not specified, return all. onlyDir returns folders only, onlyFile returns files only.
String
No
SortType
Sorting method. If not specified, files and folders are sorted separately, with folders returned first, followed by files. union sorts files and folders together.
String
No
WithInode
0 or 1, whether to return inode (file directory ID). Default: do not return.
String
No
WithFavoriteStatus
0 or 1, whether to return favorite status. Default: do not return.
String
No
AccessToken
Access token. For Public Read Media Library or tenant space, this parameter is not specified. Otherwise, you must specify this parameter. To obtain it, see Generate Access Token.
String
No
UserId
User identity recognition. When the access token corresponds to admin permission and the user identity recognition during token application is empty, it is used to temporarily specify user identity. For details, see Generate Access Token.
String
No
Request Body
This request does not have a request body.
Response
Response code
Retrieval successful, return HTTP 200 OK.
Response Body
application/json
Response body example:
{
  "path": [ "foo", "bar" ],
  "nextMarker": 1013,
  "fileCount": 10,
  "subDirCount": 8,
  "totalNum":18,
  "localSync": {
    "syncId": 4,
    "strategy": "local_to_cloud",
    "isSyncRootFolder": true,
    "syncUserId": "123"
  },
  "contents": [
      {
          "name": "sub-dir1",
          "path":["xxx","xxx"],
          "type": "dir",
          "creationTime": "2020-09-22T07:43:01.000Z",
          "modificationTime": "2020-09-22T07:43:01.000Z",
          "versionId":2, 
          "localSync": {
            "syncId": 4,
            "strategy": "local_to_cloud",
            "syncUserId": "",
            "isSyncRootFolder": false,
          },
          "authorityList": {
              "canView": false,
              "canPreview": false,
              "canDownload": false,
              "canUpload": false,
              "canDelete": false,
              "canModify": false,
              "canAuthorize": false,
              "canShare": false
          }
      },
      {
          "name": "sub-dir2",
          "type": "dir",
          "creationTime": "2020-09-22T07:43:14.000Z",
          "modificationTime": "2020-09-22T07:43:14.000Z"
      },
      {
          "name": "file1.jpg",
          "type": "file",
          "creationTime": "2020-09-22T07:44:45.000Z",
          "modificationTime": "2020-09-22T07:44:45.000Z",
          "contentType": "image/jpg",
          "size": "1048576",
          "eTag": "xxx",
          "crc64": "xxx",
          "authorityList": {
              "canView": false,
              "canPreview": false,
              "canDownload": false,
              "canUpload": false,
              "canDelete": false,
              "canModify": false,
              "canAuthorize": false,
              "canShare": false
          },
          "metaData": {
              "x-smh-meta-foo": "bar"
          },
          "previewByDoc": true,
          "previewByCI": true,
          "previewAsIcon": true,
          "fileType": "powerpoint",
      },
      {
          "name": "file2.docx",
          "type": "file",
          "creationTime": "2020-09-22T07:46:08.000Z",
          "modificationTime": "2020-09-22T07:46:08.000Z",
          "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingm",
          "size": "1048576",
          "eTag": "xxx",
          "crc64": "xxx",
          "metaData": {
              "x-smh-meta-foo": "bar"
          },
          "previewByDoc": true,
          "previewByCI": true,
          "previewAsIcon": true,
          "fileType": "powerpoint",
      }
  ],
  "authorityList": {
      "canView": false,
      "canPreview": false,
      "canDownload": false,
      "canUpload": false,
      "canDelete": false,
      "canModify": false,
      "canAuthorize": false,
      "canShare": false,
      "canPreviewSelf": false,
      "canDownloadSelf": false
  }
}
Field description in the response body:
Response Parameters
Description
Type
path
Return the directory structure of the current request. If the current request is for the root directory, this field is an empty array.
Array
fileCount
Number of files in the current directory (excluding subdirectories)
Int
subDirCount
Number of subdirectories in the current directory (excluding subdirectories)
Int
totalNum
Number of all files and subdirectories in the current directory (excluding subdirectories)
Int
nextMarker
Sequential page identification for listing
String/Int
contents
Content in directory or album
Array
Specific parameters in contents are as follows:
Response Parameters
Description
Type
name
Directory or album name or file name
String
path
Specific file directory
String
inode
File directory ID
String
versionId
Version number.
String
type
Entry type
dir: directory or album.
file: file, only used for file type media library.
image: image, only used for media type media library.
video: video, only used for media type media library.
symlink: symbolic link.
String
creationTime
ISO 8601 formatted date and time string indicating the creation time of a directory or album, or the upload time of a file, such as 2020-10-14T10:17:57.953Z
String
modificationTime
The time when the file was last overwritten, or the last time a subdirectory or file was added or removed in the directory
String
contentType
media type
String
size
File size, to avoid precision issues
String
eTag
File ETag
String
isFavorite
Whether it is a favorite, returns when WithFavoriteStatus = 1
Boolean
crc64
File CRC64-ECMA182 check value
String
metaData
File metadata information
String
previewByDoc
Whether WPS can preview
Boolean
previewByCI
Whether Wanxiang can preview
Boolean
previewAsIcon
Use preview image as icon
Boolean
fileType
File type: Excel, PowerPoint
String
category
File classification, such as image, video, doc
String
labels
Simplified file tag
Array
localCreationTime
Local creation time of the file
String
localModificationTime
Local modification time of the file
String
Error Codes
This request operation has no special error messages. For common error messages, see Error Codes.

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Feedback

Request parameters.	Description	Type	Required or Not
LibraryId	Media Library ID, obtain it after creating a media library in the media hosting console, see create media library	String	Yes
SpaceId	Space ID. If the media library is in single-tenant mode, this parameter is fixed as a hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. Please refer to create tenant space for retrieval.	String	No
DirPath	Directory path or album name. For multi-level directory, use a slash (`/`) to separate, such as `foo/bar`; for root directory, leave this parameter blank.	String	No
Marker	Identification for sequential listing with paginate, cannot be used with page and page_size parameters simultaneously	String	No
Limit	Limit on the number of locally listed projects for sequential pagination, cannot be used with page and page_size parameters simultaneously	String	No
Page	pagination code, default first page, cannot be used with marker and limit parameters simultaneously	String	No
PageSize	page size, default 20, cannot be used with marker and limit parameters simultaneously	String	No
OrderBy	Sorting field: name for sort by name, modificationTime for sort by modification time, size for sort by file size, creationTime for sort by creation time, localCreationTime for sort by local creation time, localModificationTime for sort by local modification time	String	No
OrderByType	Sorting method: asc for ascending, desc for descending	String	No
DirectoryFilter	Filtering method. If not specified, return all. onlyDir returns folders only, onlyFile returns files only.	String	No
SortType	Sorting method. If not specified, files and folders are sorted separately, with folders returned first, followed by files. union sorts files and folders together.	String	No
WithInode	0 or 1, whether to return inode (file directory ID). Default: do not return.	String	No
WithFavoriteStatus	0 or 1, whether to return favorite status. Default: do not return.	String	No
AccessToken	Access token. For Public Read Media Library or tenant space, this parameter is not specified. Otherwise, you must specify this parameter. To obtain it, see Generate Access Token.	String	No
UserId	User identity recognition. When the access token corresponds to admin permission and the user identity recognition during token application is empty, it is used to temporarily specify user identity. For details, see Generate Access Token.	String	No

Response Parameters	Description	Type
path	Return the directory structure of the current request. If the current request is for the root directory, this field is an empty array.	Array
fileCount	Number of files in the current directory (excluding subdirectories)	Int
subDirCount	Number of subdirectories in the current directory (excluding subdirectories)	Int
totalNum	Number of all files and subdirectories in the current directory (excluding subdirectories)	Int
nextMarker	Sequential page identification for listing	String/Int
contents	Content in directory or album	Array

tencent cloud

Description

Request

Request Example

Request Parameter

Request Body

Response

Response code

Response Body

Error Codes