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' example: 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 version not found. content: application/json: schema: type: object properties: message: type: string example: The requested file version 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: - Your request contains invalid fileId parameter. - Your request contains invalid versionId parameter. help: type: string example: For support kindly contact us at support@imagekit.io. delete: tags: - Managing assets operationId: delete-file-version summary: Delete file version description: 'This API deletes a non-current file version permanently. The API returns an empty response. Note: If you want to delete all versions of a file, use the delete file 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 - 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' '204': description: File version deleted successfully. content: application/json: schema: type: object x-stainless-empty-object: true '400': description: Trying to delete the current version of the file. content: application/json: schema: type: object properties: message: type: string examples: - You cannot delete current version of a file. - Your request contains invalid fileId parameter. - Your request contains invalid versionId parameter. help: type: string example: For support kindly contact us at support@imagekit.io. '404': description: File version found. content: application/json: schema: type: object properties: message: type: string example: The requested asset does not exist. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/files/{fileId}/versions/{versionId}/restore: put: tags: - Managing assets operationId: restore-file-version summary: Restore file version description: 'This API restores a file version as the current 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: Restored 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 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' '404': description: File or file version does not exist. content: application/json: schema: type: object properties: message: type: string example: The requested file version 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: - Your request contains invalid fileId parameter. - Your request contains invalid versionId parameter. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/files/addTags: post: tags: - Managing assets operationId: add-tags-bulk summary: Add tags (bulk) description: 'This API adds tags to multiple files in bulk. A maximum of 50 files can be specified at a time. ' requestBody: content: application/json: schema: type: object required: - fileIds - tags properties: fileIds: type: array items: type: string description: 'An array of fileIds to which you want to add tags. ' tags: type: array items: type: string description: 'An array of tags that you want to add to the files. ' example: fileIds: - 598821f949c0a938d57563bd - 598821f949c0a938d57563be tags: - t-shirt - round-neck - sale2019 responses: '429': $ref: '#/components/responses/RateLimitExceeded' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '200': description: Tags added successfully. content: application/json: schema: type: object properties: successfullyUpdatedFileIds: type: array items: type: string description: 'An array of fileIds that in which tags were successfully added. ' '207': description: Partially successful. Some files were not updated. content: application/json: schema: type: object properties: successfullyUpdatedFileIds: type: array items: type: string description: 'An array of fileIds that were successfully updated. ' errors: type: array items: type: object properties: fileId: type: string description: Unique identifier of the file that was not updated. error: type: string description: 'Error message for the file that was not updated. ' description: 'An array of fileIds that were not updated and the error. ' '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. ' '400': description: Bad Request. content: application/json: schema: type: object properties: message: type: string examples: - fileIds parameter is missing. - fileIds is empty. - A maximum of 50 files can be edited at a time. - fileIds should be an Array. - tags parameter is missing. - tags array cannot be empty. - Your request contains invalid value for tags parameter. Combined length of all tags should be less than or equal to 500. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/files/removeTags: post: tags: - Managing assets operationId: remove-tags-bulk summary: Remove tags (bulk) description: 'This API removes tags from multiple files in bulk. A maximum of 50 files can be specified at a time. ' requestBody: content: application/json: schema: type: object required: - fileIds - tags properties: fileIds: type: array items: type: string description: 'An array of fileIds from which you want to remove tags. ' tags: type: array items: type: string description: 'An array of tags that you want to remove from the files. ' example: fileIds: - 598821f949c0a938d57563bd - 598821f949c0a938d57563be tags: - t-shirt - round-neck - sale2019 responses: '429': $ref: '#/components/responses/RateLimitExceeded' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '200': description: Tags removed successfully. content: application/json: schema: type: object properties: successfullyUpdatedFileIds: type: array items: type: string description: 'An array of fileIds that in which tags were successfully removed. ' '207': description: Partially successful. Some files were not updated. content: application/json: schema: type: object properties: successfullyUpdatedFileIds: type: array items: type: string description: 'An array of fileIds that were successfully updated. ' errors: type: array items: type: object properties: fileId: type: string description: Unique identifier of the file that was not updated. error: type: string description: 'Error message for the file that was not updated. ' description: 'An array of fileIds that were not updated and the error. ' '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. ' '400': description: Bad Request. content: application/json: schema: type: object properties: message: type: string examples: - fileIds parameter is missing. - fileIds is empty. - A maximum of 50 files can be edited at a time. - fileIds should be an Array. - tags parameter is missing. - tags array cannot be empty. - Your request contains invalid value for tags parameter. Combined length of all tags should be less than or equal to 500. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/files/removeAITags: post: tags: - Managing assets operationId: remove-ai-tags-bulk summary: Remove AI tags (bulk) description: 'This API removes AITags from multiple files in bulk. A maximum of 50 files can be specified at a time. ' requestBody: content: application/json: schema: type: object required: - fileIds - AITags properties: fileIds: type: array items: type: string description: 'An array of fileIds from which you want to remove AITags. ' AITags: type: array items: type: string description: 'An array of AITags that you want to remove from the files. ' example: fileIds: - 598821f949c0a938d57563bd - 598821f949c0a938d57563be AITags: - t-shirt - round-neck - sale2019 responses: '429': $ref: '#/components/responses/RateLimitExceeded' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '200': description: AITags removed successfully. content: application/json: schema: type: object properties: successfullyUpdatedFileIds: type: array items: type: string description: 'An array of fileIds that in which AITags were successfully removed. ' '207': description: Partially successful. Some files were not updated. content: application/json: schema: type: object properties: successfullyUpdatedFileIds: type: array items: type: string description: 'An array of fileIds that were successfully updated. ' errors: type: array items: type: object properties: fileId: type: string description: Unique identifier of the file that was not updated. error: type: string description: 'Error message for the file that was not updated. ' description: 'An array of fileIds that were not updated and the error. ' '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. '400': description: Bad Request. content: application/json: schema: type: object properties: message: type: string examples: - fileIds parameter is missing. - fileIds is empty. - A maximum of 50 files can be edited at a time. - fileIds should be an Array. - AITags parameter is missing. - AITags array cannot be empty. - Your request contains invalid value for AITags. Please provide an array of strings. Example - ['t-shirt','summer-sale']. help: type: string example: For support kindly contact us at support@imagekit.io. components: schemas: RemovedotBGExtension: title: Remove background type: object required: - name properties: name: type: string description: Specifies the background removal extension. enum: - remove-bg options: type: object properties: add_shadow: type: boolean description: 'Whether to add an artificial shadow to the result. Default is false. Note: Adding shadows is currently only supported for car photos. ' default: false semitransparency: type: boolean description: 'Allows semi-transparent regions in the result. Default is true. Note: Semitransparency is currently only supported for car windows. ' default: true bg_color: type: string description: 'Specifies a solid color background using hex code (e.g., "81d4fa", "fff") or color name (e.g., "green"). If this parameter is set, `bg_image_url` must be empty. ' bg_image_url: type: string description: 'Sets a background image from a URL. If this parameter is set, `bg_color` must be empty. ' AITaskYesNo: title: AI Task - Yes/No type: object required: - type - instruction properties: type: type: string description: Task type that asks a yes/no question and executes actions based on the answer. enum: - yes_no instruction: type: string minLength: 1 maxLength: 2000 description: The yes/no question for the AI to answer about the image. example: Is this a luxury or high-end fashion item? on_yes: $ref: '#/components/schemas/AITaskAction' description: Actions to execute if the AI answers yes. on_no: $ref: '#/components/schemas/AITaskAction' description: Actions to execute if the AI answers no. on_unknown: $ref: '#/components/schemas/AITaskAction' description: Actions to execute if the AI cannot determine the answer. FileDetails: title: File & File Version description: Object containing details of a file or file version. type: object properties: fileId: type: string description: Unique identifier of the asset. type: type: string description: Type of the asset. enum: - file - file-version name: type: string description: Name of the asset. filePath: type: string description: 'Path of the file. This is the path you would use in the URL to access the file. For example, if the file is at the root of the media library, the path will be `/file.jpg`. If the file is inside a folder named `images`, the path will be `/images/file.jpg`. ' tags: type: array items: type: string description: 'An array of tags assigned to the file. Tags are used to search files in the media library. ' AITags: type: array items: $ref: '#/components/schemas/AITag' description: 'Array of AI-generated tags associated with the image. If no AITags are set, it will be null. ' versionInfo: description: 'An object with details of the file version. ' $ref: '#/components/schemas/VersionInfo' isPrivateFile: type: boolean description: 'Specifies if the file is private or not. ' isPublished: type: boolean description: 'Specifies if the file is published or not. ' customCoordinates: type: string description: 'An string with custom coordinates of the file. ' url: type: string format: uri description: 'URL of the file. ' thumbnail: type: string format: uri description: 'URL of the thumbnail image. This URL is used to access the thumbnail image of the file in the media library. ' fileType: type: string description: 'Type of the file. Possible values are `image`, `non-image`. ' mime: type: string description: 'MIME type of the file. ' width: type: number description: 'Width of the file. ' height: type: number description: 'Height of the file. ' size: type: number description: 'Size of the file in bytes. ' bitRate: type: integer description: The bit rate of the video in kbps (only for video). duration: type: integer description: The duration of the video in seconds (only for video). audioCodec: type: string description: The audio codec used in the video (only for video/audio). videoCodec: type: string description: The video codec used in the video (only for video). hasAlpha: type: boolean description: 'Specifies if the image has an alpha channel. ' customMetadata: description: 'An object with custom metadata for the file. ' $ref: '#/components/schemas/CustomMetadata' selectedFieldsSchema: $ref: '#/components/schemas/SelectedFieldsSchema' embeddedMetadata: $ref: '#/components/schemas/EmbeddedMetadata' description: Consolidated embedded metadata associated with the file. It includes exif, iptc, and xmp data. description: type: string description: 'Optional text to describe the contents of the file. Can be set by the user or the ai-auto-description extension. ' createdAt: type: string format: date-time description: 'Date and time when the file was uploaded. The date and time is in ISO8601 format. ' updatedAt: type: string format: date-time description: 'Date and time when the file was last updated. The date and time is in ISO8601 format. ' AutoTaggingExtension: title: Auto tagging type: object required: - name - minConfidence - maxTags properties: name: type: string enum: - google-auto-tagging - aws-auto-tagging description: Specifies the auto-tagging extension used. minConfidence: type: integer description: Minimum confidence level for tags to be considered valid. maxTags: type: integer description: Maximum number of tags to attach to the asset. AITaskAction: title: AI Task Action type: object description: Defines actions to perform based on AI task results. properties: add_tags: type: array description: Array of tag strings to add to the asset. items: type: string example: - luxury - premium remove_tags: type: array description: Array of tag strings to remove from the asset. items: type: string example: - budget - affordable set_metadata: type: array description: Array of custom metadata field updates. items: type: object required: - field - value properties: field: type: string description: Name of the custom metadata field to set. value: description: Value to set for the custom metadata field. The value type should match the custom metadata field type. oneOf: - type: string - type: number - type: boolean - type: array x-stainless-variantName: Mixed title: Mixed items: title: Metadata value item oneOf: - type: string - type: number - type: boolean example: - field: price_range value: premium unset_metadata: type: array description: Array of custom metadata fields to remove. items: type: object required: - field properties: field: type: string description: Name of the custom metadata field to remove. example: - field: price_range Extensions: title: Extensions Array type: array items: discriminator: propertyName: name anyOf: - $ref: '#/components/schemas/RemovedotBGExtension' - $ref: '#/components/schemas/AutoTaggingExtension' - $ref: '#/components/schemas/AutoDescriptionExtension' - $ref: '#/components/schemas/AITasksExtension' - $ref: '#/components/schemas/SavedExtensionReference' description: 'Array of extensions to be applied to the asset. Each extension can be configured with specific parameters based on the extension type. ' example: - name: remove-bg options: add_shadow: true bg_colour: green - name: google-auto-tagging maxTags: 5 minConfidence: 95 - name: ai-auto-description - name: ai-tasks tasks: - type: select_tags instruction: What types of clothing items are visible in this image? vocabulary: - shirt - tshirt - dress - trousers - jacket - type: yes_no instruction: Is this a luxury or high-end fashion item? on_yes: add_tags: - luxury - premium - name: saved-extension id: ext_abc123 CustomMetadata: type: object description: 'A key-value data associated with the asset. ' additionalProperties: true EmbeddedMetadata: type: object additionalProperties: true description: Consolidated embedded metadata associated with the file. It includes exif, iptc, and xmp data. AITag: type: object properties: name: type: string description: Name of the tag. confidence: type: number description: Confidence score of the tag. source: type: string description: Source of the tag. Possible values are `google-auto-tagging` and `aws-auto-tagging`. description: 'AI-generated tag associated with an image. These tags can be added using the `google-auto-tagging` or `aws-auto-tagging` extensions. ' AITasksExtension: title: AI Tasks type: object required: - name - tasks properties: name: type: string description: Specifies the AI tasks extension for automated image analysis using AI models. enum: - ai-tasks tasks: type: array minItems: 1 maxItems: 10 description: Array of task objects defining AI operations to perform on the asset. items: discriminator: propertyName: type oneOf: - $ref: '#/components/schemas/AITaskSelectTags' - $ref: '#/components/schemas/AITaskSelectMetadata' - $ref: '#/components/schemas/AITaskYesNo' AutoDescriptionExtension: title: Auto description type: object required: - name properties: name: type: string description: Specifies the auto description extension. enum: - ai-auto-description AITaskSelectTags: title: AI Task - Select Tags type: object required: - type - instruction properties: type: type: string description: Task type that analyzes the image and adds matching tags from a vocabulary. enum: - select_tags instruction: type: string minLength: 1 maxLength: 2000 description: The question or instruction for the AI to analyze the image. example: What types of clothing items are visible in this image? vocabulary: type: array minItems: 1 maxItems: 30 description: Array of possible tag values. The combined length of all strings must not exceed 500 characters, and values cannot include the `%` character. When providing large vocabularies (more than 30 items), the AI may not follow the list strictly. items: type: string example: - shirt - tshirt - dress - trousers - jacket min_selections: type: integer minimum: 0 description: Minimum number of tags to select from the vocabulary. max_selections: type: integer minimum: 1 description: Maximum number of tags to select from the vocabulary. VersionInfo: type: object properties: id: type: string description: Unique identifier of the file version. name: type: string description: Name of the file version. description: 'An object containing the file or file version''s `id` (versionId) and `name`. ' SelectedFieldsSchema: type: object description: 'This field is included in the response only if the Path policy feature is available in the plan. It contains schema definitions for the custom metadata fields selected for the specified file path. Field selection can only be done when the Path policy feature is enabled. Keys are the names of the custom metadata fields; the value object has details about the custom metadata schema. ' additionalProperties: type: object required: - type properties: type: description: Type of the custom metadata field. type: string enum: - Text - Textarea - Number - Date - Boolean - SingleSelect - MultiSelect selectOptions: type: array items: oneOf: - type: string - type: number - type: boolean description: 'An array of allowed values when field type is `SingleSelect` or `MultiSelect`. ' example: - small - medium - large - 30 - 40 - true selectOptionsTruncated: type: boolean description: 'Specifies if the selectOptions array is truncated. It is truncated when number of options are > 100. ' defaultValue: description: 'The default value for this custom metadata field. The value should match the `type` of custom metadata field. ' oneOf: - type: string - type: number - type: boolean - type: array x-stainless-variantName: Mixed title: Mixed items: oneOf: - type: string - type: number - type: boolean description: 'Default value should be of type array when custom metadata field type is set to `MultiSelect`. ' example: - true - 10 - Hello isValueRequired: type: boolean description: 'Specifies if the custom metadata field is required or not. ' readOnly: type: boolean description: 'Indicates whether the custom metadata field is read only. A read only field cannot be modified after being set. This field is configurable only via the **Path policy** feature. ' minValue: description: 'Minimum value of the field. Only set if field type is `Date` or `Number`. For `Date` type field, the value will be in ISO8601 string format. For `Number` type field, it will be a numeric value. ' oneOf: - type: string - type: number maxValue: description: 'Maximum value of the field. Only set if field type is `Date` or `Number`. For `Date` type field, the value will be in ISO8601 string format. For `Number` type field, it will be a numeric value. ' oneOf: - type: string - type: number minLength: description: 'Minimum length of string. Only set if `type` is set to `Text` or `Textarea`. ' type: number maxLength: description: 'Maximum length of string. Only set if `type` is set to `Text` or `Textarea`. ' type: number UpdateFileRequest: title: Update file request description: Schema for update file update request. type: object example: removeAITags: - car - vehicle - motorsports webhookUrl: https://webhook.site/0d6b6c7a-8e5a-4b3a-8b7c-0d6b6c7a8e5a extensions: - name: remove-bg options: add_shadow: true - name: google-auto-tagging minConfidence: 80 maxTags: 10 - name: aws-auto-tagging minConfidence: 80 maxTags: 10 - name: ai-auto-description - name: ai-tasks tasks: - type: select_tags instruction: What types of clothing items are visible? vocabulary: - shirt - dress - jacket - name: saved-extension id: ext_abc123 tags: - tag1 - tag2 customCoordinates: 10,10,100,100 customMetadata: brand: Nike color: red oneOf: - title: Update file details type: object properties: removeAITags: oneOf: - type: array items: type: string - type: string enum: - all description: "An array of AITags associated with the file that you want to remove, e.g. `[\"car\", \"vehicle\", \"motorsports\"]`. \n\nIf you want to remove all AITags associated with the file, send a string - \"all\".\n\nNote: The remove operation for `AITags` executes before any of the `extensions` are processed.\n" webhookUrl: type: string format: uri description: 'The final status of extensions after they have completed execution will be delivered to this endpoint as a POST request. [Learn more](/docs/api-reference/digital-asset-management-dam/managing-assets/update-file-details#webhook-payload-structure) about the webhook payload structure. ' extensions: $ref: '#/components/schemas/Extensions' tags: type: array items: type: string description: 'An array of tags associated with the file, such as `["tag1", "tag2"]`. Send `null` to unset all tags associated with the file. ' example: - tag1 - tag2 customCoordinates: type: string description: 'Define an important area in the image in the format `x,y,width,height` e.g. `10,10,100,100`. Send `null` to unset this value. ' customMetadata: type: object description: 'A key-value data to be associated with the asset. To unset a key, send `null` value for that key. Before setting any custom metadata on an asset you have to create the field using custom metadata fields API. ' additionalProperties: true description: type: string description: 'Optional text to describe the contents of the file. ' - title: Change publication status type: object properties: publish: type: object required: - isPublished description: 'Configure the publication status of a file and its versions. ' properties: isPublished: type: boolean description: 'Set to `true` to publish the file. Set to `false` to unpublish the file. ' includeFileVersions: type: boolean description: 'Set to `true` to publish/unpublish all versions of the file. Set to `false` to publish/unpublish only the current version of the file. ' AITaskSelectMetadata: title: AI Task - Select Metadata type: object required: - type - instruction - field properties: type: type: string description: Task type that analyzes the image and sets a custom metadata field value from a vocabulary. enum: - select_metadata instruction: type: string minLength: 1 maxLength: 2000 description: The question or instruction for the AI to analyze the image. example: What is the primary color of the clothing? field: type: string description: Name of the custom metadata field to set. The field must exist in your account. example: primary_color vocabulary: type: array minItems: 1 maxItems: 30 description: An array of possible values matching the custom metadata field type. If not provided for SingleSelect or MultiSelect field types, all values from the custom metadata field definition will be used. When providing large vocabularies (above 30 items), the AI may not strictly adhere to the list. items: oneOf: - type: string - type: number - type: boolean example: - red - blue - green - black - white min_selections: type: integer minimum: 0 description: Minimum number of values to select from the vocabulary. max_selections: type: integer minimum: 1 description: Maximum number of values to select from the vocabulary. SavedExtensionReference: title: Saved Extension Reference type: object required: - name - id properties: name: type: string description: Indicates this is a reference to a saved extension. enum: - saved-extension id: type: string description: The unique ID of the saved extension to apply. example: ext_abc123 responses: Forbidden: description: Forbidden. content: application/json: schema: type: object properties: message: type: string examples: - Your account cannot be authenticated. - Your request contains expired private API key. - Your account is disabled. help: type: string example: For support kindly contact us at support@imagekit.io. Unauthorized: description: Unauthorized request. content: application/json: schema: type: object properties: message: type: string example: Your request does not contain private API key. help: type: string example: For support kindly contact us at support@imagekit.io. RateLimitExceeded: description: The request exceeded the rate limit. Contains headers indicating the limits and a message detailing the error. headers: X-RateLimit-Limit: schema: type: integer description: The maximum number of requests that can be made to this endpoint in the interval specified by `X-RateLimit-Interval` response header. X-RateLimit-Reset: schema: type: integer description: The amount of time in milliseconds before you can make another request to this endpoint. Pause/sleep your workflow for this duration. X-RateLimit-Interval: schema: type: integer description: The duration of the interval in milliseconds for which this rate limit was exceeded. content: application/json: schema: type: object properties: message: type: string description: A description of the error, providing details about why the rate limit has been exceeded. securitySchemes: basicAuth: description: 'Basic HTTP authentication. Allowed headers-- Authorization: Basic | Authorization: Basic ImageKit API uses API keys to authenticate requests. You can view and manage your API keys in [the dashboard](https://imagekit.io/dashboard/developer/api-keys). All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.' scheme: basic type: http