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.

If you receive a response status code of 429 (Too Many Requests), 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.

Rate limits are specified for a specific interval. So, if an endpoint allows 100 requests per second (1000 milliseconds), and you exceed this rate, your application will receive a 429 response code. As explained below, every endpoint can have different limits, which are exposed via rate-limiting headers.

A single endpoint can have multiple limits, for example, a 100 request per second limit along with 1000 limits for a 15-minute duration.

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.