Search files

POST 
/api/v1/storage/search-files

Searches the effective user's tracked files using a case-insensitive filename substring or a case-insensitive complete tag. File contents, such as text inside a PDF, are not searched.

Supported FileFilter fields narrow candidates before the query is applied, and all listed tags must be present. The date filters uploadedAfter and uploadedBefore are accepted but currently not enforced; do not offer a date range as an effective filter.

maxResults caps a single response; search does not paginate. If results are too broad, let the customer refine the name, tag or folder rather than promising a complete result set.

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

Search results returned

Find matching files within the authenticated user’s storage namespace.

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

Request example

{
  "query": "welcome",
  "maxResults": 20
}

Guide request for Find a report when its folder is unknown. Replace example resource identifiers with your own authorized values.

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

Request example

{
  "query": "quarterly report",
  "maxResults": 10,
  "filter": {
    "extensions": [
      ".pdf"
    ],
    "tags": [
      "finance"
    ],
    "minSizeBytes": 1024,
    "maxSizeBytes": 52428800,
    "nameContains": "Q1"
  }
}

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

Section ID: DOC-CP-files-data-api-searchFiles#example-storage-searchFiles-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
    }
  ],
  "totalMatches": 1
}

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

Section	Stable reference
Search files	DOC-CP-files-data-api-searchFiles#overview
Request	DOC-CP-files-data-api-searchFiles#request
Responses	DOC-CP-files-data-api-searchFiles#responses