ImageKit API Overview

ImageKit.io offers REST APIs to programmatically integrate ImageKit.io into your application, especially the integrated Digital Asset Management or the media storage called the Media Library. Currently, APIs are available for the following operations.

• File Upload APIs - Upload files to the ImageKit Media Library from the server or client side.
• Digital Asset Management APIs - Build a Headless DAM solution by natively integrating the ImageKit Media Library with search, list, copy, move, and other operations exposed via APIs.
• File Metadata APIs - Get a file's metadata by its file ID or URL.
• Custom Metadata Fields APIs - Create, read, and update custom metadata fields in your ImageKit Media Library via APIs. These fields can then be updated for your files via the Update File or Upload File API.
• Cache Management APIs - Initiate cache purge requests and check their status via APIs.
• Account Management APIs - Get the usage for your account between two dates.

All these methods are available in our backend SDKs. We recommend using the SDKs for a more straightforward integration with your code. Upload APIs can also be used from the client side.

Except for upload API, all our APIs accept JSON-encoded request bodies and return JSON-encoded responses.

We’ve created a Postman collection to simplify testing and working with our API.

Here is the OpenAPI specification for v1 version of ImageKit's API.

ImageKit.io API uses standard HTTP error codes.

All API responses contain a x-ik-requestId header. This header's value is a unique identifier associated with the API request. If you encounter any issues with any API, provide this header value in your support ticket to help us troubleshoot the issue quickly. This is also exposed in all SDKs as part of the response object. Please refer to the respective SDK documentation for more details.

Your API requests are authenticated using the account's private API key. If you do not include your key when making an API request or use an incorrect one, we return an error. You can view your API keys in the ImageKit.io dashboard under the developer's tab.

Authentication to the API is performed via HTTP Basic Auth. Provide your private API key as the basic auth username value. You do not need to provide a password.

You can provide the private API key in a curl request as:

curl https://api.imagekit.io/v1/files \ 
-u your_private_api_key:
# The colon prevents curl from asking for a password.

You can also use the "Authorization" header and provide base64 encoded value of the string
your_private_api_key:

If you encode your_private_api_key: using base64, you will get eW91cl9wcml2YXRlX2FwaV9rZXk6

curl https://api.imagekit.io/v1/files \
 -H 'Authorization: Basic eW91cl9wcml2YXRlX2FwaV9rZXk6'

Except for the upload API, all our APIs are rate-limited to protect our infrastructure from excessive request rates and to keep ImageKit.io fast and stable for everyone.

Rate limiting is done across the account. When you exceed the rate limits for an endpoint, you will receive a 429 (Too many requests) response code.

Rate limiting is based on two primary thresholds:

1. Burst (short-term): A limit on how many requests can be sent in a very short window (for example, per second).
2. Sustained (long-term): A limit on how many requests can be sent over a longer window (for example, per minute).

When your requests exceed either the burst or the sustained threshold for a given endpoint, you’ll receive an HTTP 429 Too Many Requests response. In that case, please sleep/pause for the number of milliseconds specified by the value of X-RateLimit-Reset response header before making additional requests to that endpoint.

Based on the majority of standard file and folder endpoints:

• Reads: Stay near or below 40 requests/second on average. This remains comfortably under our common per-minute limit and leaves headroom for short bursts. Most read operations allow bursts of up to 100 requests/second.
• Writes: Aim for 5-20 requests/second on average. Many write operations allow bursts of up to 100 requests/second, but some endpoints have tighter caps e.g. add bulk tags, remove bulk tags, custom metadata fields CRUD operations, etc, which are limited to 5 requests/second.

You will also receive the following response headers in response to every API request that hits the rate limit. Use these headers to stay within rate limits or pause/sleep your workflow in case you exceed them.

If your workflow demands a higher rate limit, please contact us at support@imagekit.io.