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));

📙API Reference - Previous

Media API

Get file details

Last updated 2 months ago

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`.

List and search files

getList and search file API

Response structure and status code (application/JSON)

Understanding response

Examples

Fetch 10 files uploaded in media library

Search media library files by name

List files within a specific folder

Search files by tags

Limit the search to only image type files

get
List and search file API