ImageKit Managing assets API
The Managing assets API from ImageKit — 12 operation(s) for managing assets.
OpenAPI Specification
openapi: 3.0.3
info:
title: ImageKit Account Management API Managing assets API
version: 1.0.0
description: Checkout [API overview](/docs/api-overview) to learn about ImageKit's APIs, authentication, rate limits, and error codes etc.
contact:
email: developer@imagekit.io
name: ImageKit Team
url: https://imagekit.io
termsOfService: https://imagekit.io/terms/
servers:
- url: https://api.imagekit.io
security:
- basicAuth: []
tags:
- name: Managing assets
paths:
/v1/files/{fileId}/details:
get:
tags:
- Managing assets
operationId: get-file-details
summary: Get file details
description: This API returns an object with details or attributes about the current version of the file.
parameters:
- description: 'The unique `fileId` of the uploaded file. `fileId` is returned in the list and search assets API and upload API.
'
in: path
name: fileId
required: true
schema:
type: string
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: File details object.
content:
application/json:
schema:
$ref: '#/components/schemas/FileDetails'
example:
fileId: 598821f949c0a938d57563bd
type: file
name: file.jpg
filePath: /images/products/file.jpg
tags:
- t-shirt
- round-neck
- sale2019
AITags:
- name: Shirt
confidence: 90.12
source: google-auto-tagging
- name: T-shirt
confidence: 80.12
source: aws-auto-tagging
versionInfo:
id: 598821f949c0a938d57563bd
name: Version 1
isPrivateFile: false
isPublished: true
customCoordinates: null
url: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313
thumbnail: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313&tr=n-ik_ml_thumbnail
fileType: image
mime: image/jpeg
width: 100
height: 100
size: 100
hasAlpha: false
customMetadata:
brand: Nike
color: red
description: A product description
createdAt: '2019-08-24T06:14:41.313Z'
updatedAt: '2019-08-24T06:14:41.313Z'
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested file does not exist.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Your request contains invalid fileId parameter.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
patch:
tags:
- Managing assets
operationId: update-file-details
summary: Update file details
description: 'This API updates the details or attributes of the current version of the file. You can update `tags`, `customCoordinates`, `customMetadata`, publication status, remove existing `AITags` and apply extensions using this API.
'
parameters:
- description: 'The unique `fileId` of the uploaded file. `fileId` is returned in list and search assets API and upload API.
'
in: path
name: fileId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFileRequest'
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: Updated file details object.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/FileDetails'
- type: object
properties:
extensionStatus:
type: object
properties:
google-auto-tagging:
type: string
enum:
- success
- pending
- failed
aws-auto-tagging:
type: string
enum:
- success
- pending
- failed
remove-bg:
type: string
enum:
- success
- pending
- failed
ai-auto-description:
type: string
enum:
- success
- pending
- failed
ai-tasks:
type: string
enum:
- success
- pending
- failed
example:
fileId: 598821f949c0a938d57563bd
type: file
name: file1.jpg
filePath: /images/products/file.jpg
isPublished: true
tags:
- t-shirt
- round-neck
- sale2019
AITags:
- name: Shirt
confidence: 90.12
source: google-auto-tagging
- name: T-shirt
confidence: 80.12
source: aws-auto-tagging
versionInfo:
id: 598821f949c0a938d57563bd
name: Version 1
isPrivateFile: false
customCoordinates: null
url: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313
thumbnail: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313&tr=n-ik_ml_thumbnail
fileType: image
mime: image/jpeg
width: 100
height: 100
size: 100
hasAlpha: false
customMetadata:
brand: Nike
color: red
createdAt: '2019-08-24T06:14:41.313Z'
updatedAt: '2019-08-24T06:14:41.313Z'
extensionStatus:
google-auto-tagging: success
remove-bg: pending
ai-auto-description: success
ai-tasks: success
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested file does not exist.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
- Invalid custom metadata.
- Your request contains invalid fileId parameter.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
errors:
type: object
/v1/files/{fileId}:
delete:
tags:
- Managing assets
operationId: delete-file
summary: Delete file
description: 'This API deletes the file and all its file versions permanently.
Note: If a file or specific transformation has been requested in the past, then the response is cached. Deleting a file does not purge the cache. You can purge the cache using purge cache API.
'
parameters:
- description: 'The unique `fileId` of the uploaded file. `fileId` is returned in list and search assets API and upload API.
'
in: path
name: fileId
required: true
schema:
type: string
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'204':
description: File deleted successfully.
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested file does not exist.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Your request contains invalid fileId parameter.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
/v1/files/batch/deleteByFileIds:
post:
tags:
- Managing assets
operationId: delete-multiple-files
summary: Delete multiple files
description: 'This API deletes multiple files and all their file versions permanently.
Note: If a file or specific transformation has been requested in the past, then the response is cached. Deleting a file does not purge the cache. You can purge the cache using purge cache API.
A maximum of 100 files can be deleted at a time.
'
requestBody:
content:
application/json:
schema:
type: object
required:
- fileIds
properties:
fileIds:
type: array
items:
type: string
description: 'An array of fileIds which you want to delete.
'
example:
fileIds:
- 598821f949c0a938d57563bd
- 598821f949c0a938d57563be
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: Files deleted successfully.
content:
application/json:
schema:
type: object
properties:
successfullyDeletedFileIds:
type: array
items:
type: string
description: 'An array of fileIds that were successfully deleted.
'
'207':
description: Partially successful. Some files were not deleted.
content:
application/json:
schema:
type: object
properties:
successfullyDeletedFileIds:
type: array
items:
type: string
description: 'An array of fileIds that were successfully deleted.
'
errors:
type: array
items:
type: object
properties:
fileId:
type: string
description: Unique identifier of the file that was not deleted.
error:
type: string
description: 'Error message for the file that was not deleted.
'
description: 'An array of fileIds that were not deleted and the error.
'
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
- fileIds parameter is missing.
- fileIds cannot have more than 100 items.
- fileIds should be an Array.
- fileIds is empty.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested file(s) does not exist.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
missingFileIds:
type: array
items:
type: string
description: 'An array of fileIds that were not found.
'
/v1/files/copy:
post:
tags:
- Managing assets
operationId: copy-file
summary: Copy file
description: "This will copy a file from one folder to another. \n\nNote: If any file at the destination has the same name as the source file, then the source file and its versions (if `includeFileVersions` is set to true) will be appended to the destination file version history.\n"
requestBody:
content:
application/json:
schema:
type: object
required:
- sourceFilePath
- destinationPath
properties:
sourceFilePath:
type: string
description: 'The full path of the file you want to copy.
'
example: /path/to/file.jpg
destinationPath:
type: string
description: 'Full path to the folder you want to copy the above file into.
'
example: /folder/to/copy/into/
includeFileVersions:
type: boolean
description: 'Option to copy all versions of a file. By default, only the current version of the file is copied. When set to true, all versions of the file will be copied. Default value - `false`.
'
example: false
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'204':
description: File copied successfully.
content:
application/json:
schema:
type: object
x-stainless-empty-object: true
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
reason:
type: string
example: SOURCE_FILE_MISSING
message:
type: string
example: No file found with filePath `/file1.jpg`.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Your request is missing parameters / contains invalid parameters.
reason:
type: string
examples:
- MISSING_PARAMETER
- SAME_SOURCE_AND_DESTINATION
- VERSION_LIMIT_EXCEEDED
- INVALID_FOLDER_PATH
help:
type: string
example: For support kindly contact us at support@imagekit.io.
/v1/files/move:
post:
tags:
- Managing assets
operationId: move-file
summary: Move file
description: "This will move a file and all its versions from one folder to another. \n\nNote: If any file at the destination has the same name as the source file, then the source file and its versions will be appended to the destination file.\n"
requestBody:
content:
application/json:
schema:
type: object
required:
- sourceFilePath
- destinationPath
properties:
sourceFilePath:
type: string
description: 'The full path of the file you want to move.
'
example: /path/to/file.jpg
destinationPath:
type: string
description: 'Full path to the folder you want to move the above file into.
'
example: /folder/to/move/into/
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'204':
description: File moved successfully.
content:
application/json:
schema:
type: object
x-stainless-empty-object: true
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
reason:
type: string
example: SOURCE_FILE_MISSING
message:
type: string
example: No file found with filePath `/file1.jpg`.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Your request is missing parameters / contains invalid parameters.
reason:
type: string
examples:
- MISSING_PARAMETER
- SAME_SOURCE_AND_DESTINATION
- VERSION_LIMIT_EXCEEDED
- INVALID_FOLDER_PATH
help:
type: string
example: For support kindly contact us at support@imagekit.io.
/v1/files/rename:
put:
tags:
- Managing assets
operationId: rename-file
summary: Rename file
description: "You can rename an already existing file in the media library using rename file API. This operation would rename all file versions of the file. \n\nNote: The old URLs will stop working. The file/file version URLs cached on CDN will continue to work unless a purge is requested.\n"
requestBody:
content:
application/json:
schema:
type: object
required:
- filePath
- newFileName
properties:
filePath:
type: string
description: 'The full path of the file you want to rename.
'
example: /path/to/file.jpg
newFileName:
type: string
description: 'The new name of the file. A filename can contain:
Alphanumeric Characters: `a-z`, `A-Z`, `0-9` (including Unicode letters, marks, and numerals in other languages).
Special Characters: `.`, `_`, and `-`.
Any other character, including space, will be replaced by `_`.
'
example: newFileName.jpg
purgeCache:
type: boolean
description: 'Option to purge cache for the old file and its versions'' URLs.
When set to true, it will internally issue a purge cache request on CDN to remove cached content of old file and its versions. This purge request is counted against your monthly purge quota.
Note: If the old file were accessible at `https://ik.imagekit.io/demo/old-filename.jpg`, a purge cache request would be issued against `https://ik.imagekit.io/demo/old-filename.jpg*` (with a wildcard at the end). It will remove the file and its versions'' URLs and any transformations made using query parameters on this file or its versions. However, the cache for file transformations made using path parameters will persist. You can purge them using the purge API. For more details, refer to the purge API documentation.
Default value - `false`
'
example: true
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: On success, you will receive `purgeRequestId` in the response body, which can be used to get the purge request status. This is only sent if the `purgeCache` is set to `true` in the request. Otherwise, the response is an empty JSON.
content:
application/json:
schema:
type: object
properties:
purgeRequestId:
type: string
description: 'Unique identifier of the purge request. This can be used to check the status of the purge request.
'
'207':
description: In case purgeCache is set to true and total purge request count has exceeded the quota, we will rename the file but won't purge CDN cache.
content:
application/json:
schema:
type: object
properties:
reason:
type: string
example: PURGE_FAILED
message:
type: string
example: File renamed successfully but we could not purge the CDN cache for old URL because of rate limits on purge API.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'404':
description: If no file is found at the specified filePath in the media library, then a 404 response is returned.
content:
application/json:
schema:
type: object
properties:
reason:
type: string
example: FILE_MISSING
message:
type: string
example: No file found in media library at filePath /path/to/file.jpg
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'409':
description: If a file with newFileName already exist in the same location.
content:
application/json:
schema:
type: object
properties:
reason:
type: string
example: FILE_ALREADY_EXISTS
message:
type: string
example: File with name newFileName already exists at the same location.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
reason:
type: string
examples:
- MISSING_PARAMETER
- INVALID_PARAMETER
- SAME_OLD_AND_NEW_NAME
message:
type: string
example: newFileName cannot be the same as its existing name.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
/v1/files/{fileId}/versions:
get:
tags:
- Managing assets
operationId: list-file-versions
summary: List file versions
description: 'This API returns details of all versions of a file.
'
parameters:
- description: 'The unique `fileId` of the uploaded file. `fileId` is returned in list and search assets API and upload API.
'
in: path
name: fileId
required: true
schema:
type: string
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: Array of file version objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FileDetails'
example:
- fileId: 598821f949c0a938d57563bd
type: file
name: file.jpg
filePath: /images/products/file.jpg
tags:
- t-shirt
- round-neck
- sale2019
AITags:
- name: Shirt
confidence: 90.12
source: google-auto-tagging
- name: T-shirt
confidence: 80.12
source: aws-auto-tagging
versionInfo:
id: 598821f949c0a938d57563bd
name: Version 2
isPrivateFile: false
customCoordinates: null
url: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313
thumbnail: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313&tr=n-ik_ml_thumbnail
fileType: image
mime: image/jpeg
width: 100
height: 100
size: 100
hasAlpha: false
customMetadata:
brand: Nike
color: red
createdAt: '2019-08-24T06:14:41.313Z'
updatedAt: '2019-08-24T06:14:41.313Z'
- fileId: 598821f949c0a938d81963bd
type: file-version
name: file.jpg
filePath: /images/products/file.jpg
tags:
- t-shirt
- sale2019
AITags:
- name: Shirt
confidence: 90.12
source: google-auto-tagging
- name: T-shirt
confidence: 80.12
source: aws-auto-tagging
versionInfo:
id: 598821f949c0a938d57563bd
name: Version 1
isPrivateFile: false
customCoordinates: null
url: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?ik-obj-version=iAg8gxkqo_QUBwqNeQrJzuyce2XB7Gc4&updatedAt=1566630881313
thumbnail: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?ik-obj-version=iAg8gxkqo_QUBwqNeQrJzuyce2XB7Gc4&updatedAt=1566630881313&tr=n-ik_ml_thumbnail
fileType: image
mime: image/jpeg
width: 100
height: 100
size: 100
hasAlpha: false
customMetadata:
brand: Nike
color: red
createdAt: '2019-08-24T06:15:41.313Z'
updatedAt: '2019-08-24T06:15:41.313Z'
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested file does not exist.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Your request contains invalid fileId parameter.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
/v1/files/{fileId}/versions/{versionId}:
get:
tags:
- Managing assets
operationId: get-file-version-details
summary: Get file version details
description: This API returns an object with details or attributes of a file version.
parameters:
- description: 'The unique `fileId` of the uploaded file. `fileId` is returned in list and search assets API and upload API.
'
in: path
name: fileId
required: true
schema:
type: string
- description: 'The unique `versionId` of the uploaded file. `versionId` is returned in list and search assets API and upload API.
'
in: path
name: versionId
required: true
schema:
type: string
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: File version details object.
content:
application/json:
schema:
$ref: '#/components/schemas/FileDetails'
examp
# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apis-json-v1-9-imagekit/refs/heads/main/openapi/imagekit-managing-assets-api-openapi.yml