List Directory Entries

Drive is currently in Beta. API definitions, response structures, and behavior may change. Follow documentation updates and verify compatibility before production use.

GET /api/v1/forward/drives/entries

Request Headers

Header	Required	Description
Authorization	Yes	`Bearer <PAT or SAT>`

Query Parameters

Parameter	Type	Required	Description
identity_id	string	Yes	Identity ID within the current authentication scope; supply exactly once. An Identity-level SAT can select only its bound Identity.
path	string	No	Relative directory path; defaults to an empty string for the root.
limit	integer	No	Default 20, range 1–100; supply at most once.
page_token	string	No	The previous response's `next_page_token`; omit on the first request. Use it with the same credential resource scope, Identity, and directory. Maximum 8192 bytes; do not modify it.

Path Rules

Omit path or pass an empty string for the root. Nonempty paths must follow these rules:

Use a valid UTF-8 relative path such as projects/reports. Absolute paths such as /projects/reports or C:/projects/reports are not accepted.
Separate directories with /. Leading, trailing, or consecutive slashes, backslashes, and . or .. path segments are not allowed.
Leading or trailing whitespace, control characters, and % are not allowed, including escaped text such as projects%2Freports.

These rules apply to the decoded path. Query encoding:

Preserve / as the path separator, as in path=projects/reports; do not encode it as %2F.
Use standard form URL encoding for Chinese and reserved characters; encode spaces as +.

Example Request

curl --silent --show-error --fail-with-body -X GET \
  "https://api.qoder.com/api/v1/forward/drives/entries?identity_id=idn_xxx&path=projects&limit=20" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Example Response

HTTP 200 OK

{
  "entries": [
    {
      "path": "projects/demo",
      "name": "demo",
      "type": "directory"
    },
    {
      "path": "projects/readme.md",
      "name": "readme.md",
      "type": "file",
      "size": 2048,
      "etag": "example-etag",
      "last_modified": "2026-09-07T02:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
entries	array	Immediate children of the current directory, sorted lexicographically by path; `[]` if the directory is missing or empty.
entries[].path	string	Relative path within Drive; directory paths have no trailing `/`.
entries[].name	string	File or directory name at the current level.
entries[].type	string	`file` or `directory`.
entries[].size	integer	File size in bytes; 0 for zero-byte files, omitted for directories.
entries[].etag	string	File ETag, returned when nonempty; omitted for directories.
entries[].last_modified	string	File's last modification time in RFC 3339 format; omitted when unavailable and for directories.
next_page_token	string	Returned when another page exists; omitted on the last page. Pass it unchanged as `page_token` in the next request.

Errors

HTTP	Code	Condition
400	`invalid_drive_path`	The path, its query encoding, or the Identity identifier format is invalid.
400	`invalid_limit`	The page size is not an integer from 1 to 100, or is supplied more than once.
400	`invalid_page_token`	The page token is invalid, modified, or used with another resource scope, Identity, or directory.
400	`invalid_identity_id`	`identity_id` is missing, empty, or supplied more than once.
401	—	Credentials are missing or invalid. Exchange a Service Account Key for a SAT first.
403	`identity_mismatch`	An Identity-level SAT selected another Identity.
404	`identity_not_found`	The Identity was not found within the current authentication scope.
500	—	Internal server error.
503	`drive_unavailable`	Drive storage, signing, or a dependency is temporarily unavailable.

HTTP Error Response

{
  "type": "error",
  "request_id": "req_xxx",
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_drive_path",
    "message": "Invalid Drive path."
  }
}

Response Fields

Field	Type	Description
type	string	Always `error`.
request_id	string	Request trace ID, returned when available.
error.type	string	Error category, such as `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `conflict_error`, or `api_error`.
error.code	string	Business error code; omitted for some common errors.
error.message	string	Error description.

Gateway authentication errors may use a different response structure.

List Directory Entries

Request Headers

Query Parameters

Path Rules

Example Request

Example Response

Response Fields

Errors

HTTP Error Response

Response Fields

Create an Upload URL

Create a Download URL

​Request Headers

​Query Parameters

​Path Rules

​Example Request

​Example Response

​Response Fields

​Errors

​HTTP Error Response

​Response Fields

​Related

Create an Upload URL

Create a Download URL

Request Headers

Query Parameters

Path Rules

Example Request

Example Response

Response Fields

Errors

HTTP Error Response

Response Fields

Related