List & search files
GET {{api-server}}/:token/{{api-version}}/files
This API is used to search and list files in Filerobot.
Search parameter (&q=)
The (q=) parameter is used as a search and filter parameter for custom metadata fields,tags,filenames and also fuzzy search. For more information on how to arrange the returned results, see the format parameters in GET file details )
For all available options and syntax of the q= parameter, see the table below:
| Name | Description | Syntax | Value/Example |
|---|---|---|---|
| Fuzzy Search | Fuzzy search in all metadata fields. | Start and end with double quotes | - q="greater himalayas" |
| Tag filter | Tag-based filtering. | Start and end with double quotes and include sharp (#) before begining of the tag | - q="#headgear" |
| Single/Multi-Select Metadata Filters | Filtering by SELECT / MULTI_SELECT metadata fields. | Colon operator (`:`) should be included between the meta key and the meta value. In case there is a space in the meta value, the value should be quoted with double quotes (` value with space symbol`) The comma symbol (`,`) put between multiple meta values stays for OR operator. The addition symbol (`+`) put between multiple meta values stays for AND operator. empty keyword can be used to list all assets having an empty meta value non-empty keyword can be used to list all assets having any value in the metadata field. The minus symbol (` -`) put in front of the metadata value, stays for NOT operator. | - &q=kategorie:"Tiger" - &q="brand":"Saint Thomas" - &q=brand:Adidas,Nike - &q=kategorie:"Tiger"+brand:"Adidas" - q=copyright:empty - &q=copyright:non-empty - &q=brand:-scaleflex |
| Boolean Metadata filter | Filtering boolean metadata fields. | Meta value can be a boolean with true or false | - q=approved:true - &q=kategorie:"Tiger"+brand "Adidas"+approved:true |
| Numeric/Date Metadata filter | This format is used to search/filter metadata with DATE or NUMERIC data type. | Operators included between meta key and meta value are :(equality), >, <, >=, <=, !=(comparison) Double quotes can be used here when spaces are inside the meta key. Date values should be in a format yyyy-mm-dd For searching in an interval between 2 dates, the .. operator is used. | - &q="expiration date"!=2022-12-02 - &q="price material"!=100 - &q="price material">100 - &q=event_date:2024-06-17..2024-06-18 |
| Text/Text Area Metadata filter | This format searches/filters TEXT or TEXTAREA custom metadata. It looks for certain keywords (strings) in the user-specified meta field. Please note that it is searching for exact matches only. | The operator between the meta key and the meta value is ~ | - &q=Description~"product is hand made" |
| Filename search | A search by exact filename, including the file extension, can be performed using this format. | filename keyword is used as meta key and the meta value is the filename, put inside quotes. This search returns only exact matches, meaning that &q=filename:"girl.jpg" will not return girl.pngin the search results. | - &q=filename:"girl.jpg" |
Internal metadata search
A lot of asset metadata is stored internally by Filerobot. Some fields can be used as filters. For example, type`, orientation, mimetype, color, resolution, faces, approval_status, and enable_favorited are all examples of reserved keywords. You can not use these as keys of custom-defined metadata fields.
For searching and sorting results, you can use:
| Name: | Description: | Syntax: | Value/Example: |
|---|---|---|---|
type | Filter by asset type - WEBP, TXT, DOC, VIDEO, JPG | In case of filtering by multiple types, they should be separated with comma. It stays for OR operator. Possible values - application/pdf, image/jpeg, image/png, image/tiff, image/webp, image/x-icon, text/html, image/x-photoshop , image/vnd.adobe.photoshop, image/gif, video/mp4, image/tiff, image/webp etc. | `&type=txt,doc |
mimetype | Filter results by mimetype. | In case of filtering by multiple types, they should be separated with comma. It stays for OR operator. | &mimetype=image |
resolution | Filter by the image width | The possible value of resolution are: - &resolution=small (image width < 600) - &resolution=medium (image width between 600 and 1800) - &resolution=large(image width > 1800) | &resolution=medium,large |
orientation | Filter by the image orientation | The possible value of resolution are: - &orientation=PA(panaroma image) - &orientation=PO (portrait image) - &orientation=SQ (square image) - &orientation=LD (landscape image) | &orientation=SQ,LD |
size | Filter by image size in MB | It is a range of number.The lower and upper limit is separated by .. | &size=5..10 |
Filters available if specific AI postprocess is activated in the project
This category of filters returns results only if AI has been used to classify the data.
| Name: | Description: | Syntax: | Value/Example: |
|---|---|---|---|
faces | Filter by number of detected human faces in the image. | In order to return results, the AI postprocess Count facesshould be activated for the project. Possible value of faces are: - &faces=0..0 - no people detected - &faces=1..1 - 1 person - &faces=3..1000 - Groups The number of people searched in the image is specified with .. operator | &faces=3..1000 |
color | Filters by pre-dominant color found in the image | In order this filter to work, it requires activation of the AI process Extract Dominant Colors The filter supports the following color values - red, orange, pink, grass green, yellow, azure, chartreuse, teal, purple | &color=red,orange,pink,grass green,yellow,azure,chartreuse,teal,purple |
Labels search/filter:
You can filter results by multiple labels SID (SID is the internal value of an label which can be obtained by the Labels endpoint).
| Parameter | Type | Description | Example |
|---|---|---|---|
labels_operator | String | It is possible to search by several labels by defining the operator between them.The accepted values areOR, AND | - &labels_operator=AND - &labels_oerator=OR |
labels | String | Search by label's SID. If multiple SIDs, separate them by comma | &labels=lbxmw9j4s |
Sorting search results(&sort)
The search results can be sorted using the query parameter &sort. Sort results by name (default), uploaded_at, created_at, modified_at, size. Sort resuts with order asc or desc. Example: &sort=name:desc ; &sort=uploaded_at:asc
| Name: | Description: | Syntax: | Value/Example: |
|---|---|---|---|
name | Sorting by filename | This is the default sort. | &sort=name:desc |
created_at | Sorting by the date when the asset has been uploaded in Filerobot. | &sort=created_at:desc | |
modified_at | Sorting by the date of the last edit in Filerobot | The metadata edits are not considered as edits that this filter reflects. It checks only for modifications of the file's content. | &sort=modified_at:desc |
size | Sorting by filesize. | &sort=size:asc | |
type | Grouping assets by mimetype | &sort=type:asc |
Request Params
| Key | Datatype | Required | Description |
|---|---|---|---|
recursive | number | Whether to list/search recursively in the sub-folders. 1 =yes; 0 =No | |
limit | number | Max number of returned results (used for pagination) | |
offset | number | Start offset (for pagination). | |
sort | string | See "Sorting search results" for more info | |
format | string | Format response. please see "format response" in GET file details | |
labels_operator | string | Labels operator when using multiple labels. Acccepted values:OR,AND | |
labels | string | SID of the label. If you want to filter by labels. | |
variant | string | In which language variant to return results. Please check your token configuration for language abbreviation. Alternatively you can do a GET files request and see language abbreviation. | |
mimetype | string | Filter by mimetype | |
resolution | string | Filter by resolution | |
orientation | string | Filter by orientation | |
type | string | Filter by image,video,audio | |
q | string | Search parameter.See search parameter section. | |
size | string | Filter by size of the file (in mb).First value is the lower limit and second value is the upper limit | |
tags | string | Filter by tags.SID of the tag you want to filter by. | |
folder | string | Search in specific folder | |
| `` | null |
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
X-Filerobot-Key | string | Filerobot API key | |
Content-Type | string |
RESPONSES
status: OK
{"status":"success","type":"LIST","base":{"uuid":"20f67ac0-ea7a-5ae9-a844-42cf9b7ae4e4","path":"/Docs","name":"Docs","meta":{},"visibility":{"in_dam":{"set":"public","actual":"all_organisation"},"in_cdn":{"set":"public","actual":"public"}},"updated_at":"2023-07-31T08:45:04","created_at":"2023-07-17T08:33:44","count":{"files_recursive":8,"files_direct":7},"size":{"total_recursive_bytes":2427601,"total_recursive_pretty":"2.32 MB"},"public_icon":"https://scaleflex.cloudimg.io/crop/300x300/x/http://www.airstore.io/assets/dir.png"},"files":[{"uuid":"341c6b77-ad4f-565d-8da7-fb7829850000","name":"flat.jpg","extension":"jpg","size":{"bytes":458988,"pretty":"448.23 KB"},"flags":null,"type":"image/jpeg","info":{"ext":"jpg","area":1151040,"img_h":880,"img_o":"LD","img_w":1308,"img_type":"JPEG","thumbnail":"https://fbmjmuoeb.filerobot.com/.internal/thumbnails/341c6b77-ad4f-565d-8da7-fb7829850000.jpg","img_color_space":"RGB"},"meta":{"title":{"en":"nice flat"},"description":{"en":"the price is negotiable. room for 3"},"id":null,"product-type":"@itm_v1_4905fe8f_1@","color_1":["@itm_v1_b3ac673b_3@"],"details":null,"year":null,"internal":null,"season":null,"approved":true,"release_date":null,"price":null},"tags":{"en":[{"sid":"#tg81221","label":"Clothes hanger"},{"sid":"#tg3885e","label":"360"},{"sid":"#tga63d4","label":"Car"},{"sid":"#tg05997","label":"orange"}],"fr":[{"sid":"#tg81221","label":"Cintre"},{"sid":"#tg3885e","label":"~ 360"},{"sid":"#tga63d4","label":"Voiture"},{"sid":"#tg05997","label":"Orange"}]},"labels":["#lb9kzmglo"],"relevance":1,"visibility":{"in_dam":{"set":"inherited","actual":"all_organisation"},"in_cdn":{"set":"inherited","actual":"public"}},"is_favorite":null,"url":{"public":"https://store.filerobot.com/fbmjmuoeb/Docs/flat.jpg","permalink":"https://api.filerobot.com/fbmjmuoeb/v5/get/341c6b77-ad4f-565d-8da7-fb7829850000","cdn":"https://fbmjmuoeb.filerobot.com/Docs/flat.jpg?vh=1e845d","path":"/Docs/flat.jpg"},"hash":{"sha1":"1e845d7ce4e32afd080b4efee20226d3dc65eb86","blurhash":null},"iptc_xml":{},"created_at":"2023-07-17T08:33:44Z","modified_at":"2023-08-08T09:57:47Z","folder":{"uuid":"20f67ac0-ea7a-5ae9-a844-42cf9b7ae4e4","name":"/Docs"},"product":{"ref":"Name-change-ref","position":"1"}}],"folders":[],"warnings":[],"stats":{"approx_files_count":1,"approx_files_size":458988,"approx_files_count_method":"COUNT_EXACT"},"info":{"atom":"atom011","response_time":{"db_conn":0,"db_query":336,"db_query_core":0,"parse":1}},"api_version":{"hash":"fb3440b980d63376bfcd277b9811349cd7f6280a","datetime":"2023-08-07T23:26:19+07:00"}}