Search files with the API

On this page

The search API provides you with a powerful way to find files in your Sirv account.

Search options

You can search any combination of these parameters:

  • basename - file name
  • filename - file name and its folder path
  • dirname - folder name
  • dirname.paths - strictly this folder only
  • dirname.raw - this folder and its sub-folders
  • extension - file extension e.g. .jpg
  • contentType - mime type e.g. image/JPEG
  • mtime - modified time
  • ctime - created time
  • size - file size
  • isDirectory - if the result is a folder
  • meta.tags - files with a particular meta tag
  • meta.description - files with a particular meta description
  • meta.title - files with a particular meta title
  • meta.width - images with certain width
  • meta.height - images with certain height

This query will search for all files named Adidas-Gazelle.jpg:

"query": "basename:Adidas-Gazelle.jpg",

Boolean operators

You can use AND, OR and NOT boolean operators to narrow down the files you require.


Create a very specific search using AND to search upon a variety of requirements. For example, this will return all JPEG files modified in the last 14 days and not in the Trash folder:

"query": "contentType:image\\/jpeg AND mtime:[now-14d TO now] AND -dirname:\\/.Trash",


A search using OR will return results that contain either or both terms. For example, this will return files with either a .psd or .eps extension:

"query": "extension:.psd OR .eps",


You can exclude certain results with NOT. For example, this will show all results for "Gazelle", without showing any folders in the results:

"query": "filename:Gazelle NOT isDirectory:true",

Escaping special characters

You can use special characters in your search, as long as they are escaped with a double backslash \\ beforehand.

These special characters should be escaped:

{ } / \

For example to search for /My-folder/2022/studio.jpg use the query:

"query": "filename:\\/My-folder\\/2022\\/studio.jpg",

In case your file name/path contains a backslash \, then it should be escaped by only one backslash thus it will be displayed as two backslashes \\.


If you need to find all files that contain a partial string of characters, you can use * to fill in the gaps. It will match anything after that point.

For example:

  • Adidas*.jpg will return all results starting with Adidas and ending .jpg.
  • Adidas* will return all results starting with Adidas.

Additional options

You can also add a leading - to make it a negative query.

Example scripts

The REST API search documentation contains an example payload, JSON schema, response and scripts for 10 popular programming languages:

Was this article helpful?

Get help from a Sirv expert

help ukraine help ukraine Powered by Ukrainian determination and British ingenuity

How can you support Ukraine