List and search files

get
List and search file API

https://api.imagekit.io/v1/files
This API can list all the uploaded files in your ImageKit.io media library. For searching and filtering, you can use query parameters as described below.
Request
Response
Request
Headers
Authorization
required
string
base64 encoding of your_private_api_key: Note the colon in the end.
Query Parameters
path
optional
string
Folder path if you want to limit the search within a specific folder. For example, /sales-banner/ will only search in folder sales-banner.
fileType
optional
string
Type of files to include in result set. Accepts three values: all - include all types of files in result set image - only search in image type files non-image - only search in files which are not image, e.g., JS or CSS or video files. Default value - all
tags
optional
string
Comma-separated list of tags. Files matching any of the tags are included in result response. If no tag is matched, the file is not included in result set. Example - t-shirt,round-neck,sale2019 will return any files which have either of these three tags, t-shirt or round-neck or sale2019.
includeFolder
optional
string
Whether to include folders in search results or not. By default only files are searched. Accepts true and false. If this is set to true then tags and fileType parameters are ignored.
name
optional
string
The name of the file or folder.
limit
optional
string
The maximum number of results to return in response: Minimum value - 1 Maximum value - 1000 Default value - 1000
skip
optional
string
The number of results to skip before returning results. Minimum value - 0 Default value - 0
Response
200: OK
[
{
"fileId" : "598821f949c0a938d57563bd",
"type": "file",
"name": "file1.jpg",
"filePath": "/images/products/file1.jpg",
"tags": ["t-shirt","round-neck","sale2019"],
"isPrivateFile" : false,
"customCoordinates" : null,
"url": "https://ik.imagekit.io/your_imagekit_id/images/products/file1.jpg",
"thumbnail": "https://ik.imagekit.io/your_imagekit_id/tr:n-media_library_thumbnail/images/products/file1.jpg",
"fileType": "image"
},
...more items
]

Response structure and status code (application/JSON)

In case of error, you will get an error code along with the error message. On success, you will receive a 200 status code with the list of files in JSON-encoded response body.

Understanding response

The JSON-encoded response has an array of items. Each item can have the following properties.

Property name

Description

fileId

The unique fileId of the uploaded file.

type

Type of item. It can be either file or folder.

name

Name of the file or folder.

filePath

The relative path of the file. In the case of an image, you can use this path to construct different transformations.

tags

Array of tags associated with the image. If no tags are set, it will be null.

isPrivateFile

Is the file marked as private. It can be either true or false.

customCoordinates

Value of custom coordinates associated with the image in format x,y,width,height. If customCoordinates are not defined then it is null.

url

A publicly accessible URL of the file.

thumbnail

In case of an image, a small thumbnail URL.

fileType

The type of file, it could be either image or non-image.

Examples

Here are some example requests to understand the API usage.

Fetch 10 files uploaded in media library

cURL
Node.js
Python
PHP
cURL
curl -X GET "https://api.imagekit.io/v1/files?skip=0&limit=10" \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
skip : 0,
limit : 10
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"skip": 0, "limit": 10})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"skip" => 0,
"limit" => 10,
));
echo ("List files : " . json_encode($listFiles));

Search media library files by name

cURL
Node.js
Python
PHP
cURL
curl -X GET "https://api.imagekit.io/v1/files?name=main-banner.jpg" \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
name : "main-banner.jpg"
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"name": "main-banner.jpg"})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"name" => "main-banner.jpg",
));
echo ("List files : " . json_encode($listFiles));

List files within a specific folder

cURL
Node.js
Python
PHP
cURL
curl -X GET "https://api.imagekit.io/v1/files?path=products" \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
path : "products"
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"path": "products"})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"path" => "products",
));
echo ("List files : " . json_encode($listFiles));

Search files by tags

cURL
Node.js
Python
PHP
cURL
curl -X GET "https://api.imagekit.io/v1/files?tags=sale,summer" \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
tags : ["sale","summer"]
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"tags": ["sale","summer"]})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"tags" => implode(",", array("sale", "summer")),
));
echo ("List files : " . json_encode($listFiles));

Limit the search to only image type files

cURL
Node.js
Python
PHP
cURL
curl -X GET "https://api.imagekit.io/v1/files?fileType=image" \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
fileType : "image"
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"fileType": "image"})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"fileType" => "image",
));
echo ("List files : " . json_encode($listFiles));