List files and folders in a directory

POST 
/api/v1/storage/list-files

Lists files and subfolders under the given folder path. The current file filter accepts upload-date fields but does not enforce them; do not rely on those fields to exclude records.

The following access conditions are preserved as declared intent and are not implemented by generated code: Accepted storage owner context, Storage owner actor routing.

Use this in a guide: Build a searchable document library

Request

Responses

200

File listing returned

List a bounded page of files from the reports folder.

Section ID: DOC-CP-files-data-api-listFiles#example-storage-listFiles-request

Request example

{
  "folderPath": "reports",
  "pageSize": 20
}

Guide request for Populate the folder view. Replace example resource identifiers with your own authorized values.

Section ID: DOC-CP-files-data-api-listFiles#example-cookbook-core-platform-files-data-managing-01-request

Request example

{
  "folderPath": "/documents",
  "recursive": true,
  "pageSize": 20
}

Guide request for Populate the folder view. Replace example resource identifiers with your own authorized values.

Section ID: DOC-CP-files-data-api-listFiles#example-cookbook-core-platform-files-data-managing-json-01-request

Request example

{
  "folderPath": "/",
  "recursive": true,
  "filter": {
    "extensions": [
      ".pdf",
      ".docx"
    ],
    "tags": [
      "work"
    ],
    "minSizeBytes": 1024,
    "nameContains": "report"
  }
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.

Section ID: DOC-CP-files-data-api-listFiles#example-storage-listFiles-response

Response example

{
  "files": [
    {
      "fileId": "example_123",
      "name": "example",
      "path": "documents/example.txt",
      "folderPath": "documents/example.txt",
      "sizeBytes": "1",
      "contentType": "Example text",
      "uploadedAt": "example",
      "modifiedAt": "example",
      "metadata": {},
      "tags": [
        "example"
      ],
      "description": "example",
      "storageRef": {
        "bucket": "example",
        "key": "example_123",
        "provider": "STORAGE_PROVIDER_GCS"
      },
      "checksum": "example",
      "version": 1
    }
  ],
  "folders": [
    {
      "folderId": "example_123",
      "name": "example",
      "path": "documents/example.txt",
      "parentPath": "documents/example.txt",
      "createdAt": "example",
      "modifiedAt": "example",
      "metadata": {},
      "fileCount": 1,
      "subfolderCount": 1,
      "totalSizeBytes": "1"
    }
  ],
  "nextPageToken": "example",
  "totalCount": 1
}

Document ID: DOC-CP-files-data-api-listFiles. Section identities and revisions.

Section	Stable reference
List files and folders in a directory	DOC-CP-files-data-api-listFiles#overview
Request	DOC-CP-files-data-api-listFiles#request
Responses	DOC-CP-files-data-api-listFiles#responses