ImageKit API

Authentication

1. Get keys: an account administrator opens Developer options → API keys in the dashboard. Each account has a public key (public_…, safe for client code, used only for client-side uploads) and a private key (private_…, server-only) S23. Revealing a private key requires the user's password; SSO and magic-link users must first set a password S23.
2. Server-side calls: send Authorization: Basic base64("{private_key}:") (note the trailing colon) over HTTPS. A request without a key returns 401; an expired key, a disabled account or an exhausted storage quota returns 403 S22. An unauthenticated GEThttps://api.imagekit.io/v1/files returned 401 with the message that the request "does not contain private API key" S38.
3. Restricted keys: create a key with per-resource access (None, Read only, Read and write) for media management and account management. Account-management APIs (origins, URL endpoints, usage analytics, named transformations, webhooks) require a restricted key with that access; standard keys cannot call them S23.
4. Client-side uploads: the browser or app asks your backend for credentials S26 S90:
   • V1: the backend returns token (unique, never reused), expire (Unix time less than 1 h ahead) and signature = HMAC-SHA1(token + expire, private key).
   • V2 (beta): the backend returns a JWT signed with HS256 using the private key, with kid = public key; its payload includes every upload parameter, so tampering is detected; exp - iat ≤ 3600.
5. MCP OAuth (DAM and Admin servers): the MCP client discovers https://imagekit.io/.well-known/oauth-protected-resource/mcp/{dam|admin}, registers dynamically (/oauth/register), and runs authorization code + PKCE against https://imagekit.io/oauth/authorize and /oauth/token. The user signs in and picks permissions on a consent screen. Grants can be revoked from the user profile S35 S36 S25. A token granted for DAM cannot call Admin tools, and vice versa S13.

Core resources

Derived from the archived OpenAPI file (commit d9244ba, 2026-11-02). Methods and paths are relative to https://api.imagekit.io unless noted S26.

Data model

• File: identified by fileId. Main attributes: name, filePath, url, thumbnail, type, fileType, mime, width/height, size, hasAlpha, video/audio properties (duration, bitRate, codecs), tags, AITags, description, customMetadata (object keyed by field name), embeddedMetadata, customCoordinates, isPrivateFile, isPublished, versionInfo, createdAt, updatedAt S26.
• Version: each re-upload to the same path creates a version with its own versionId. All versions count toward storage S26 S52.
• Folder: path-based (/campaigns/summer/). Folders appear in listings with type=folder S26.
• Custom metadata field: id, name (immutable API key), label, schema (type, default, required, min/max, select options). The reserved field _internal_original_created_datetime preserves original creation dates of migrated assets S26 S42.
• Renditions: not stored objects. Any variant is a delivery URL with transformation parameters (tr: path segment or query). Named transformations are aliases, and post-transformations at upload pre-generate variants S1 S40.
• Taxonomy: flat tags (user tags and AI tags kept separately) plus typed custom metadata. Controlled vocabularies are SingleSelect/MultiSelect options (CSV import over 100 options) S42 S44.

Search & querying

• Endpoint: GET/v1/files with searchQuery in a Lucene-like syntax; when present, searchQuery overrides the simple tags, type and name filters S26 S89.
• Operators: =, : (begins with), IN, NOT =, NOT IN, <, >, <=, >=, EXISTS, NOT EXISTS, HAS (case-insensitive word-token full-text), AND, OR and parentheses S89.
• Fields: id, name, path, type, format, size, width, height, videoDuration, tags, private, published, transparency, createdAt, updatedAt, createdBy, embeddedMetadata.DateTimeOriginal, embeddedMetadata.Keywords, embeddedMetadata.LocationTaken, and customMetadata.{field} for every custom field type S89. Dates accept ISO 8601 or relative units (7d, 2w, 2m, 1y) S89.
• Sorting: name, created, updated, height, width, size, relevance, duration and original creation date, each ascending or descending S26.
• Filters: type (file, file-version, folder, all), fileType (all, image, non-image), path (single folder; subfolders through path in searchQuery) S26.
• Facets / aggregations: none in the API. GET/v1/tags gives tag counts S26.
• Visual / natural-language search: dashboard-only and Enterprise-only; no public REST endpoint S41.
• Page size: max 1,000 per request S26.

Uploads & binaries

• Single request: one multipart POST per file. The file field accepts binary data, a public URL (ImageKit must receive the response headers within 8 s) or Base64 S26. No chunked or resumable upload is documented (Unknown).
• Size limits (per file): images, audio and raw files 25 MB (Free), 40 MB (Lite), 50 MB (Pro); video 100 MB / 300 MB / 2 GB; higher on Enterprise S26 S3.
• Upload-time processing: extensions (remove-bg, google-auto-tagging, aws-auto-tagging, ai-tasks, ai-auto-description), pre-transformation (one, applied before storage) and up to five post-transformations (pre-generated variants), with optional checks (server-side validation) S26 S40.
• Bulk migration: Rclone integration, migration guides and the Upload API from-URL mode S77 S40.
• Downloads / renditions: every file has a delivery url. Private files need signed URLs (signature from the private key, optional expiry). Named transformations can be applied to private assets without signing S68 S40. ZIP downloads (up to 2,000 files and folders) are available in the dashboard and through DAM MCP tools S55 S25.

Events & webhooks

Limits & quirks

• Account-management APIs need a restricted key: a standard key gets no access to origins, URL endpoints, usage analytics, named transformations or webhooks S23.
• Name search is case-sensitive with = and :; use HAS for case-insensitive matching S89.
• Tag counts are eventually consistent: GET/v1/tags usually reflects changes within about a minute S26.
• Usage analytics responses are cached for 5 minutes per account and date range S26.
• Draft uploads: the API reference says uploading in draft state requires a custom Enterprise plan. Unverified The pricing table instead lists draft assets for Pro S3 S26.
• Upload tokens are single-use: reusing a token or JWT, even after a failed request, returns a validation error S26.
• Free-plan downgrade: the "empty media library" helper does not work above 50,000 files or folders; use bulk delete in batches S85.
• Two spec locations: the docs link the older sdk-generation file while the SDKs are generated from the openapi repository Unverified S22 S26 S28.
• Legacy MCP endpoint still answers: on 2026-11-10 https://api-mcp.imagekit.io/mcp still returned a 401 Bearer challenge, although the vendor asks users to move to the DAM and Admin servers S38 S25.

SDKs, tools & code samples

Changelog of the API

Dated from commits to the public OpenAPI repository (latest first) and vendor announcements S26.