openapi: 3.1.0 info: title: ImageKit 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 paths: /v1/dummy/test: post: summary: Dummy test endpoint using all shared models operationId: create-dummy-test description: | Internal test endpoint for SDK generation purposes only. This endpoint demonstrates usage of all shared models defined in the Stainless configuration and is not intended for public consumption. tags: - Dummy Test requestBody: required: true content: application/json: schema: type: object properties: extensions: $ref: '#/components/schemas/Extensions' savedExtensions: $ref: '#/components/schemas/SavedExtension' extensionConfig: $ref: '#/components/schemas/ExtensionConfig' srcOptions: $ref: '#/components/schemas/SrcOptions' getImageAttributesOptions: $ref: '#/components/schemas/GetImageAttributesOptions' responsiveImageAttributes: $ref: '#/components/schemas/ResponsiveImageAttributes' transformation: $ref: '#/components/schemas/Transformation' transformationPosition: $ref: '#/components/schemas/TransformationPosition' streamingResolution: $ref: '#/components/schemas/StreamingResolution' overlay: $ref: '#/components/schemas/Overlay' baseOverlay: $ref: '#/components/schemas/BaseOverlay' overlayPosition: $ref: '#/components/schemas/OverlayPosition' overlayTiming: $ref: '#/components/schemas/OverlayTiming' textOverlay: $ref: '#/components/schemas/TextOverlay' imageOverlay: $ref: '#/components/schemas/ImageOverlay' videoOverlay: $ref: '#/components/schemas/VideoOverlay' subtitleOverlay: $ref: '#/components/schemas/SubtitleOverlay' solidColorOverlay: $ref: '#/components/schemas/SolidColorOverlay' textOverlayTransformation: $ref: '#/components/schemas/TextOverlayTransformation' subtitleOverlayTransformation: $ref: '#/components/schemas/SubtitleOverlayTransformation' solidColorOverlayTransformation: $ref: '#/components/schemas/SolidColorOverlayTransformation' responses: "204": description: No content - Request processed successfully with empty response "400": description: Bad request content: application/json: schema: type: object properties: error: type: string example: "Invalid input data" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v1/files/upload: servers: - url: https://upload.imagekit.io post: tags: - Upload File operationId: upload-file summary: Upload file V1 description: | ImageKit.io allows you to upload files directly from both the server and client sides. For server-side uploads, private API key authentication is used. For client-side uploads, generate a one-time `token`, `signature`, and `expire` from your secure backend using private API. [Learn more](/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload) about how to implement client-side file upload. The [V2 API](/docs/api-reference/upload-file/upload-file-v2) enhances security by verifying the entire payload using JWT. **File size limit** \ On the free plan, the maximum upload file sizes are 25MB for images, audio, and raw files and 100MB for videos. On the Lite paid plan, these limits increase to 40MB for images, audio, and raw files and 300MB for videos, whereas on the Pro paid plan, these limits increase to 50MB for images, audio, and raw files and 2GB for videos. These limits can be further increased with enterprise plans. **Version limit** \ A file can have a maximum of 100 versions. **Demo applications** - A full-fledged [upload widget using Uppy](https://github.com/imagekit-samples/uppy-uploader), supporting file selections from local storage, URL, Dropbox, Google Drive, Instagram, and more. - [Quick start guides](/docs/quick-start-guides) for various frameworks and technologies. requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/FileUploadV1" responses: "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: File uploaded successfully. content: application/json: schema: $ref: "#/components/schemas/Upload" examples: Simple image file: value: $ref: "#/components/examples/UploadResponseImage" Simple video file: value: $ref: "#/components/examples/UploadResonseVideo" Image with EmbeddedMetadata: value: $ref: "#/components/examples/UploadResponseWithEmbeddedMetadata" "202": description: File accepted for upload. Pre transformation for video is being processed. content: application/json: schema: type: object properties: message: type: string example: The pre-transformation has been queued successfully. "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string examples: - Your request is missing file parameter. - Your request contains both signature and basic auth parameter. Use only one method, you might be exposing your private API key. - Your request contains invalid expire parameter. Expire parameter should be a Unix time in less than 1 hour into the future. - A file with the same name already exists at the exact location. We could not overwrite it because both overwriteFile and useUniqueFileName are set to false. - Your request contains invalid file parameter. The file size exceeds limits. - Upload Limit Exceeded. - Extensions quota exceeded. - The file could not be uploaded because the transformation field is invalid. - The file could not be uploaded because transformations are supported only for image and video files. - The file could not be uploaded because the detected file type & post-transformation are incompatible. - You have sent too many requests to update the file recently. Please try again later. - Your request contains invalid syntax for the checks parameter. - Your request failed 'checks' validation. help: type: string example: For support kindly contact us at support@imagekit.io. /api/v2/files/upload: servers: - url: https://upload.imagekit.io post: tags: - Upload File operationId: upload-file-v2 summary: Upload file V2 description: | The V2 API enhances security by verifying the entire payload using JWT. This API is in beta. ImageKit.io allows you to upload files directly from both the server and client sides. For server-side uploads, private API key authentication is used. For client-side uploads, generate a one-time `token` from your secure backend using private API. [Learn more](/docs/api-reference/upload-file/upload-file-v2#how-to-implement-secure-client-side-file-upload) about how to implement secure client-side file upload. **File size limit** \ On the free plan, the maximum upload file sizes are 25MB for images, audio, and raw files, and 100MB for videos. On the Lite paid plan, these limits increase to 40MB for images, audio, and raw files and 300MB for videos, whereas on the Pro paid plan, these limits increase to 50MB for images, audio, and raw files and 2GB for videos. These limits can be further increased with enterprise plans. **Version limit** \ A file can have a maximum of 100 versions. **Demo applications** - A full-fledged [upload widget using Uppy](https://github.com/imagekit-samples/uppy-uploader), supporting file selections from local storage, URL, Dropbox, Google Drive, Instagram, and more. - [Quick start guides](/docs/quick-start-guides) for various frameworks and technologies. requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/FileUploadV2" responses: "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: File uploaded successfully. content: application/json: schema: $ref: "#/components/schemas/Upload" examples: Simple image file: value: $ref: "#/components/examples/UploadResponseImage" Simple video file: value: $ref: "#/components/examples/UploadResonseVideo" Image with EmbeddedMetadata: value: $ref: "#/components/examples/UploadResponseWithEmbeddedMetadata" "202": description: File accepted for upload. Pre transformation for video is being processed. content: application/json: schema: type: object properties: message: type: string example: The pre-transformation has been queued successfully. "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string examples: - Your request is missing file parameter. - Your request contains both token and basic auth parameter. Use only one method, you might be exposing your private API key. - Your request contains invalid payload. It does not match with the payload used to generate token. - Your request is missing token parameter. - Your request contains expired token. - Your request has invalid token. - A file with the same name already exists at the exact location. We could not overwrite it because both overwriteFile and useUniqueFileName are set to false. - Your request contains invalid file parameter. The file size exceeds limits. - Upload Limit Exceeded. - Extensions quota exceeded. - The file could not be uploaded because the transformation field is invalid. - The file could not be uploaded because transformations are supported only for image and video files. - The file could not be uploaded because the detected file type & post-transformation are incompatible. - You have sent too many requests to update the file recently. Please try again later. - Your request contains invalid syntax for the checks parameter. - Your request failed 'checks' validation. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/customMetadataFields: post: summary: Create new field operationId: create-new-field description: | This API creates a new custom metadata field. Once a custom metadata field is created either through this API or using the dashboard UI, its value can be set on the assets. The value of a field for an asset can be set using the media library UI or programmatically through upload or update assets API. requestBody: content: application/json: schema: type: object required: - name - label - schema properties: name: type: string description: | API name of the custom metadata field. This should be unique across all (including deleted) custom metadata fields. `_internal_original_created_datetime` is a reserved name and cannot be used. ImageKit creates that field automatically when you enable the original creation date setting in the media library settings. label: type: string description: Human readable name of the custom metadata field. This should be unique across all non deleted custom metadata fields. This name is displayed as form field label to the users while setting field value on an asset in the media library UI. description: type: string maxLength: 500 description: | Optional description for the custom metadata field. Can be up to 500 characters. This is shown as a hint to the users while setting the field's value on an asset in the media library UI. schema: 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. This property is only required if `type` property is set to `SingleSelect` or `MultiSelect`. example: - small - medium - large - 30 - 40 - true defaultValue: description: | The default value for this custom metadata field. This property is only required if `isValueRequired` property is set to `true`. 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: title: Default value item 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: | Sets this custom metadata field as required. Setting custom metadata fields on an asset will throw error if the value for all required fields are not present in upload or update asset API request body. minValue: description: | Minimum value of the field. Only set this property if field type is `Date` or `Number`. For `Date` type field, set the minimum date in ISO8601 string format. For `Number` type field, set the minimum numeric value. oneOf: - type: string - type: number maxValue: description: | Maximum value of the field. Only set this property if field type is `Date` or `Number`. For `Date` type field, set the minimum date in ISO8601 string format. For `Number` type field, set the minimum numeric value. oneOf: - type: string - type: number minLength: description: | Minimum length of string. Only set this property if `type` is set to `Text` or `Textarea`. type: number maxLength: description: | Maximum length of string. Only set this property if `type` is set to `Text` or `Textarea`. type: number example: name: price label: price schema: type: Number minValue: 1000 maxValue: 3000 responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "201": description: Custom metadata field created successfully. content: application/json: schema: $ref: "#/components/schemas/CustomMetadataField" example: id: 598821f949c0a938d57563dd name: price label: price schema: type: Number minValue: 1000 maxValue: 3000 "400": description: Bad Request. content: application/json: schema: type: object properties: message: type: string example: A custom metadata field with this name already exists. help: type: string example: For support kindly contact us at support@imagekit.io. tags: - Digital Asset Management (DAM) - Custom metadata fields get: tags: - Digital Asset Management (DAM) - Custom metadata fields operationId: list-all-fields summary: List all fields description: | This API returns the array of created custom metadata field objects. By default the API returns only non deleted field objects, but you can include deleted fields in the API response. You can also filter results by a specific folder path to retrieve custom metadata fields applicable at that location. This path-specific filtering is useful when using the **Path policy** feature to determine which custom metadata fields are selected for a given path. parameters: - in: query description: | Set it to `true` to include deleted field objects in the API response. name: includeDeleted required: false schema: type: boolean default: false - in: query description: | The folder path (e.g., `/path/to/folder`) for which to retrieve applicable custom metadata fields. Useful for determining path-specific field selections when the [Path policy](https://imagekit.io/docs/dam/path-policy) feature is in use. name: folderPath required: false schema: type: string responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: Array of custom metadata field objects. content: application/json: schema: type: array items: $ref: "#/components/schemas/CustomMetadataField" example: - id: 598821f949c0a938d57563dd name: brand label: brand schema: type: Text defaultValue: Nike - id: 865421f949c0a835d57563dd name: price label: price schema: type: Number minValue: 1000 maxValue: 3000 /v1/files/{fileId}/details: get: tags: - Digital Asset Management (DAM) - 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: - Digital Asset Management (DAM) - 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/customMetadataFields/{id}: patch: tags: - Digital Asset Management (DAM) - Custom metadata fields operationId: update-existing-field summary: Update existing field description: | This API updates the label, description, or schema of an existing custom metadata field. parameters: - description: | Should be a valid custom metadata field id. in: path name: id required: true schema: type: string requestBody: content: application/json: schema: type: object properties: label: type: string description: Human readable name of the custom metadata field. This should be unique across all non deleted custom metadata fields. This name is displayed as form field label to the users while setting field value on an asset in the media library UI. This parameter is required if `schema` is not provided. description: type: string maxLength: 500 description: | Optional description for the custom metadata field. Can be up to 500 characters. Send an empty string to clear an existing description. This is shown as a hint to the users while setting the field's value on an asset in the media library UI. schema: type: object description: | An object that describes the rules for the custom metadata key. This parameter is required if `label` is not provided. Note: `type` cannot be updated and will be ignored if sent with the `schema`. The schema will be validated as per the existing `type`. properties: selectOptions: type: array items: oneOf: - type: string - type: number - type: boolean description: | An array of allowed values. This property is only required if `type` property is set to `SingleSelect` or `MultiSelect`. example: - small - medium - large - 30 - 40 - true defaultValue: description: | The default value for this custom metadata field. This property is only required if `isValueRequired` property is set to `true`. 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: title: Default value item 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: | Sets this custom metadata field as required. Setting custom metadata fields on an asset will throw error if the value for all required fields are not present in upload or update asset API request body. minValue: description: | Minimum value of the field. Only set this property if field type is `Date` or `Number`. For `Date` type field, set the minimum date in ISO8601 string format. For `Number` type field, set the minimum numeric value. oneOf: - type: string - type: number maxValue: description: | Maximum value of the field. Only set this property if field type is `Date` or `Number`. For `Date` type field, set the minimum date in ISO8601 string format. For `Number` type field, set the minimum numeric value. oneOf: - type: string - type: number minLength: description: | Minimum length of string. Only set this property if `type` is set to `Text` or `Textarea`. type: number maxLength: description: | Maximum length of string. Only set this property if `type` is set to `Text` or `Textarea`. type: number example: label: price schema: type: Number minValue: 1000 maxValue: 3000 responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string examples: - Cannot update a deleted custom metadata fields. - Either label, description or schema should be provided. - A custom metadata field with this label already exists. - description must be a string - description must be at most 500 characters - Invalid schema object. - Name cannot be updated. - Missing id parameter. - Your request contains invalid ID parameter. help: type: string example: For support kindly contact us at support@imagekit.io. "404": description: Custom metadata field doesn't exist. content: application/json: schema: type: object properties: message: type: string example: No such custom metadata field exists. help: type: string example: For support kindly contact us at support@imagekit.io. "200": description: Custom metadata field updated successfully. content: application/json: schema: $ref: "#/components/schemas/CustomMetadataField" example: id: 598821f949c0a938d57563dd name: price label: price schema: type: Number minValue: 1000 maxValue: 3000 delete: tags: - Digital Asset Management (DAM) - Custom metadata fields operationId: delete-a-field summary: Delete a field description: | This API deletes a custom metadata field. Even after deleting a custom metadata field, you cannot create any new custom metadata field with the same name. parameters: - description: | Should be a valid custom metadata field id. in: path name: id required: true schema: type: string responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string examples: - Missing id parameter. - Your request contains invalid ID parameter. - "This custom metadata field cannot be deleted as it is a part of a path policy: policy-name" help: type: string example: For support kindly contact us at support@imagekit.io. "404": description: Custom metadata field doesn't exist. content: application/json: schema: type: object properties: message: type: string example: No such custom metadata field exists. help: type: string example: For support kindly contact us at support@imagekit.io. "204": description: Custom metadata field deleted successfully. /v1/files: get: tags: - Digital Asset Management (DAM) operationId: list-and-search-assets summary: List and search assets description: | This API can list all the uploaded files and folders in your ImageKit.io media library. In addition, you can fine-tune your query by specifying various filters by generating a query string in a Lucene-like syntax and provide this generated string as the value of the `searchQuery`. parameters: - in: query name: type required: false description: | Filter results by asset type. - `file` — returns only files - `file-version` — returns specific file versions - `folder` — returns only folders - `all` — returns both files and folders (excludes `file-version`) schema: type: string enum: - file - file-version - folder - all default: file - in: query name: sort required: false description: | Sort the results by one of the supported fields in ascending or descending order. `ASC_ORIGINAL_CREATION_DATE` and `DESC_ORIGINAL_CREATION_DATE` sort files by the value of the reserved `_internal_original_created_datetime` custom metadata field (labelled "Original creation date" in the dashboard). This field exists only after you enable the original creation date setting under the Custom Metadata tab of the media library settings. Files that have no value set for this field fall back to their upload time, so migrated assets carrying a preserved original date and natively uploaded assets are ordered together in a single timeline. schema: type: string enum: - ASC_NAME - DESC_NAME - ASC_CREATED - DESC_CREATED - ASC_UPDATED - DESC_UPDATED - ASC_HEIGHT - DESC_HEIGHT - ASC_WIDTH - DESC_WIDTH - ASC_SIZE - DESC_SIZE - ASC_RELEVANCE - DESC_RELEVANCE - ASC_DURATION - DESC_DURATION - ASC_ORIGINAL_CREATION_DATE - DESC_ORIGINAL_CREATION_DATE default: ASC_CREATED - in: query name: path required: false description: | Folder path if you want to limit the search within a specific folder. For example, `/sales-banner/` will only search in folder sales-banner. Note : If your use case involves searching within a folder as well as its subfolders, you can use `path` parameter in `searchQuery` with appropriate operator. Checkout [Supported parameters](/docs/api-reference/digital-asset-management-dam/list-and-search-assets#supported-parameters) for more information. schema: type: string - in: query name: searchQuery required: false description: | Query string in a Lucene-like query language e.g. `createdAt > "7d"`. Note : When the searchQuery parameter is present, the following query parameters will have no effect on the result: 1. `tags` 2. `type` 3. `name` [Learn more](/docs/api-reference/digital-asset-management-dam/list-and-search-assets#advanced-search-queries) from examples. schema: type: string - in: query name: fileType required: false description: | Filter results by file type. - `all` — include all file types - `image` — include only image files - `non-image` — include only non-image files (e.g., JS, CSS, video) schema: type: string enum: - all - image - non-image default: all - in: query name: limit required: false description: | The maximum number of results to return in response. schema: type: integer minimum: 1 maximum: 1000 default: 1000 - in: query name: skip required: false description: | The number of results to skip before returning results. schema: type: integer minimum: 0 default: 0 responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: List of assets. content: application/json: schema: type: array items: discriminator: propertyName: type mapping: file: "#/components/schemas/FileDetails" "file-version": "#/components/schemas/FileDetails" folder: "#/components/schemas/FolderDetails" oneOf: - $ref: "#/components/schemas/FileDetails" - $ref: "#/components/schemas/FolderDetails" 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" - folderId: 6441fce4e809dd54b0dee029 type: folder name: summer createdAt: "2023-04-21T03:03:00.869Z" updatedAt: "2023-04-21T03:10:22.374Z" folderPath: "/sale" "400": description: Bad Request. content: application/json: schema: type: object properties: message: type: string examples: - The value of skip parameter should be greater than or equal to 0. Value sent is -1. - Minimum value of limit parameter is 1. Value sent is 0. - Maximum value of limit parameter is 1000. Value sent is 2000. - Your request contains invalid value for sort parameters. - "Your request contains invalid value for type parameter. Please provide one of the following: file, file-version, folder, all." - sd help: type: string example: For support kindly contact us at support@imagekit.io. /v1/files/{fileId}: delete: tags: - Digital Asset Management (DAM) - 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: - Digital Asset Management (DAM) - 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: - Digital Asset Management (DAM) - Managing assets operationId: copy-file summary: Copy file description: | This will copy a file from one folder to another. Note: 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. 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. "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: - Digital Asset Management (DAM) - Managing assets operationId: move-file summary: Move file description: | This will move a file and all its versions from one folder to another. Note: 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. 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. "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: - Digital Asset Management (DAM) - 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. Note: The old URLs will stop working. The file/file version URLs cached on CDN will continue to work unless a purge is requested. 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: - Digital Asset Management (DAM) - 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: - Digital Asset Management (DAM) - 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: - Digital Asset Management (DAM) - 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. "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: - Digital Asset Management (DAM) - 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: - Digital Asset Management (DAM) - 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: - Digital Asset Management (DAM) - 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: - Digital Asset Management (DAM) - 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. /v1/tags: get: tags: - Digital Asset Management (DAM) operationId: list-tags summary: List tags description: | This API lists the distinct tags in use across your media library, with the number of assets each tag is applied to and when it was last used. Tags are matched case-insensitively, so `Summer` and `summer` are one entry: `name` is the lowercased form and `label` is the spelling that was used most recently. Use `tagSource` and `fileType` to list only the tags in use on matching assets. `lastUsedAt` and the `ASC_LAST_USED` / `DESC_LAST_USED` sorts follow those filters, while `assetCount` always counts every asset carrying the tag. Use `search` or `prefix` to narrow the listing and `cursor` to page through it. Tag counts are updated asynchronously. Changes to a file's tags usually appear in this list within about a minute, but can take longer during heavy tagging activity, so a tag you just added or removed may not be reflected immediately. parameters: - in: query name: tagSource required: false description: | Filter tags by who added them. - `user` — tags added by users through the dashboard or the API - `ai` — tags added by AI auto-tagging extensions - `all` — both schema: type: string enum: - user - ai - all default: all - in: query name: fileType required: false description: | Filter tags by the type of asset they are applied to. - `image` — tags in use on images - `video` — tags in use on videos - `static` — tags in use on any other file, such as documents, scripts and stylesheets - `all` — tags in use on any asset schema: type: string enum: - image - video - static - all default: all - in: query name: prefix required: false description: | Only return tags that begin with this value. Matching is case-insensitive. schema: type: string maxLength: 100 - in: query name: search required: false description: | Only return tags that contain this text. Every word in the value must appear in the tag and the last word may be incomplete, which suits search-as-you-type. Matching is case-insensitive. schema: type: string maxLength: 100 - in: query name: sort required: false description: | Sort the results. - `ASC_NAME` / `DESC_NAME` — by `name` - `ASC_LAST_USED` / `DESC_LAST_USED` — by `lastUsedAt` within the requested `tagSource` and `fileType`, ties broken by `name` schema: type: string enum: - ASC_NAME - DESC_NAME - ASC_LAST_USED - DESC_LAST_USED default: ASC_NAME - in: query name: limit required: false description: | The maximum number of tags to return in response. schema: type: integer minimum: 1 maximum: 1000 default: 1000 x-stainless-pagination-property: purpose: max_per_page - in: query name: cursor required: false description: | The `nextCursor` value from the previous response, to fetch the next page. A cursor is bound to the `tagSource`, `fileType`, `sort`, `search` and `prefix` it was issued with; sending it with different values returns a 400. schema: type: string x-stainless-pagination-property: purpose: next_cursor_param responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: A page of tags. content: application/json: schema: type: object properties: tags: type: array description: Tags matching the request, in the requested order. items: $ref: "#/components/schemas/Tag" x-stainless-pagination-property: purpose: items nextCursor: type: [ string, null ] description: Cursor for the next page, or `null` when there are no more tags. x-stainless-pagination-property: purpose: next_cursor_field required: - tags - nextCursor example: tags: - name: round-neck label: round-neck lastUsedAt: "2026-10-20T08:31:12.000Z" assetCount: 42 - name: sale2019 label: Sale2019 lastUsedAt: "2026-10-18T14:02:55.000Z" assetCount: 7 - name: t-shirt label: T-Shirt lastUsedAt: "2026-10-21T10:15:03.000Z" assetCount: 128 nextCursor: eyJmIjoiYWxsOmFsbCIsInMiOiJBU0NfTkFNRSIsInEiOm51bGwsInAiOm51bGwsImEiOlsidC1zaGlydCJdfQ "400": description: Bad Request. content: application/json: schema: type: object properties: message: type: string examples: - Your request contains invalid value for tagSource parameter. Allowed values are ai, user, all. - Your request contains invalid value for fileType parameter. Allowed values are image, video, static, all. - Your request contains invalid value for sort parameter. Allowed values are ASC_NAME, DESC_NAME, ASC_LAST_USED, DESC_LAST_USED. - Your request contains invalid value for prefix parameter. Maximum length is 100 characters. - Your request contains invalid value for search parameter. Maximum length is 100 characters. - Your request contains invalid value for limit parameter. It must be an integer between 1 and 1000. - Your request contains invalid value for cursor parameter. Use the nextCursor value from a previous response with the same tagSource, fileType, sort, search and prefix. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/folder: post: tags: - Digital Asset Management (DAM) - Managing folders operationId: create-folder summary: Create folder description: | This will create a new folder. You can specify the folder name and location of the parent folder where this new folder should be created. requestBody: content: application/json: schema: type: object required: - folderName - parentFolderPath properties: folderName: type: string description: | The folder will be created with this name. All characters except alphabets and numbers (inclusive of unicode letters, marks, and numerals in other languages) will be replaced by an underscore i.e. `_`. parentFolderPath: type: string description: | The folder where the new folder should be created, for root use `/` else the path e.g. `containing/folder/`. Note: If any folder(s) is not present in the parentFolderPath parameter, it will be automatically created. For example, if you pass `/product/images/summer`, then `product`, `images`, and `summer` folders will be created if they don't already exist. example: folderName: summer parentFolderPath: /product/images/ responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "201": description: Folder created successfully. content: application/json: schema: type: object x-stainless-empty-object: true "400": description: Bad Request. content: application/json: schema: type: object properties: reason: type: string example: INVALID_FOLDER_PATH message: type: string example: "'.' & '..' can not be used as folder-name" help: type: string example: For support kindly contact us at support@imagekit.io. delete: tags: - Digital Asset Management (DAM) - Managing folders operationId: delete-folder summary: Delete folder description: | This will delete a folder and all its contents permanently. The API returns an empty response. requestBody: content: application/json: schema: type: object required: - folderPath properties: folderPath: type: string description: | Full path to the folder you want to delete. For example `/folder/to/delete/`. example: folderPath: /folder/to/delete/ responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "204": description: Folder deleted successfully. "404": description: Folder not found content: application/json: schema: type: object properties: reason: type: string example: FOLDER_NOT_FOUND message: type: string example: No folder found with folderPath `/folder/to/delete/`. 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 example: TOO_MANY_OBJECTS message: type: string example: Total nested assets (files, folders and file versions) are more than allowed limit of 100000 items. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/bulkJobs/copyFolder: post: tags: - Digital Asset Management (DAM) - Managing folders operationId: copy-folder summary: Copy folder description: | This will copy one folder into another. The selected folder, its nested folders, files, and their versions (in `includeVersions` is set to true) are copied in this operation. Note: 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 version history. requestBody: content: application/json: schema: type: object required: - sourceFolderPath - destinationPath properties: sourceFolderPath: type: string description: | The full path to the source folder you want to copy. example: /path/of/source/folder destinationPath: type: string description: | Full path to the destination folder where you want to copy the source folder into. example: /path/of/destination/folder includeVersions: type: boolean description: | Option to copy all versions of files that are nested inside the selected folder. By default, only the current version of each file will be copied. When set to true, all versions of each file will be copied. Default value - `false`. example: true responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": content: application/json: schema: $ref: "#/components/schemas/JobResponse" "404": description: Folder not found content: application/json: schema: type: object properties: reason: type: string example: NO_FILES_FOLDER message: type: string example: No files & folder found at sourceFolderPath `/folder/to/copy`. 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: sourceFolderPath and destinationPath is same reason: type: string examples: - MISSING_PARAMETER - INVALID_PARAMETER - TOO_MANY_OBJECTS - SOURCE_IS_ROOT - SAME_SOURCE_AND_DESTINATION - INVALID_FOLDER_PATH help: type: string example: For support kindly contact us at support@imagekit.io. "423": description: Locked resource - A bulk operation is currently running on the folder. content: application/json: schema: type: object properties: message: type: string examples: - A bulk job is running on given folder path, please try after sometime. - Destination folder path is already locked. Please try after sometime. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/bulkJobs/moveFolder: post: tags: - Digital Asset Management (DAM) - Managing folders operationId: move-folder summary: Move folder description: | This will move one folder into another. The selected folder, its nested folders, files, and their versions are moved in this operation. Note: 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 version history. requestBody: content: application/json: schema: type: object required: - sourceFolderPath - destinationPath properties: sourceFolderPath: type: string description: | The full path to the source folder you want to move. example: /path/of/source/folder destinationPath: type: string description: | Full path to the destination folder where you want to move the source folder into. example: /path/of/destination/folder responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": content: application/json: schema: $ref: "#/components/schemas/JobResponse" "404": description: Folder not found content: application/json: schema: type: object properties: reason: type: string example: NO_FILES_FOLDER message: type: string example: No files & folder found at sourceFolderPath `/folder/to/move`. 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: This operation is not allowed because parent folder cannot be moved into child folder. reason: type: string examples: - MISSING_PARAMETER - INVALID_PARAMETER - TOO_MANY_OBJECTS - SOURCE_IS_ROOT - SAME_SOURCE_AND_DESTINATION - INVALID_FOLDER_PATH - INVALID_DESTINATION_PATH help: type: string example: For support kindly contact us at support@imagekit.io. "423": description: Locked resource - A bulk operation is currently running on the folder. content: application/json: schema: type: object properties: message: type: string examples: - A bulk job is running on given folder path, please try after sometime. - Destination folder path is already locked. Please try after sometime. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/bulkJobs/renameFolder: post: tags: - Digital Asset Management (DAM) - Managing folders operationId: rename-folder summary: Rename folder description: | This API allows you to rename an existing folder. The folder and all its nested assets and sub-folders will remain unchanged, but their paths will be updated to reflect the new folder name. requestBody: content: application/json: schema: type: object required: - folderPath - newFolderName properties: folderPath: type: string description: | The full path to the folder you want to rename. example: /path/of/folder newFolderName: type: string description: | The new name for the folder. All characters except alphabets and numbers (inclusive of unicode letters, marks, and numerals in other languages) and `-` will be replaced by an underscore i.e. `_`. example: new-folder-name purgeCache: type: boolean description: | Option to purge cache for the old nested files and their versions' URLs. When set to true, it will internally issue a purge cache request on CDN to remove the cached content of the old nested files and their versions. There will only be one purge request for all the nested files, which will be counted against your monthly purge quota. Note: A purge cache request will be issued against `https://ik.imagekit.io/old/folder/path*` (with a wildcard at the end). This will remove all nested files, their versions' URLs, and any transformations made using query parameters on these files or their 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: "202": content: application/json: schema: $ref: "#/components/schemas/JobResponse" "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string examples: - folderPath cannot be root. - folderPath parameter is missing. help: type: string example: For support kindly contact us at support@imagekit.io. "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": description: Folder not found content: application/json: schema: type: object properties: message: type: string example: Source folder not found. help: type: string example: For support kindly contact us at support@imagekit.io. "409": description: If a folder with newFileName already exist in the same location. content: application/json: schema: type: object properties: message: type: string example: Folder with name newFolderName already exists at the same location. help: type: string example: For support kindly contact us at support@imagekit.io. "423": description: Locked resource - A bulk operation is currently running on the folder. content: application/json: schema: type: object properties: message: type: string examples: - A bulk job is running on given folder path, please try after sometime. help: type: string example: For support kindly contact us at support@imagekit.io. "429": $ref: "#/components/responses/RateLimitExceeded" /v1/bulkJobs/{jobId}: get: tags: - Digital Asset Management (DAM) - Managing folders operationId: bulk-job-status summary: Bulk job status description: | This API returns the status of a bulk job like copy and move folder operations. parameters: - description: | The `jobId` is returned in the response of bulk job API e.g. copy folder or move folder API. in: path name: jobId required: true schema: type: string responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: | On success, you will receive the status of the bulk job in the response body. content: application/json: schema: type: object properties: jobId: type: string description: | Unique identifier of the bulk job. type: type: string description: | Type of the bulk job. enum: - COPY_FOLDER - MOVE_FOLDER - RENAME_FOLDER status: type: string description: | Status of the bulk job. enum: - Pending - Completed purgeRequestId: type: string description: | Unique identifier of the purge request. This will be present only if `purgeCache` is set to `true` in the rename folder API request. example: jobId: 5d5b1a9b4c8c4c0001f3e4a2 type: COPY_FOLDER status: Completed "207": description: | Partial success – the folder was renamed, but purge cache failed for nested files. It is only returned when `purgeCache` is set `true` in the rename folder API request. content: application/json: schema: type: object properties: jobId: type: string description: | Unique identifier of the bulk job. type: type: string description: | Type of the bulk job. It is only possible for `RENAME_FOLDER`. status: type: string description: | Status of the bulk job. It will be `Partial success`. message: type: string example: Folder renamed successfully but purging cache on nested files failed. help: type: string example: For support kindly contact us at support@imagekit.io. example: jobId: 5d5b1a9b4c8c4c0001f3e4a2 type: RENAME_FOLDER status: Partial success message: Folder renamed successfully but purging cache on nested files failed. help: For support kindly contact us at support@imagekit.io. "404": description: Job not found content: application/json: schema: type: object properties: message: type: string example: The requested job does not exist. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/files/purge: post: tags: - Caching operationId: purge-cache summary: Purge cache description: | This API will purge CDN cache and ImageKit.io's internal cache for a file. Note: Purge cache is an asynchronous process and it may take some time to reflect the changes. requestBody: content: application/json: schema: type: object required: - url properties: url: type: string format: uri description: | The full URL of the file to be purged. example: https://ik.imagekit.io/your_imagekit_id/default-image.jpg responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "201": description: Purge request submitted successfully. A `requestId` will be returned. content: application/json: schema: type: object properties: requestId: type: string description: | Unique identifier of the purge request. This can be used to check the status of the purge request. "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string example: The URL is not valid for cache purging. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/files/purge/{requestId}: get: tags: - Caching operationId: purge-status summary: Get purge status description: | This API returns the status of a purge cache request. parameters: - description: | Should be a valid requestId. in: path name: requestId required: true schema: type: string responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: | On success, you will receive the status of the purge request in the response body. content: application/json: schema: type: object properties: status: type: string example: Completed enum: - Pending - Completed description: | Status of the purge request. "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string example: No request found for this requestId. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/files/{fileId}/metadata: get: tags: - File Metadata operationId: get-uploaded-file-metadata summary: Get uploaded file metadata description: | You can programmatically get image EXIF, pHash, and other metadata for uploaded files in the ImageKit.io media library using this API. You can also get the metadata in upload API response by passing `metadata` in `responseFields` parameter. 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 metadata object. content: application/json: schema: $ref: "#/components/schemas/Metadata" examples: Image: value: $ref: "#/components/examples/ImageMetadata" Video: value: $ref: "#/components/examples/VideoMetadata" "404": description: File not found. content: application/json: schema: type: object properties: message: type: string example: The requested file does not exist or is inaccessible at this time. 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: The requested file is corrupt or invalid. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/metadata: get: tags: - File Metadata operationId: get-metadata-from-url summary: Get metadata from remote URL description: | Get image EXIF, pHash, and other metadata from ImageKit.io powered remote URL using this API. parameters: - description: | Should be a valid file URL. It should be accessible using your ImageKit.io account. in: query name: url required: true schema: type: string format: uri responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: File metadata object. content: application/json: schema: $ref: "#/components/schemas/Metadata" examples: Image: value: $ref: "#/components/examples/ImageMetadata" Video: value: $ref: "#/components/examples/VideoMetadata" "404": description: File not found. content: application/json: schema: type: object properties: message: type: string example: The requested file does not exist or is inaccessible at this time. 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: The url should be accessible using your ImageKit.io account. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/saved-extensions: get: tags: - Digital Asset Management (DAM) - Saved Extensions operationId: list-extensions summary: List all saved extensions description: | This API returns an array of all saved extensions for your account. Saved extensions allow you to save complex extension configurations and reuse them by referencing them by ID in upload or update file APIs. responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: Array of saved extension objects. content: application/json: schema: type: array items: $ref: "#/components/schemas/SavedExtension" post: tags: - Digital Asset Management (DAM) - Saved Extensions operationId: create-extension summary: Create saved extension description: | This API creates a new saved extension. Saved extensions allow you to save complex extension configurations (like AI tasks) and reuse them by referencing the ID in upload or update file APIs. **Saved extension limit** \ You can create a maximum of 100 saved extensions per account. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateSavedExtension" responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "201": description: Saved extension created successfully. content: application/json: schema: $ref: "#/components/schemas/SavedExtension" "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string example: Invalid extension configuration. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/saved-extensions/{id}: get: tags: - Digital Asset Management (DAM) - Saved Extensions operationId: get-extension summary: Get saved extension details description: | This API returns details of a specific saved extension by ID. parameters: - in: path name: id required: true schema: type: string description: | The unique ID of the saved extension. responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: Saved extension details. content: application/json: schema: $ref: "#/components/schemas/SavedExtension" "404": description: Saved extension not found. content: application/json: schema: type: object properties: message: type: string example: The requested saved extension 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: Invalid saved extension ID. help: type: string example: For support kindly contact us at support@imagekit.io. patch: tags: - Digital Asset Management (DAM) - Saved Extensions operationId: update-extension summary: Update saved extension description: | This API updates an existing saved extension. You can update the name, description, or config. parameters: - in: path name: id required: true schema: type: string description: | The unique ID of the saved extension. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateSavedExtension" responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "200": description: Saved extension updated successfully. content: application/json: schema: $ref: "#/components/schemas/SavedExtension" "404": description: Saved extension not found. content: application/json: schema: type: object properties: message: type: string example: The requested saved extension 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: Invalid extension configuration. help: type: string example: For support kindly contact us at support@imagekit.io. delete: tags: - Digital Asset Management (DAM) - Saved Extensions operationId: delete-extension summary: Delete saved extension description: | This API deletes a saved extension permanently. parameters: - in: path name: id required: true schema: type: string description: | The unique ID of the saved extension. responses: "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "204": description: Saved extension deleted successfully. "404": description: Saved extension not found. content: application/json: schema: type: object properties: message: type: string example: The requested saved extension 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: Invalid saved extension ID. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/accounts/usage: get: tags: - Account Management API operationId: get-usage summary: Get account usage information description: | Get the account usage information between two dates. Note that the API response includes data from the start date while excluding data from the end date. In other words, the data covers the period starting from the specified start date up to, but not including, the end date. For an agency account, the returned usage is aggregated across the agency and all of its child accounts that are billed to it. The response is cached for 6 hours per account, date range and requested metrics. parameters: - in: query name: startDate description: Specify a `startDate` in `YYYY-MM-DD` format. It should be before the `endDate`. The difference between `startDate` and `endDate` should be less than 90 days. schema: type: string format: date required: true - in: query name: endDate description: Specify a `endDate` in `YYYY-MM-DD` format. It should be after the `startDate`. The difference between `startDate` and `endDate` should be less than 90 days. schema: type: string format: date required: true responses: "200": description: In the response, you will get different usage metrics. content: application/json: schema: type: object properties: bandwidthBytes: type: integer description: Amount of bandwidth used in bytes. mediaLibraryStorageBytes: type: integer description: Storage used by media library in bytes. videoProcessingUnitsCount: type: integer description: Number of video processing units used. extensionUnitsCount: type: integer description: Number of extension units used. originalCacheStorageBytes: type: integer description: Storage used by the original cache in bytes. examples: default: value: bandwidthBytes: 21991583578 mediaLibraryStorageBytes: 1878758298 videoProcessingUnitsCount: 0 extensionUnitsCount: 0 originalCacheStorageBytes: 0 "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string examples: - startDate and endDate should be within 90 days - startDate and endDate are required in query parameters - startDate and endDate should be in format YYYY-MM-DD - startDate should be before endDate help: type: string example: "For support kindly contact us at support@imagekit.io ." "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /v1/accounts/origins: get: summary: List origins tags: - Account Management API - Origins operationId: list-origins description: > **Note:** This API is currently in beta. Returns an array of all configured origins for the current account. responses: "200": description: Successful response. content: application/json: schema: type: array items: $ref: "#/components/schemas/OriginResponse" "401": &a1 $ref: "#/components/responses/Unauthorized" "403": &a2 $ref: "#/components/responses/Forbidden" "429": &a3 $ref: "#/components/responses/RateLimitExceeded" post: summary: Create origin tags: - Account Management API - Origins operationId: create-origin description: > **Note:** This API is currently in beta. Creates a new origin and returns the origin object. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OriginRequest" responses: "201": description: Origin created successfully. content: application/json: schema: $ref: "#/components/schemas/OriginResponse" "400": description: Bad request. The request body is invalid. content: application/json: schema: type: object properties: message: type: string examples: - Invalid origin type. Must be one of S3, S3_COMPATIBLE, CLOUDINARY_BACKUP, WEB_FOLDER, WEB_PROXY, GCS, AZURE_BLOB, AKENEO_PIM. - name is required and must be a string - bucket is required and must be a string help: type: string example: For support kindly contact us at support@imagekit.io. "401": *a1 "403": *a2 "429": *a3 "/v1/accounts/origins/{id}": get: summary: Get origin tags: - Account Management API - Origins operationId: get-origin description: > **Note:** This API is currently in beta. Retrieves the origin identified by `id`. parameters: - &a4 in: path name: id schema: description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/OriginResponse" "401": *a1 "403": *a2 "404": description: Resource not found content: application/json: schema: type: object properties: message: type: string examples: - Origin not found. help: type: string example: For support kindly contact us at support@imagekit.io. "429": *a3 put: summary: Update origin tags: - Account Management API - Origins operationId: update-origin description: > **Note:** This API is currently in beta. Updates the origin identified by `id` and returns the updated origin object. parameters: - *a4 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OriginRequest" responses: "200": description: Origin updated successfully. content: application/json: schema: $ref: "#/components/schemas/OriginResponse" "400": description: Bad request. The request body is invalid. content: application/json: schema: type: object properties: message: type: string examples: - Invalid origin type. Must be one of S3, S3_COMPATIBLE, CLOUDINARY_BACKUP, WEB_FOLDER, WEB_PROXY, GCS, AZURE_BLOB, AKENEO_PIM. - name is required and must be a string - bucket is required and must be a string help: type: string example: For support kindly contact us at support@imagekit.io. "401": *a1 "403": *a2 "404": description: Resource not found content: application/json: schema: type: object properties: message: type: string examples: - Origin not found. help: type: string example: For support kindly contact us at support@imagekit.io. "429": *a3 delete: summary: Delete origin tags: - Account Management API - Origins operationId: delete-origin description: > **Note:** This API is currently in beta. Permanently removes the origin identified by `id`. If the origin is in use by any URL‑endpoints, the API will return an error. parameters: - *a4 responses: "204": description: Origin deleted successfully. "401": *a1 "403": *a2 "404": description: Resource not found content: application/json: schema: type: object properties: message: type: string examples: - Origin not found. help: type: string example: For support kindly contact us at support@imagekit.io. "429": *a3 /v1/accounts/url-endpoints: get: summary: List URL‑endpoints tags: - Account Management API - URL endpoints operationId: list-url-endpoints description: > **Note:** This API is currently in beta. Returns an array of all URL‑endpoints configured including the default URL-endpoint generated by ImageKit during account creation. responses: "200": description: Successful response. content: application/json: schema: type: array items: $ref: "#/components/schemas/UrlEndpointResponse" "401": *a1 "403": *a2 "404": description: Resource not found content: application/json: schema: type: object properties: message: type: string examples: - URL-endpoint not found. help: type: string example: For support kindly contact us at support@imagekit.io. "429": *a3 post: summary: Create URL‑endpoint tags: - Account Management API - URL endpoints operationId: create-url-endpoint description: > **Note:** This API is currently in beta. Creates a new URL‑endpoint and returns the resulting object. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UrlEndpointRequest" responses: "201": description: URL‑endpoint created successfully. content: application/json: schema: $ref: "#/components/schemas/UrlEndpointResponse" "400": description: Bad request. The request body is invalid. content: application/json: schema: type: object properties: message: type: string examples: - description is required - urlPrefix must be a string - urlPrefix cannot be empty string. This is reserved for the default URL-endpoint created by ImageKit. - Origin does not exists. Please create origin before using it in URL-endpoint. help: type: string example: For support kindly contact us at support@imagekit.io. "401": *a1 "403": *a2 "429": *a3 "/v1/accounts/url-endpoints/{id}": get: summary: Get URL‑endpoint tags: - Account Management API - URL endpoints operationId: get-url-endpoint description: > **Note:** This API is currently in beta. Retrieves the URL‑endpoint identified by `id`. parameters: - &a5 in: path name: id schema: description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`. type: string required: true description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`. responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/UrlEndpointResponse" "401": *a1 "403": *a2 "404": description: Resource not found content: application/json: schema: type: object properties: message: type: string examples: - URL-endpoint not found. help: type: string example: For support kindly contact us at support@imagekit.io. "429": *a3 put: summary: Update URL‑endpoint tags: - Account Management API - URL endpoints operationId: update-url-endpoint description: > **Note:** This API is currently in beta. Updates the URL‑endpoint identified by `id` and returns the updated object. parameters: - *a5 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UrlEndpointRequest" responses: "200": description: URL‑endpoint updated successfully. content: application/json: schema: $ref: "#/components/schemas/UrlEndpointResponse" "400": description: Bad request. The request body is invalid. content: application/json: schema: type: object properties: message: type: string examples: - description is required - urlPrefix must be a string - urlPrefix cannot be empty string. This is reserved for the default URL-endpoint created by ImageKit. - Origin does not exists. Please create origin before using it in URL-endpoint. help: type: string example: For support kindly contact us at support@imagekit.io. "401": *a1 "403": *a2 "404": description: Resource not found content: application/json: schema: type: object properties: message: type: string examples: - URL-endpoint not found. help: type: string example: For support kindly contact us at support@imagekit.io. "429": *a3 delete: summary: Delete URL‑endpoint tags: - Account Management API - URL endpoints operationId: delete-url-endpoint description: > **Note:** This API is currently in beta. Deletes the URL‑endpoint identified by `id`. You cannot delete the default URL‑endpoint created by ImageKit during account creation. parameters: - *a5 responses: "204": description: URL‑endpoint deleted successfully. "400": description: Bad request. The request body is invalid. content: application/json: schema: type: object properties: message: type: string examples: - Default URL-endpoint cannot be deleted. help: type: string example: For support kindly contact us at support@imagekit.io. "401": *a1 "403": *a2 "404": description: Resource not found content: application/json: schema: type: object properties: message: type: string examples: - URL-endpoint not found. help: type: string example: For support kindly contact us at support@imagekit.io. "429": *a3 /v1/accounts/usage-analytics: get: operationId: get-usage-analytics summary: Get usage analytics description: | **Note:** This API is currently in beta. Get the account analytics data between two dates. The response covers the period from the start date to the end date, both dates inclusive. Both dates are interpreted as UTC calendar days. The returned data is scoped to the requesting account only. Unlike `/v1/accounts/usage`, an agency account's analytics are not aggregated across its child accounts. The response is cached for 5 minutes per account and date range. Use `generatedAt` to check how fresh the returned data is. tags: - Account Management API parameters: - in: query name: startDate required: true description: > Specify a `startDate` in `YYYY-MM-DD` format, interpreted as a UTC calendar day. It should be before the `endDate`. The difference between `startDate` and `endDate` should be less than 90 days. schema: type: string format: date example: "2026-06-28" - in: query name: endDate required: true description: > Specify an `endDate` in `YYYY-MM-DD` format, interpreted as a UTC calendar day. It should be after the `startDate`. The difference between `startDate` and `endDate` should be less than 90 days. schema: type: string format: date example: "2026-06-30" responses: "200": description: Usage analytics for the requested date range. content: application/json: schema: $ref: "#/components/schemas/UsageAnalyticsResponse" example: startDate: "2026-06-28" endDate: "2026-06-30" generatedAt: "2026-07-04T09:12:33Z" requestCount: 18442310 bandwidthBytes: 21985004312 statusCodes: - name: "200" requestCount: 18012400 - name: "404" requestCount: 271430 errorReasons: - name: asset-not-found requestCount: 261488 - name: signature-invalid requestCount: 84210 top404Assets: - name: https://ik.imagekit.io/demo/products/discontinued-sku-4421.jpg requestCount: 88210 - name: https://ik.imagekit.io/demo/img/legacy/logo-old.svg requestCount: 17204 extensions: - name: remove-bg operationCount: 980 - name: genfill operationCount: 100 cache: hitCount: 17150348 missCount: 1198320 errorCount: 93642 videoProcessing: - resolution: SD codec: h264 durationSeconds: 600 - resolution: HD codec: h264 durationSeconds: 1000 - resolution: HD codec: av1 durationSeconds: 400 - resolution: "4K" codec: h264 durationSeconds: 200 country: byRequests: - code: IN name: India requestCount: 9120400 bandwidthBytes: 9855012340 - code: US name: United States requestCount: 4210330 bandwidthBytes: 6120458821 byBandwidth: - code: IN name: India requestCount: 9120400 bandwidthBytes: 9855012340 - code: US name: United States requestCount: 4210330 bandwidthBytes: 6120458821 format: byRequests: - name: image/avif requestCount: 10204112 bandwidthBytes: 6122504430 - name: image/webp requestCount: 6120033 bandwidthBytes: 7943310022 byBandwidth: - name: image/webp requestCount: 6120033 bandwidthBytes: 7943310022 - name: image/avif requestCount: 10204112 bandwidthBytes: 6122504430 device: byRequests: - name: "Desktop - Apple Mac" requestCount: 11204488 bandwidthBytes: 11020448120 byBandwidth: - name: "Desktop - Linux PC" requestCount: 6811222 bandwidthBytes: 10412030448 browser: byRequests: - name: Chrome requestCount: 12010448 bandwidthBytes: 14012448821 byBandwidth: - name: Chrome requestCount: 12010448 bandwidthBytes: 14012448821 urlEndpoints: byRequests: - name: Default requestCount: 14200110 bandwidthBytes: 16820044120 - name: ecommerce requestCount: 4242200 bandwidthBytes: 5164960192 byBandwidth: - name: Default requestCount: 14200110 bandwidthBytes: 16820044120 - name: ecommerce requestCount: 4242200 bandwidthBytes: 5164960192 topImages: byRequests: - name: https://ik.imagekit.io/demo/products/hero-banner.jpg requestCount: 820441 bandwidthBytes: 410220500 byBandwidth: - name: https://ik.imagekit.io/demo/catalog/summer/shoe-01.png requestCount: 611230 bandwidthBytes: 733476000 topVideos: byRequests: - name: https://ik.imagekit.io/demo/promos/launch-2026.mp4 requestCount: 44210 bandwidthBytes: 2210500000 byBandwidth: - name: https://ik.imagekit.io/demo/promos/launch-2026.mp4 requestCount: 44210 bandwidthBytes: 2210500000 topOtherAssets: byRequests: - name: https://ik.imagekit.io/demo/docs/spec-sheet.pdf requestCount: 9021 bandwidthBytes: 45210330 byBandwidth: - name: https://ik.imagekit.io/demo/docs/spec-sheet.pdf requestCount: 9021 bandwidthBytes: 45210330 topImageTransforms: byRequests: - name: "tr:w-400,h-400,fo-auto" requestCount: 3120448 bandwidthBytes: 1204488210 byBandwidth: - name: "tr:w-1200,q-80,f-auto" requestCount: 2210330 bandwidthBytes: 3310220400 topVideoTransforms: byRequests: - name: "tr:h-720,f-mp4" requestCount: 38210 bandwidthBytes: 1820440200 byBandwidth: - name: "tr:sr-240_360_480_720" requestCount: 12044 bandwidthBytes: 2210338100 topReferrers: byRequests: - name: https://imagekit.io requestCount: 10204488 bandwidthBytes: 12010448821 byBandwidth: - name: https://ik.imagekit.io requestCount: 10204488 bandwidthBytes: 12010448821 topUserAgents: byRequests: - name: "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5) AppleWebKit/605.1.15" requestCount: 5120448 bandwidthBytes: 4210338210 byBandwidth: - name: "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5) AppleWebKit/605.1.15" requestCount: 5120448 bandwidthBytes: 4210338210 "400": description: Bad request. content: application/json: schema: type: object properties: message: type: string examples: - startDate and endDate should be within 90 days - startDate and endDate are required in query parameters - startDate and endDate should be in format YYYY-MM-DD - startDate should be before endDate help: type: string example: "For support kindly contact us at support@imagekit.io ." "401": *a1 "403": *a2 "429": *a3 /v1/accounts/contract: get: tags: - Account Management API operationId: get-contract summary: Get contract consumption description: | Get the account's contract terms and the usage consumed against them in the current contract term. Bandwidth is in bytes; video processing units, extension units and purge cache requests are counts. For an agency account, consumption includes the child accounts billed to it. A child account billed to its parent cannot call this endpoint; call it with the parent account's credentials instead. Contract terms are read live; consumption is refreshed periodically, not on every request. Use `asOf` to check how fresh it is. Contracts of one month or less are reported as `hasContract: false`. The response is cached for 5 minutes per account. Requires an API key with account management access. responses: "200": description: Contract terms and consumption. content: application/json: schema: type: object required: - hasContract properties: hasContract: type: boolean description: Whether the account has an active contract. The other fields are present only when it does. contractMonths: type: integer description: Length of each contract term in months. originalContractStartDate: type: string format: date description: Start date of the first contract term. effectiveContractStartDate: type: string format: date description: Start date of the current contract term. It moves forward when the contract renews. effectiveContractEndDate: type: string format: date description: End date of the current contract term. quota: $ref: "#/components/schemas/ContractUnits" description: Usage included in the current contract term. consumed: $ref: "#/components/schemas/ContractUnits" description: Usage consumed in the current contract term. For an agency account, this includes the child accounts billed to it. asOf: type: [ string, null ] format: date-time description: When `consumed` was last computed. `null` if it has not been computed for the contract yet; `consumed` is then all zeros. examples: default: value: hasContract: true contractMonths: 12 originalContractStartDate: "2025-04-01" effectiveContractStartDate: "2026-04-01" effectiveContractEndDate: "2027-03-31" quota: bandwidthBytes: 536870912000000 videoProcessingUnitsCount: 2000000 extensionUnitsCount: 100000 purgeCacheRequests: 0 consumed: bandwidthBytes: 229190589617275 videoProcessingUnitsCount: 812004 extensionUnitsCount: 40211 purgeCacheRequests: 0 asOf: "2026-10-27T09:00:00.000Z" noContract: value: hasContract: false "429": $ref: "#/components/responses/RateLimitExceeded" "401": $ref: "#/components/responses/Unauthorized" "403": 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. - This account is billed to its parent account. Contract details are available on the parent account. help: type: string example: For support kindly contact us at support@imagekit.io. /v1/named-transformations: get: summary: List named transformations tags: - Account Management API - Named Transformations operationId: list-named-transformations description: | Returns an array of all named transformations configured for your account. responses: "200": description: Array of named transformation objects. content: application/json: schema: type: array items: $ref: "#/components/schemas/NamedTransformation" example: - &a9 id: "6bZ9x2ZUx" name: "small_thumbnail" transformation: "w-150,h-150,fo-center,cm-pad_resize" enabled: true createdAt: "2024-01-10T09:00:00.000Z" "401": *a1 "403": *a2 "429": *a3 post: summary: Create named transformation tags: - Account Management API - Named Transformations operationId: create-named-transformation description: | Creates a new named transformation and returns the created object. A named transformation is a short, reusable name for a transformation string. Use it in image and video URLs as `tr:n-`, and update the underlying transformation later without changing existing URLs. Learn more about [named transformations](https://imagekit.io/docs/transformations#named-transformations). You can create up to 250 named transformations per account. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateNamedTransformation" example: name: "small_thumbnail" transformation: "w-150,h-150,fo-center,cm-pad_resize" enabled: true responses: "201": description: Named transformation created successfully. content: application/json: schema: $ref: "#/components/schemas/NamedTransformation" example: *a9 "400": description: Bad request. The request body failed validation. content: application/json: schema: type: object properties: message: type: string examples: - "`name` is required and may contain only alphanumeric characters or '_'." - "`transformation` is required and cannot be empty." - "`transformation` is invalid. `transformation` contains an invalid or unsupported transformation string." - "`transformation` cannot include a named transformation reference." - "Your request must not contain any additional properties." - "You have reached the maximum limit of 250 named transformations allowed per account." help: &a10 type: string example: For support kindly contact us at support@imagekit.io. "409": description: A named transformation with this name already exists. content: application/json: schema: type: object properties: message: type: string example: "A named transformation with the name 'small_thumbnail' already exists." help: *a10 "401": *a1 "403": *a2 "429": *a3 "/v1/named-transformations/{id}": get: summary: Get named transformation tags: - Account Management API - Named Transformations operationId: get-named-transformation description: Retrieves the named transformation identified by `id`. parameters: - &a6 in: path name: id required: true description: Unique identifier of the named transformation. This is the `id` returned when the named transformation was created. schema: $ref: "#/components/schemas/NamedTransformationIdField" responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/NamedTransformation" example: *a9 "400": &a11 description: Bad request. The `id` path parameter is malformed. content: application/json: schema: type: object properties: message: type: string example: Invalid `id` in path parameter. help: *a10 "401": *a1 "403": *a2 "404": &a8 description: Named transformation not found. content: application/json: schema: type: object properties: message: type: string example: 'Named transformation with id "6bZ9x2ZUx" not found.' help: *a10 "429": *a3 patch: summary: Update named transformation tags: - Account Management API - Named Transformations operationId: update-named-transformation description: | Updates the named transformation identified by `id` and returns the updated object. Only the fields present in the request body are updated; other fields stay unchanged. Renaming or disabling a named transformation fails with a `409` error if it is still referenced (via the `n-` token) by an upload pre-transformation or post-transformation setting. This check is best-effort and can't detect references in your own application code or in previously generated URLs. parameters: - *a6 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateNamedTransformation" example: transformation: "w-200,h-200,fo-center,cm-pad_resize" enabled: false responses: "200": description: Named transformation updated successfully. content: application/json: schema: $ref: "#/components/schemas/NamedTransformation" example: id: "6bZ9x2ZUx" name: "small_thumbnail" transformation: "w-200,h-200,fo-center,cm-pad_resize" enabled: false createdAt: "2024-01-10T09:00:00.000Z" "400": description: Bad request. The request body or `id` path parameter failed validation. content: application/json: schema: type: object properties: message: type: string examples: - "`name` may contain only alphanumeric characters or '_'." - "`transformation` is invalid. `transformation` contains an invalid or unsupported transformation string." - "`transformation` cannot include a named transformation reference." - "Your request must not contain any additional properties." - "Invalid `id` in path parameter." help: *a10 "401": *a1 "403": *a2 "404": *a8 "409": description: The new name is already taken, or this named transformation is still referenced elsewhere (see the description above). content: application/json: schema: type: object properties: message: type: string examples: - "A named transformation with the name 'small_thumbnail' already exists." - 'Named transformation "small_thumbnail" cannot be renamed because it is referenced by an upload pre-transformation or post-transformation setting.' - 'Named transformation "small_thumbnail" cannot be disabled because it is referenced by an upload pre-transformation or post-transformation setting.' help: *a10 "429": *a3 delete: summary: Delete named transformation tags: - Account Management API - Named Transformations operationId: delete-named-transformation description: | Permanently deletes the named transformation identified by `id`. Deletion fails with a `409` error if the named transformation is still referenced (via the `n-` token) by an upload pre-transformation or post-transformation setting. This check is best-effort and can't detect references in your own application code or in previously generated URLs. parameters: - *a6 responses: "204": description: Named transformation deleted successfully. "400": *a11 "401": *a1 "403": *a2 "404": *a8 "409": description: The named transformation is still referenced elsewhere and cannot be deleted (see the description above). content: application/json: schema: type: object properties: message: type: string example: 'Named transformation "small_thumbnail" cannot be deleted because it is referenced by an upload pre-transformation or post-transformation setting.' help: *a10 "429": *a3 /v1/accounts/webhooks: get: summary: List webhooks tags: - Account Management API - Webhooks operationId: list-webhooks description: | Returns an array of all webhooks configured for your account. responses: "200": description: Array of webhook objects. content: application/json: schema: type: array items: $ref: "#/components/schemas/Webhook" example: - &whExample id: "65f1c2a9e4b0a1b2c3d4e5f6" endpoint: "https://example.com/imagekit/webhooks" events: - "video.transformation.ready" - "file.created" enabled: true secret: "whsec_WvVlXdM3rcNkRNJ1u4H8Qq0GmZ2FEb7p" createdAt: "2024-01-10T09:00:00.000Z" updatedAt: "2024-01-10T09:00:00.000Z" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": $ref: "#/components/responses/RateLimitExceeded" post: summary: Create webhook tags: - Account Management API - Webhooks operationId: create-webhook description: | Creates a new webhook and returns the created object, including the generated signing `secret`. ImageKit sends a `POST` request to the webhook `endpoint` whenever one of the subscribed `events` occurs. Use the `secret` to verify the signature of each request. Learn more about [webhooks](https://imagekit.io/docs/webhooks). You can create up to 3 webhooks per account. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateWebhook" example: endpoint: "https://example.com/imagekit/webhooks" events: - "video.transformation.ready" - "file.created" responses: "201": description: Webhook created successfully. content: application/json: schema: $ref: "#/components/schemas/Webhook" example: *whExample "400": description: Bad request. The request body failed validation. content: application/json: schema: type: object properties: message: type: string examples: - "`endpoint` is required and must be a valid URL with the http or https protocol." - "`events` is required and must contain at least one event." - "`events` contains an unsupported event type." - "`events` must not contain duplicate event types." - "`enabled` must be a boolean." - "Your request must not contain any additional properties." - "You have reached the maximum limit of 3 webhooks allowed per account." help: &whHelp type: string example: For support kindly contact us at support@imagekit.io . "409": description: A webhook with this endpoint already exists, or another webhook is being created for this account at the same time. content: application/json: schema: type: object properties: message: type: string examples: - "A webhook with the endpoint 'https://example.com/imagekit/webhooks' already exists." - "Another webhook is being created for this account. Please retry after some time." help: *whHelp "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": $ref: "#/components/responses/RateLimitExceeded" /v1/accounts/webhooks/{id}: get: summary: Get webhook tags: - Account Management API - Webhooks operationId: get-webhook description: Retrieves the webhook identified by `id`. parameters: - &whId in: path name: id required: true description: Unique identifier of the webhook. This is the `id` returned when the webhook was created. schema: $ref: "#/components/schemas/WebhookIdField" responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/Webhook" example: *whExample "400": &whInvalidId description: Bad request. The `id` path parameter is malformed. content: application/json: schema: type: object properties: message: type: string example: Invalid `id` in path parameter. help: *whHelp "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": &whNotFound description: Webhook not found. content: application/json: schema: type: object properties: message: type: string example: 'Webhook with id "65f1c2a9e4b0a1b2c3d4e5f6" not found.' help: *whHelp "429": $ref: "#/components/responses/RateLimitExceeded" patch: summary: Update webhook tags: - Account Management API - Webhooks operationId: update-webhook description: | Updates the webhook identified by `id` and returns the updated object. Only the fields included in the request body are changed. When `events` is provided, it replaces the existing list of subscribed events. The signing `secret` can't be changed. parameters: - *whId requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateWebhook" example: events: - "video.transformation.ready" - "video.transformation.error" enabled: false responses: "200": description: Webhook updated successfully. content: application/json: schema: $ref: "#/components/schemas/Webhook" example: id: "65f1c2a9e4b0a1b2c3d4e5f6" endpoint: "https://example.com/imagekit/webhooks" events: - "video.transformation.ready" - "video.transformation.error" enabled: false secret: "whsec_WvVlXdM3rcNkRNJ1u4H8Qq0GmZ2FEb7p" createdAt: "2024-01-10T09:00:00.000Z" updatedAt: "2024-02-01T12:30:00.000Z" "400": description: Bad request. The request body or `id` path parameter failed validation. content: application/json: schema: type: object properties: message: type: string examples: - "`endpoint` must be a valid URL with the http or https protocol." - "`events` must contain at least one event." - "`events` contains an unsupported event type." - "`events` must not contain duplicate event types." - "`enabled` must be a boolean." - "Your request must contain at least one of `endpoint`, `events` or `enabled`." - "Your request must not contain any additional properties." - "Invalid `id` in path parameter." help: *whHelp "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": *whNotFound "409": description: Another webhook with this endpoint already exists. content: application/json: schema: type: object properties: message: type: string example: "A webhook with the endpoint 'https://example.com/imagekit/webhooks' already exists." help: *whHelp "429": $ref: "#/components/responses/RateLimitExceeded" delete: summary: Delete webhook tags: - Account Management API - Webhooks operationId: delete-webhook description: | Permanently deletes the webhook identified by `id`. ImageKit stops sending events to its endpoint. parameters: - *whId responses: "204": description: Webhook deleted successfully. "400": *whInvalidId "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": *whNotFound "429": $ref: "#/components/responses/RateLimitExceeded" components: schemas: BaseWebhookEvent: type: object properties: id: type: string description: Unique identifier for the event. type: type: string description: The type of webhook event. x-stainless-skip: [ java ] required: [ id, type ] 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 const: "all" description: | An array of AITags associated with the file that you want to remove, e.g. `["car", "vehicle", "motorsports"]`. If you want to remove all AITags associated with the file, send a string - "all". Note: The remove operation for `AITags` executes before any of the `extensions` are processed. 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, null ] 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, null ] 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. To preserve the original creation date of an asset migrated from another system, set the reserved `_internal_original_created_datetime` key to an ISO 8601 date string. This key is available once the original creation date setting is enabled in the media library settings. 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. OriginRequest: title: Origin request description: Schema for origin request resources. example: name: My S3 Origin type: S3 bucket: test-bucket prefix: images accessKey: AKIATEST123 secretKey: secrettest123 discriminator: propertyName: type oneOf: - title: S3 type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "S3" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri bucket: description: S3 bucket name. example: product-images type: string minLength: 1 maxLength: 100 prefix: description: Path prefix inside the bucket. example: raw-assets default: "" type: string maxLength: 100 useIAMRole: description: > Use IAM role for authentication instead of access/secret keys. When set to `true`, send an empty string for both `accessKey` and `secretKey`. example: true default: false type: boolean accessKey: description: > Access key for the bucket. When `useIAMRole` is `true`, send an empty string. example: AKIAIOSFODNN7EXAMPLE type: string maxLength: 100 secretKey: description: > Secret key for the bucket. When `useIAMRole` is `true`, send an empty string. example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY type: string maxLength: 100 required: - name - type - bucket - accessKey - secretKey additionalProperties: false - title: S3 Compatible type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "S3_COMPATIBLE" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri bucket: description: S3 bucket name. example: product-images type: string minLength: 1 maxLength: 100 prefix: description: Path prefix inside the bucket. example: raw-assets default: "" type: string maxLength: 100 accessKey: description: Access key for the bucket. example: AKIAIOSFODNN7EXAMPLE type: string minLength: 1 maxLength: 100 secretKey: description: Secret key for the bucket. example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY type: string minLength: 1 maxLength: 100 endpoint: description: Custom S3-compatible endpoint. example: https://s3.eu-central-1.wasabisys.com type: string format: uri s3ForcePathStyle: default: false description: Use path-style S3 URLs? example: true type: boolean required: - name - type - bucket - accessKey - secretKey - endpoint additionalProperties: false - title: Cloudinary Backup type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "CLOUDINARY_BACKUP" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri bucket: description: S3 bucket name. example: product-images type: string minLength: 1 maxLength: 100 prefix: description: Path prefix inside the bucket. example: raw-assets default: "" type: string maxLength: 100 useIAMRole: description: > Use IAM role for authentication instead of access/secret keys. When set to `true`, send an empty string for both `accessKey` and `secretKey`. example: true default: false type: boolean accessKey: description: > Access key for the bucket. When `useIAMRole` is `true`, send an empty string. example: AKIAIOSFODNN7EXAMPLE type: string maxLength: 100 secretKey: description: > Secret key for the bucket. When `useIAMRole` is `true`, send an empty string. example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY type: string maxLength: 100 required: - name - type - bucket - accessKey - secretKey additionalProperties: false - title: Web Folder type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "WEB_FOLDER" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri baseUrl: description: Root URL for the web folder origin. example: https://images.example.com/assets type: string format: uri forwardHostHeaderToOrigin: description: Forward the Host header to origin? example: false default: false type: boolean required: - name - type - baseUrl additionalProperties: false - title: Web Proxy type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "WEB_PROXY" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri required: - name - type additionalProperties: false - title: Google Cloud Storage (GCS) type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "GCS" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri bucket: example: gcs-media type: string minLength: 1 maxLength: 100 prefix: example: products default: "" type: string maxLength: 100 clientEmail: example: service-account@project.iam.gserviceaccount.com type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ privateKey: example: -----BEGIN PRIVATE KEY-----\nMIIEv... type: string minLength: 1 required: - name - type - bucket - clientEmail - privateKey additionalProperties: false - title: Azure Blob Storage type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "AZURE_BLOB" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri container: example: images type: string minLength: 1 maxLength: 100 prefix: example: uploads default: "" type: string maxLength: 100 accountName: example: account123 type: string minLength: 1 maxLength: 100 sasToken: example: ?sv=2023-01-03&sr=c&sig=abc123 type: string minLength: 1 required: - name - type - container - accountName - sasToken additionalProperties: false - title: Akeneo PIM type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "AKENEO_PIM" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri baseUrl: description: Akeneo instance base URL. example: https://akeneo.company.com type: string format: uri clientId: description: Akeneo API client ID. example: akeneo-client-id type: string minLength: 1 maxLength: 100 clientSecret: description: Akeneo API client secret. example: akeneo-client-secret type: string minLength: 1 maxLength: 100 username: description: Akeneo API username. example: integration-user type: string minLength: 1 maxLength: 100 password: description: Akeneo API password. example: strongpassword123 type: string minLength: 1 maxLength: 100 required: - name - type - baseUrl - clientId - clientSecret - username - password additionalProperties: false type: object OriginResponse: title: Origin Response description: Origin object as returned by the API (sensitive fields removed). discriminator: propertyName: type oneOf: - title: S3 type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "S3" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri bucket: description: S3 bucket name. example: product-images type: string minLength: 1 maxLength: 100 prefix: type: string description: Path prefix inside the bucket. example: raw-assets useIAMRole: description: > Whether the origin authenticates using an IAM role instead of access/secret keys. example: true default: false type: boolean id: readOnly: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: - name - type - includeCanonicalHeader - bucket - prefix - id additionalProperties: false - title: S3 Compatible type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "S3_COMPATIBLE" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri bucket: description: S3 bucket name. example: product-images type: string minLength: 1 maxLength: 100 prefix: type: string description: Path prefix inside the bucket. example: raw-assets endpoint: description: Custom S3-compatible endpoint. example: https://s3.eu-central-1.wasabisys.com type: string format: uri s3ForcePathStyle: default: false description: Use path-style S3 URLs? example: true type: boolean id: readOnly: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: - name - type - includeCanonicalHeader - bucket - prefix - endpoint - s3ForcePathStyle - id additionalProperties: false - title: Cloudinary Backup type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "CLOUDINARY_BACKUP" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri bucket: description: S3 bucket name. example: product-images type: string minLength: 1 maxLength: 100 prefix: type: string description: Path prefix inside the bucket. example: raw-assets useIAMRole: description: > Whether the origin authenticates using an IAM role instead of access/secret keys. example: true default: false type: boolean id: readOnly: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: - name - type - includeCanonicalHeader - bucket - prefix - id additionalProperties: false - title: Web Folder type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "WEB_FOLDER" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri baseUrl: type: string format: uri description: Root URL for the web folder origin. example: https://images.example.com/assets forwardHostHeaderToOrigin: description: Forward the Host header to origin? example: false default: false type: boolean id: readOnly: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: - name - type - includeCanonicalHeader - baseUrl - forwardHostHeaderToOrigin - id additionalProperties: false - title: Web Proxy type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "WEB_PROXY" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri id: readOnly: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: - name - type - includeCanonicalHeader - id additionalProperties: false - title: Google Cloud Storage (GCS) type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "GCS" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri bucket: example: gcs-media type: string minLength: 1 maxLength: 100 prefix: type: string example: products clientEmail: example: service-account@project.iam.gserviceaccount.com type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ id: readOnly: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: - name - type - includeCanonicalHeader - bucket - prefix - clientEmail - id additionalProperties: false - title: Azure Blob Storage type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "AZURE_BLOB" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri container: example: images type: string minLength: 1 maxLength: 100 prefix: type: string example: uploads accountName: example: account123 type: string minLength: 1 maxLength: 100 id: readOnly: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: - name - type - includeCanonicalHeader - container - prefix - accountName - id additionalProperties: false - title: Akeneo PIM type: object properties: name: description: Display name of the origin. example: US S3 Storage type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9 ]+$ type: type: string const: "AKENEO_PIM" includeCanonicalHeader: description: Whether to send a Canonical header. example: false default: false type: boolean baseUrlForCanonicalHeader: description: URL used in the Canonical header (if enabled). example: https://cdn.example.com type: string format: uri baseUrl: type: string format: uri description: Akeneo instance base URL. example: https://akeneo.company.com id: readOnly: true description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string required: - name - type - includeCanonicalHeader - baseUrl - id additionalProperties: false type: object UrlEndpointRequest: title: URL Endpoint Schema description: Schema for URL endpoint resource. example: description: My custom URL endpoint urlPrefix: product-images origins: - origin-id-1 type: object properties: description: description: Description of the URL endpoint. example: My custom URL endpoint type: string minLength: 1 maxLength: 1000 urlPrefix: description: Path segment appended to your base URL to form the endpoint (letters, digits, and hyphens only — or empty for the default endpoint). example: product-images default: "" type: string maxLength: 100 origins: description: Ordered list of origin IDs to try when the file isn’t in the Media Library; ImageKit checks them in the sequence provided. Origin must be created before it can be used in a URL endpoint. example: - origin-id-1 - origin-id-2 default: [] maxItems: 10 type: array items: description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string urlRewriter: description: Configuration for third-party URL rewriting. discriminator: propertyName: type oneOf: - title: Cloudinary URL Rewriter type: object properties: type: type: string const: "CLOUDINARY" preserveAssetDeliveryTypes: description: Whether to preserve `/` in the rewritten URL. example: true default: false type: boolean useImprovedLayerSpec: description: Whether to always rewrite Cloudinary layers to the improved ImageKit layer specification (`l-image`, `l-text`, ..., `l-end`). When `false` or omitted, the improved specification is used only for transformations that require it. example: true type: boolean required: - type additionalProperties: false - title: Imgix URL Rewriter type: object properties: type: type: string const: "IMGIX" required: - type additionalProperties: false - title: Akamai URL Rewriter type: object properties: type: type: string const: "AKAMAI" required: - type additionalProperties: false type: object required: - description additionalProperties: false UrlEndpointResponse: title: URL‑endpoint Response description: URL‑endpoint object as returned by the API. type: object properties: description: description: Description of the URL endpoint. example: My custom URL endpoint type: string minLength: 1 maxLength: 1000 urlPrefix: description: Path segment appended to your base URL to form the endpoint (letters, digits, and hyphens only — or empty for the default endpoint). example: product-images default: "" type: string maxLength: 100 origins: description: Ordered list of origin IDs to try when the file isn’t in the Media Library; ImageKit checks them in the sequence provided. Origin must be created before it can be used in a URL endpoint. example: - origin-id-1 - origin-id-2 default: [] maxItems: 10 type: array items: description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin. type: string urlRewriter: description: Configuration for third-party URL rewriting. discriminator: propertyName: type oneOf: - title: Cloudinary URL Rewriter type: object properties: type: type: string const: "CLOUDINARY" preserveAssetDeliveryTypes: description: Whether to preserve `/` in the rewritten URL. example: true default: false type: boolean useImprovedLayerSpec: description: Whether to always rewrite Cloudinary layers to the improved ImageKit layer specification (`l-image`, `l-text`, ..., `l-end`). When `false` or omitted, the improved specification is used only for transformations that require it. example: true type: boolean required: - type - preserveAssetDeliveryTypes additionalProperties: false - title: Imgix URL Rewriter type: object properties: type: type: string const: "IMGIX" required: - type additionalProperties: false - title: Akamai URL Rewriter type: object properties: type: type: string const: "AKAMAI" required: - type additionalProperties: false type: object id: readOnly: true description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`. type: string required: - description - urlPrefix - origins - id additionalProperties: false FileUploadV1: type: object required: - file - fileName properties: file: type: string format: binary # multipart/form-data file upload contentEncoding: binary # For our docs try it description: | The API accepts any of the following: - **Binary data** – send the raw bytes as `multipart/form-data`. - **HTTP / HTTPS URL** – a publicly reachable URL that ImageKit’s servers can fetch. - **Base64 string** – the file encoded as a Base64 data URI or plain Base64. When supplying a URL, the server must receive the response headers within 8 seconds; otherwise the request fails with 400 Bad Request. example: https://www.example.com/path/to-image.jpg fileName: type: string description: > The name with which the file has to be uploaded. The file name can contain: - Alphanumeric Characters: `a-z`, `A-Z`, `0-9`. - Special Characters: `.`, `-` Any other character including space will be replaced by `_` publicKey: type: string description: > Your ImageKit.io public key. This field is only required for authentication when uploading a file from the client side. signature: type: string description: > HMAC-SHA1 digest of the token+expire using your ImageKit.io private API key as a key. Learn how to create a signature on the page below. This should be in lowercase. Signature must be calculated on the server-side. This field is only required for authentication when uploading a file from the client side. expire: type: integer description: > The time until your signature is valid. It must be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in less than 1 hour into the future. It should be in seconds. This field is only required for authentication when uploading a file from the client side. token: type: string description: > A unique value that the ImageKit.io server will use to recognize and prevent subsequent retries for the same request. We suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. This field is only required for authentication when uploading a file from the client side. **Note**: Sending a value that has been used in the past will result in a validation error. Even if your previous request resulted in an error, you should always send a new value for this field. useUniqueFileName: type: boolean default: true description: > Whether to use a unique filename for this file or not. If `true`, ImageKit.io will add a unique suffix to the filename parameter to get a unique filename. If `false`, then the image is uploaded with the provided filename parameter, and any existing file with the same name is replaced. tags: type: array items: type: string description: > Set the tags while uploading the file. Provide an array of tag strings (e.g. `["tag1", "tag2", "tag3"]`). The combined length of all tag characters must not exceed 500, and the `%` character is not allowed. If this field is not specified and the file is overwritten, the existing tags will be removed. example: - t-shirt - round-neck - men folder: type: string description: > The folder path in which the image has to be uploaded. If the folder(s) didn't exist before, a new folder(s) is created. The folder name can contain: - Alphanumeric Characters: `a-z` , `A-Z` , `0-9` - Special Characters: `/` , `_` , `-` Using multiple `/` creates a nested folder. default: "/" isPrivateFile: type: boolean default: false description: > Whether to mark the file as private or not. If `true`, the file is marked as private and is accessible only using named transformation or signed URL. isPublished: type: boolean default: true description: > Whether to upload file as published or not. If `false`, the file is marked as unpublished, which restricts access to the file only via the media library. Files in draft or unpublished state can only be publicly accessed after being published. The option to upload in draft state is only available in custom enterprise pricing plans. customCoordinates: type: string description: > Define an important area in the image. This is only relevant for image type files. - To be passed as a string with the x and y coordinates of the top-left corner, and width and height of the area of interest in the format `x,y,width,height`. For example - `10,10,100,100` - Can be used with fo-customtransformation. - If this field is not specified and the file is overwritten, then customCoordinates will be removed. responseFields: type: array items: type: string enum: - tags - customCoordinates - isPrivateFile - embeddedMetadata - isPublished - customMetadata - metadata - selectedFieldsSchema description: | Array of response field keys to include in the API response body. example: - tags - customCoordinates - isPrivateFile extensions: $ref: "#/components/schemas/Extensions" 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. overwriteFile: type: boolean default: true description: > If `false` and `useUniqueFileName` is also `false`, and a file already exists at the exact location, upload API will return an error immediately. overwriteAITags: type: boolean default: true description: > If set to `true` and a file already exists at the exact location, its AITags will be removed. Set `overwriteAITags` to `false` to preserve AITags. overwriteTags: type: boolean default: true description: > If the request does not have `tags`, and a file already exists at the exact location, existing tags will be removed. overwriteCustomMetadata: type: boolean default: true description: > If the request does not have `customMetadata`, and a file already exists at the exact location, existing customMetadata will be removed. customMetadata: type: object additionalProperties: true description: > JSON key-value pairs to associate with the asset. Create the custom metadata fields before setting these values. To preserve the original creation date of an asset migrated from another system, set the reserved `_internal_original_created_datetime` key to an ISO 8601 date string. This key is available once the original creation date setting is enabled in the media library settings. example: brand: "Nike" color: "red" transformation: type: object $ref: "#/components/schemas/TransformationObject" checks: type: string description: > Server-side checks to run on the asset. Read more about [Upload API checks](/docs/api-reference/upload-file/upload-file#upload-api-checks). example: > "request.folder" : "marketing/" description: type: string description: | Optional text to describe the contents of the file. example: "Running shoes" FileUploadV2: type: object required: - file - fileName properties: file: type: string format: binary # multipart/form-data file upload contentEncoding: binary # For our docs try it description: | The API accepts any of the following: - **Binary data** – send the raw bytes as `multipart/form-data`. - **HTTP / HTTPS URL** – a publicly reachable URL that ImageKit’s servers can fetch. - **Base64 string** – the file encoded as a Base64 data URI or plain Base64. When supplying a URL, the server must receive the response headers within 8 seconds; otherwise the request fails with 400 Bad Request. fileName: type: string description: > The name with which the file has to be uploaded. token: type: string description: > This is the client-generated JSON Web Token (JWT). The ImageKit.io server uses it to authenticate and check that the upload request parameters have not been tampered with after the token has been generated. Learn how to create the token on the page below. This field is only required for authentication when uploading a file from the client side. **Note**: Sending a JWT that has been used in the past will result in a validation error. Even if your previous request resulted in an error, you should always send a new token. **⚠️Warning**: JWT must be generated on the server-side because it is generated using your account's private API key. This field is required for authentication when uploading a file from the client-side. useUniqueFileName: type: boolean default: true description: > Whether to use a unique filename for this file or not. If `true`, ImageKit.io will add a unique suffix to the filename parameter to get a unique filename. If `false`, then the image is uploaded with the provided filename parameter, and any existing file with the same name is replaced. tags: type: array items: type: string description: > Set the tags while uploading the file. Provide an array of tag strings (e.g. `["tag1", "tag2", "tag3"]`). The combined length of all tag characters must not exceed 500, and the `%` character is not allowed. If this field is not specified and the file is overwritten, the existing tags will be removed. example: - t-shirt - round-neck - men folder: type: string description: > The folder path in which the image has to be uploaded. If the folder(s) didn't exist before, a new folder(s) is created. Using multiple `/` creates a nested folder. default: "/" isPrivateFile: type: boolean default: false description: > Whether to mark the file as private or not. If `true`, the file is marked as private and is accessible only using named transformation or signed URL. isPublished: type: boolean default: true description: > Whether to upload file as published or not. If `false`, the file is marked as unpublished, which restricts access to the file only via the media library. Files in draft or unpublished state can only be publicly accessed after being published. The option to upload in draft state is only available in custom enterprise pricing plans. customCoordinates: type: string description: > Define an important area in the image. This is only relevant for image type files. - To be passed as a string with the x and y coordinates of the top-left corner, and width and height of the area of interest in the format `x,y,width,height`. For example - `10,10,100,100` - Can be used with fo-customtransformation. - If this field is not specified and the file is overwritten, then customCoordinates will be removed. responseFields: type: array items: type: string enum: - tags - customCoordinates - isPrivateFile - embeddedMetadata - isPublished - customMetadata - metadata - selectedFieldsSchema description: | Array of response field keys to include in the API response body. example: - tags - customCoordinates - isPrivateFile extensions: $ref: "#/components/schemas/Extensions" 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. overwriteFile: type: boolean default: true description: > If `false` and `useUniqueFileName` is also `false`, and a file already exists at the exact location, upload API will return an error immediately. overwriteAITags: type: boolean default: true description: > If set to `true` and a file already exists at the exact location, its AITags will be removed. Set `overwriteAITags` to `false` to preserve AITags. overwriteTags: type: boolean default: true description: > If the request does not have `tags`, and a file already exists at the exact location, existing tags will be removed. overwriteCustomMetadata: type: boolean default: true description: > If the request does not have `customMetadata`, and a file already exists at the exact location, existing customMetadata will be removed. customMetadata: type: object additionalProperties: true description: > JSON key-value pairs to associate with the asset. Create the custom metadata fields before setting these values. To preserve the original creation date of an asset migrated from another system, set the reserved `_internal_original_created_datetime` key to an ISO 8601 date string. This key is available once the original creation date setting is enabled in the media library settings. example: brand: "Nike" color: "red" transformation: type: object $ref: "#/components/schemas/TransformationObject" checks: type: string description: > Server-side checks to run on the asset. Read more about [Upload API checks](/docs/api-reference/upload-file/upload-file-v2#upload-api-checks). example: > "request.folder" : "marketing/" description: type: string description: | Optional text to describe the contents of the file. example: "Running shoes" TransformationObject: type: object additionalProperties: false x-stainless-naming: java: type_name: UploadTransformation description: | Configure pre-processing (`pre`) and post-processing (`post`) transformations. - `pre` — applied before the file is uploaded to the Media Library. Useful for reducing file size or applying basic optimizations upfront (e.g., resize, compress). - `post` — applied immediately after upload. Ideal for generating transformed versions (like video encodes or thumbnails) in advance, so they're ready for delivery without delay. You can mix and match any combination of post-processing types. properties: pre: type: string description: | Transformation string to apply before uploading the file to the Media Library. Useful for optimizing files at ingestion. example: "w-300,h-300,q-80" post: type: array description: | List of transformations to apply *after* the file is uploaded. Each item must match one of the following types: `transformation`, `gif-to-video`, `thumbnail`, `abs`. items: discriminator: propertyName: type oneOf: # ───────────── simple transformation ───────────── - type: object title: Simple post-transformation required: [ type, value ] additionalProperties: false properties: type: type: string const: "transformation" description: Transformation type. value: type: string description: | Transformation string (e.g. `w-200,h-200`). Same syntax as ImageKit URL-based transformations. example: type: "transformation" value: "w-400,h-400,q-70" # ───────────── GIF → video ───────────── - type: object title: Convert GIF to video required: [ type ] additionalProperties: false properties: type: type: string const: "gif-to-video" description: Converts an animated GIF into an MP4. value: type: string description: | Optional transformation string to apply to the output video. **Example**: `q-80` example: type: "gif-to-video" value: "q-90" # ───────────── thumbnail ───────────── - type: object title: Generate a thumbnail required: [ type ] additionalProperties: false properties: type: type: string const: "thumbnail" description: Generates a thumbnail image. value: type: string description: | Optional transformation string. **Example**: `w-150,h-150` example: type: "thumbnail" value: "w-150,h-150" # ───────────── ABS ───────────── - type: object title: Adaptive Bitrate Streaming required: [ type, value, protocol ] additionalProperties: false properties: type: type: string const: "abs" description: Adaptive Bitrate Streaming (ABS) setup. value: type: string description: | List of different representations you want to create separated by an underscore. protocol: type: string enum: [ "hls", "dash" ] description: Streaming protocol to use (`hls` or `dash`). example: type: "abs" value: "sr-240_360_480_720_1080" protocol: "hls" example: post: - type: "thumbnail" value: "w-150,h-150" - type: "abs" value: "sr-240_360_480_720_1080" protocol: "dash" RemovedotBGExtension: title: Remove background type: object required: - name properties: name: type: string const: "remove-bg" description: Specifies the background removal extension. 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. 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. AutoDescriptionExtension: title: Auto description type: object required: - name properties: name: type: string const: "ai-auto-description" description: Specifies the auto description extension. AITasksExtension: title: AI Tasks type: object required: - name - tasks properties: name: type: string const: "ai-tasks" description: Specifies the AI tasks extension for automated image analysis using AI models. 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" AITaskSelectTags: title: AI Task - Select Tags type: object required: - type - instruction properties: type: type: string const: "select_tags" description: Task type that analyzes the image and adds matching tags from a vocabulary. 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. AITaskSelectMetadata: title: AI Task - Select Metadata type: object required: - type - instruction - field properties: type: type: string const: "select_metadata" description: Task type that analyzes the image and sets a custom metadata field value from a vocabulary. 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. AITaskYesNo: title: AI Task - Yes/No type: object required: - type - instruction properties: type: type: string const: "yes_no" description: Task type that asks a yes/no question and executes actions based on the answer. 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. 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" ExtensionConfig: title: Extension Configuration description: Configuration object for an extension (base extensions only, not saved extension references). type: object discriminator: propertyName: name oneOf: - $ref: "#/components/schemas/RemovedotBGExtension" - $ref: "#/components/schemas/AutoTaggingExtension" - $ref: "#/components/schemas/AutoDescriptionExtension" - $ref: "#/components/schemas/AITasksExtension" SavedExtensionReference: title: Saved Extension Reference type: object required: - name - id properties: name: type: string const: "saved-extension" description: Indicates this is a reference to a saved extension. id: type: string description: The unique ID of the saved extension to apply. example: "ext_abc123" CreateSavedExtension: title: Create Saved Extension type: object required: - name - description - config properties: name: type: string minLength: 1 description: Name of the saved extension. example: "Car Quality Analysis" description: type: string minLength: 1 description: Description of what the saved extension does. example: "Analyzes vehicle images for type, condition, and quality assessment" config: $ref: "#/components/schemas/ExtensionConfig" UpdateSavedExtension: title: Update Saved Extension type: object properties: name: type: string minLength: 1 description: Updated name of the saved extension. description: type: string minLength: 1 description: Updated description of the saved extension. config: $ref: "#/components/schemas/ExtensionConfig" SavedExtension: title: Saved Extension description: Saved extension object containing extension configuration. type: object properties: id: type: string description: Unique identifier of the saved extension. example: "ext_abc123" name: type: string description: Name of the saved extension. example: "Car Quality Analysis" description: type: string description: Description of the saved extension. example: "Analyzes vehicle images for type, condition, and quality assessment" config: $ref: "#/components/schemas/ExtensionConfig" createdAt: type: string format: date-time description: Timestamp when the saved extension was created. updatedAt: type: string format: date-time description: Timestamp when the saved extension was last updated. NamedTransformationIdField: type: string description: Unique identifier for a named transformation. example: "6bZ9x2ZUx" NamedTransformationNameField: type: string minLength: 1 pattern: "^[0-9a-zA-Z_]+$" description: | Alias for the transformation string, used in URLs as `tr:n-`. This is case-sensitive, contains only alphanumeric characters or `_` (underscore), and is unique across all named transformations for your account. example: "small_thumbnail" NamedTransformationValueField: type: string minLength: 1 description: | The transformation string this named transformation refers to. Learn more about the [transformation string syntax](https://imagekit.io/docs/transformations). example: "w-150,h-150,fo-center,cm-pad_resize" NamedTransformationEnabledField: type: boolean description: Whether the named transformation is currently enabled. When set to `false`, requests using this named transformation fail at delivery time. example: true CreateNamedTransformation: title: Create Named Transformation type: object required: - name - transformation additionalProperties: false properties: name: $ref: "#/components/schemas/NamedTransformationNameField" transformation: $ref: "#/components/schemas/NamedTransformationValueField" enabled: $ref: "#/components/schemas/NamedTransformationEnabledField" default: true UpdateNamedTransformation: title: Update Named Transformation type: object additionalProperties: false properties: name: $ref: "#/components/schemas/NamedTransformationNameField" transformation: $ref: "#/components/schemas/NamedTransformationValueField" enabled: $ref: "#/components/schemas/NamedTransformationEnabledField" description: | Whether the named transformation is enabled. Omit to leave the current value unchanged. NamedTransformation: title: Named Transformation description: | A named transformation is an alias for a transformation string, letting you apply and later update complex transformations without changing your image or video URLs. Learn more about [named transformations](https://imagekit.io/docs/transformations#named-transformations). type: object required: - id - name - transformation - enabled - createdAt properties: id: $ref: "#/components/schemas/NamedTransformationIdField" name: $ref: "#/components/schemas/NamedTransformationNameField" transformation: $ref: "#/components/schemas/NamedTransformationValueField" enabled: $ref: "#/components/schemas/NamedTransformationEnabledField" createdAt: type: string format: date-time description: | ISO 8601 timestamp of when the named transformation was created. example: "2024-01-10T09:00:00.000Z" WebhookIdField: type: string description: Unique identifier for a webhook. example: "65f1c2a9e4b0a1b2c3d4e5f6" WebhookEndpointField: type: string format: uri description: | The URL where ImageKit sends webhook events as `POST` requests. Must use the `http` or `https` protocol, and must be unique across all webhooks for your account. example: "https://example.com/imagekit/webhooks" WebhookEventType: type: string description: | A webhook event type. Learn more about the payload of each [webhook event](https://imagekit.io/docs/webhooks#list-of-events). enum: - video.transformation.accepted - video.transformation.ready - video.transformation.error - upload.pre-transform.success - upload.pre-transform.error - upload.post-transform.success - upload.post-transform.error - file.created - file.updated - file.deleted - file-version.created - file-version.deleted - folder.created - folder.updated - folder.deleted WebhookEventsField: type: array minItems: 1 uniqueItems: true description: | The event types this webhook is subscribed to. ImageKit sends a request to the `endpoint` only for these events. items: $ref: "#/components/schemas/WebhookEventType" example: - "video.transformation.ready" - "file.created" WebhookEnabledField: type: boolean description: Whether the webhook is enabled. When `false`, ImageKit doesn't send any events to the `endpoint`. example: true CreateWebhook: title: Create Webhook type: object required: - endpoint - events additionalProperties: false properties: endpoint: $ref: "#/components/schemas/WebhookEndpointField" events: $ref: "#/components/schemas/WebhookEventsField" enabled: $ref: "#/components/schemas/WebhookEnabledField" default: true UpdateWebhook: title: Update Webhook type: object minProperties: 1 additionalProperties: false properties: endpoint: $ref: "#/components/schemas/WebhookEndpointField" events: $ref: "#/components/schemas/WebhookEventsField" description: | The event types this webhook is subscribed to. Replaces the existing list. Omit to leave the current value unchanged. enabled: $ref: "#/components/schemas/WebhookEnabledField" description: | Whether the webhook is enabled. Omit to leave the current value unchanged. Webhook: title: Webhook description: | A webhook is an HTTP endpoint that ImageKit notifies when subscribed events occur in your account. Learn more about [webhooks](https://imagekit.io/docs/webhooks). type: object required: - id - endpoint - events - enabled - secret - createdAt - updatedAt properties: id: $ref: "#/components/schemas/WebhookIdField" endpoint: $ref: "#/components/schemas/WebhookEndpointField" events: $ref: "#/components/schemas/WebhookEventsField" enabled: $ref: "#/components/schemas/WebhookEnabledField" secret: type: string description: | Signing secret generated by ImageKit, used to verify that webhook requests come from ImageKit. Starts with `whsec_`. This value can't be set or changed through the API. Learn more about [verifying webhook signatures](https://imagekit.io/docs/webhooks#verify-webhook-signature). example: "whsec_WvVlXdM3rcNkRNJ1u4H8Qq0GmZ2FEb7p" createdAt: type: string format: date-time description: | ISO 8601 timestamp of when the webhook was created. example: "2024-01-10T09:00:00.000Z" updatedAt: type: string format: date-time description: | ISO 8601 timestamp of when the webhook was last updated. example: "2024-01-10T09:00:00.000Z" 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" Tag: type: object properties: name: type: string description: The tag in lowercase. Tags are case-insensitive, so this is the unique key of the tag within your account. label: type: string description: The tag as it was spelled when it was last applied to any asset. Use it for display. lastUsedAt: type: string format: date-time description: When the tag was last applied to an asset matching the `tagSource` and `fileType` filters of the request, in ISO 8601 format. assetCount: type: integer description: The number of assets carrying the tag, counted across both tag sources (user-generated tags and AI-generated tags) and all file types regardless of the request's filters. required: - name - label - lastUsedAt - assetCount description: | A tag in use in your media library, aggregated case-insensitively across the assets that carry it. 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. 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`. 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. 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, null ] 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, null ] 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, null ] 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. FolderDetails: title: Folder type: object properties: type: type: string description: Type of the asset. const: "folder" folderId: type: string description: Unique identifier of the asset. name: type: string description: Name of the asset. customMetadata: description: An object with custom metadata for the folder. Returns empty object if no custom metadata is set. $ref: "#/components/schemas/CustomMetadata" folderPath: type: string description: | Path of the folder. This is the path you would use in the URL to access the folder. For example, if the folder is at the root of the media library, the path will be /folder. If the folder is inside another folder named images, the path will be /images/folder. createdAt: type: string format: date-time description: | Date and time when the folder was created. The date and time is in ISO8601 format. updatedAt: type: string format: date-time description: | Date and time when the folder was last updated. The date and time is in ISO8601 format. createdBy: type: object description: | Details of the user who created the folder. Present only when this information is available. The `name` is the name of the user at the time of folder creation. properties: name: type: string description: Name of the user who created the folder. email: type: string description: Email of the user who created the folder. 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 Upload: description: Object containing details of a successful upload. type: object properties: fileId: type: string description: Unique fileId. Store this fileld in your database, as this will be used to perform update action on this file. name: type: string description: Name of the asset. filePath: type: string description: The relative path of the file in the media library e.g. `/marketing-assets/new-banner.jpg`. url: type: string description: A publicly accessible URL of the file. thumbnailUrl: type: string description: In the case of an image, a small thumbnail URL. height: type: number description: Height of the image in pixels (Only for images) width: type: number description: Width of the image in pixels (Only for Images) size: type: number description: Size of the image 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). videoCodec: type: string description: The video codec used in the video (only for video). tags: type: [ array, null ] items: type: string description: The array of tags associated with the asset. If no tags are set, it will be `null`. Send `tags` in `responseFields` in API request to get the value of this field. AITags: type: [ array, null ] items: $ref: "#/components/schemas/AITag" description: | An array of tags assigned to the uploaded file by auto tagging. versionInfo: $ref: "#/components/schemas/VersionInfo" isPrivateFile: type: boolean description: | Is the file marked as private. It can be either `true` or `false`. Send `isPrivateFile` in `responseFields` in API request to get the value of this field. isPublished: type: boolean description: | Is the file published or in draft state. It can be either `true` or `false`. Send `isPublished` in `responseFields` in API request to get the value of this field. customCoordinates: type: [ string, null ] description: | Value of custom coordinates associated with the image in the format `x,y,width,height`. If `customCoordinates` are not defined, then it is `null`. Send `customCoordinates` in `responseFields` in API request to get the value of this field. fileType: type: string description: | Type of the uploaded file. Possible values are `image`, `non-image`. customMetadata: description: | A key-value data associated with the asset. Use `responseField` in API request to get `customMetadata` in the upload API response. Before setting any custom metadata on an asset, you have to create the field using custom metadata fields API. Send `customMetadata` in `responseFields` in API request to get the value of this field. $ref: "#/components/schemas/CustomMetadata" selectedFieldsSchema: $ref: "#/components/schemas/SelectedFieldsSchema" extensionStatus: type: object description: | Extension names with their processing status at the time of completion of the request. It could have one of the following status values: `success`: The extension has been successfully applied. `failed`: The extension has failed and will not be retried. `pending`: The extension will finish processing in some time. On completion, the final status (success / failed) will be sent to the `webhookUrl` provided. If no extension was requested, then this parameter is not returned. 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" ] metadata: type: object $ref: "#/components/schemas/Metadata" description: | Legacy metadata. Send `metadata` in `responseFields` in API request to get metadata in the upload API response. embeddedMetadata: description: Consolidated embedded metadata associated with the file. It includes exif, iptc, and xmp data. Send `embeddedMetadata` in `responseFields` in API request to get embeddedMetadata in the upload API response. $ref: "#/components/schemas/EmbeddedMetadata" 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. ExifImage: description: Object containing EXIF image information. type: object additionalProperties: true properties: Make: type: string Model: type: string ImageDescription: type: string Artist: type: string Copyright: type: string Orientation: type: integer XResolution: type: number YResolution: type: number ResolutionUnit: type: integer Software: type: string ModifyDate: type: string YCbCrPositioning: type: integer ExifOffset: type: integer GPSInfo: type: integer Thumbnail: description: Object containing Thumbnail information. type: object additionalProperties: true properties: Compression: type: integer XResolution: type: number YResolution: type: number ResolutionUnit: type: integer ThumbnailOffset: type: integer ThumbnailLength: type: integer ExifDetails: description: Object containing Exif details. x-stainless-naming: java: type_name: ExifDetails type: object additionalProperties: true properties: ExposureTime: type: number FNumber: type: number ExposureProgram: type: integer ISO: type: integer ExifVersion: type: string DateTimeOriginal: type: string CreateDate: type: string ShutterSpeedValue: type: number ApertureValue: type: number ExposureCompensation: type: number MeteringMode: type: integer Flash: type: integer BrightnessValue: type: number MaxApertureValue: type: number LightSource: type: integer FocalLength: type: number UserComment: type: string SensingMethod: type: integer SceneType: type: string FocalLengthIn35mmFormat: type: integer LensModel: type: string SubSecTime: type: string FlashpixVersion: type: string ColorSpace: type: integer ExifImageWidth: type: integer ExifImageHeight: type: integer InteropOffset: type: integer FocalPlaneXResolution: type: number FocalPlaneYResolution: type: number FocalPlaneResolutionUnit: type: integer CustomRendered: type: integer ExposureMode: type: integer WhiteBalance: type: integer SceneCaptureType: type: integer Gps: description: Object containing GPS information. type: object additionalProperties: true properties: GPSVersionID: type: array items: type: integer GPSLatitudeRef: type: string GPSLatitude: type: array items: type: number GPSLongitudeRef: type: string GPSLongitude: type: array items: type: number GPSAltitudeRef: type: integer GPSAltitude: type: number GPSTimeStamp: type: array items: type: number GPSImgDirectionRef: type: string GPSImgDirection: type: number GPSDateStamp: type: string Interoperability: description: JSON object. type: object additionalProperties: true properties: InteropIndex: type: string InteropVersion: type: string Metadata: description: JSON object containing metadata. type: object additionalProperties: true properties: height: type: integer description: The height of the image or video in pixels. width: type: integer description: The width of the image or video in pixels. size: type: integer description: The file size in bytes. format: type: string description: The format of the file (e.g., 'jpg', 'mp4'). hasColorProfile: type: boolean description: Indicates if the image has a color profile. quality: type: integer description: The quality indicator of the image. density: type: integer description: The density of the image in DPI. hasTransparency: type: boolean description: Indicates if the image contains transparent areas. pHash: type: string description: Perceptual hash of the image. 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). videoCodec: type: string description: The video codec used in the video (only for video). exif: type: object additionalProperties: true properties: image: $ref: "#/components/schemas/ExifImage" thumbnail: $ref: "#/components/schemas/Thumbnail" exif: $ref: "#/components/schemas/ExifDetails" gps: $ref: "#/components/schemas/Gps" interoperability: $ref: "#/components/schemas/Interoperability" makernote: type: object additionalProperties: true CustomMetadataField: description: Object containing details of a custom metadata field. type: object required: - id - name - label - schema properties: id: type: string description: Unique identifier for the custom metadata field. Use this to update the field. name: type: string description: | API name of the custom metadata field. This becomes the key while setting `customMetadata` (key-value object) for an asset using upload or update API. label: type: string description: | Human readable name of the custom metadata field. This name is displayed as form field label to the users while setting field value on the asset in the media library UI. description: type: string maxLength: 500 description: | Optional description of the custom metadata field. Only present when a description has been set. Shown as a hint to the users while setting the field's value on an asset in the media library UI. reserved: type: boolean description: | Present and set to `true` when the field is reserved, i.e. created and managed by ImageKit rather than by you. Omitted for regular fields. Currently the only reserved field is `_internal_original_created_datetime` (label "Original creation date", type `Date`). ImageKit creates it when you enable the original creation date setting under the Custom Metadata tab of the media library settings in the dashboard. Use it to preserve the original creation date of assets migrated from another system: set its value through the `customMetadata` object in the upload or update file details API, then sort with `ASC_ORIGINAL_CREATION_DATE` or `DESC_ORIGINAL_CREATION_DATE` in the list and search assets API, or filter with `"customMetadata._internal_original_created_datetime"` in `searchQuery`. Reserved fields cannot be deleted, and their name cannot be reused when creating a new field. schema: type: object description: An object that describes the rules for the custom metadata field value. 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 defaultValue: description: | The default value for this custom metadata field. Data type of default value depends on the field type. oneOf: - type: string - type: number - type: boolean - type: array x-stainless-variantName: Mixed title: Mixed items: title: Default value item 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 this custom metadata field is required or not. 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 VideoWebhookRequestInfo: type: object description: Information about the original request that triggered the video transformation. properties: x_request_id: type: string description: Unique identifier for the originating transformation request. url: type: string format: uri description: Full URL of the transformation request that was submitted. user_agent: type: string description: User-Agent header from the original request that triggered the transformation. required: [ x_request_id, url ] JobResponse: type: object title: Async Bulk Job Response description: Job submitted successfully. A `jobId` will be returned. required: [ jobId ] properties: jobId: type: string description: | Unique identifier of the bulk job. This can be used to check the status of the bulk job. VideoAsset: type: object description: Information about the source video asset being transformed. properties: url: type: string format: uri description: URL to download or access the source video file. required: [ url ] VideoTransformationOptions: type: object description: Configuration options for video transformations. properties: video_codec: type: string enum: [ "h264", "vp9", "av1" ] description: Video codec used for encoding (h264, vp9, or av1). audio_codec: type: string enum: [ "aac", "opus" ] description: Audio codec used for encoding (aac or opus). auto_rotate: type: boolean description: Whether to automatically rotate the video based on metadata. quality: type: integer description: Quality setting for the output video. format: type: string enum: [ "mp4", "webm", "jpg", "png", "webp" ] description: Output format for the transformed video or thumbnail. stream_protocol: type: string enum: [ "HLS", "DASH" ] description: Streaming protocol for adaptive bitrate streaming. variants: type: array description: Array of quality representations for adaptive bitrate streaming. items: type: string description: Representation label indicating resolution or quality (e.g., "360", "480", "720", "1080"). VideoTransformationBase: type: object description: Base information about a video transformation request. properties: type: type: string enum: [ video-transformation, gif-to-video, video-thumbnail ] description: | Type of video transformation: - `video-transformation`: Standard video processing (resize, format conversion, etc.) - `gif-to-video`: Convert animated GIF to video format - `video-thumbnail`: Generate thumbnail image from video options: $ref: "#/components/schemas/VideoTransformationOptions" required: [ type ] # ---- Event: accepted ---- VideoTransformationAcceptedEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a new video transformation request is accepted for processing. This event confirms that ImageKit has received and queued your transformation request. Use this for debugging and tracking transformation lifecycle. properties: type: type: string const: "video.transformation.accepted" created_at: type: string format: date-time description: Timestamp when the event was created in ISO8601 format. request: $ref: "#/components/schemas/VideoWebhookRequestInfo" data: type: object properties: asset: $ref: "#/components/schemas/VideoAsset" transformation: $ref: "#/components/schemas/VideoTransformationBase" required: [ asset, transformation ] required: [ type, created_at, request, data ] # ---- Event: ready ---- VideoTransformationReadyEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when video encoding is finished and the transformed resource is ready to be served. This is the key event to listen for - update your database or CMS flags when you receive this so your application can start showing the transformed video to users. properties: type: type: string const: "video.transformation.ready" created_at: type: string format: date-time description: Timestamp when the event was created in ISO8601 format. request: $ref: "#/components/schemas/VideoWebhookRequestInfo" timings: type: object description: Performance metrics for the transformation process. properties: download_duration: type: integer description: Time spent downloading the source video from your origin or media library, in milliseconds. encoding_duration: type: integer description: Time spent encoding the video, in milliseconds. data: type: object properties: asset: $ref: "#/components/schemas/VideoAsset" transformation: allOf: - $ref: "#/components/schemas/VideoTransformationBase" - type: object properties: output: type: object description: Information about the transformed output video. properties: url: type: string format: uri description: URL to access the transformed video. video_metadata: type: object description: Metadata of the output video file. properties: duration: type: number description: Duration of the output video in seconds. width: type: integer description: Width of the output video in pixels. height: type: integer description: Height of the output video in pixels. bitrate: type: integer description: Bitrate of the output video in bits per second. required: [ duration, width, height, bitrate ] required: [ url ] required: [ asset, transformation ] required: [ type, created_at, request, data ] # ---- Event: error ---- VideoTransformationErrorEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when an error occurs during video encoding. Listen to this webhook to log error reasons and debug issues. Check your origin and URL endpoint settings if the reason is related to download failure. For other errors, contact ImageKit support. properties: type: type: string const: "video.transformation.error" created_at: type: string format: date-time description: Timestamp when the event was created in ISO8601 format. request: $ref: "#/components/schemas/VideoWebhookRequestInfo" data: type: object properties: asset: $ref: "#/components/schemas/VideoAsset" transformation: allOf: - $ref: "#/components/schemas/VideoTransformationBase" - type: object properties: error: type: object description: Details about the transformation error. properties: reason: type: string description: | Specific reason for the transformation failure: - `encoding_failed`: Error during video encoding process - `download_failed`: Could not download source video - `internal_server_error`: Unexpected server error enum: [ encoding_failed, download_failed, internal_server_error ] required: [ reason ] required: [ asset, transformation ] required: [ type, created_at, request, data ] # ──── Pre-transformation Event Schemas ──── PreTransformWebhookRequestInfo: type: object properties: x_request_id: type: string description: Unique identifier for the originating request. transformation: type: string description: The requested pre-transformation string. required: [ x_request_id, transformation ] UploadPreTransformSuccessEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a pre-transformation completes successfully. The file has been processed with the requested transformation and is now available in the Media Library. properties: type: type: string const: "upload.pre-transform.success" created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. request: $ref: "#/components/schemas/PreTransformWebhookRequestInfo" data: $ref: "#/components/schemas/Upload" required: [ type, created_at, request, data ] UploadPreTransformErrorEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a pre-transformation fails. The file upload may have been accepted, but the requested transformation could not be applied. properties: type: type: string const: "upload.pre-transform.error" created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. request: $ref: "#/components/schemas/PreTransformWebhookRequestInfo" data: type: object properties: name: type: string description: Name of the file. path: type: string description: Path of the file. transformation: type: object properties: error: type: object properties: reason: type: string description: Reason for the pre-transformation failure. example: "encoding_failed" required: [ reason ] required: [ error ] required: [ name, path, transformation ] required: [ type, created_at, request, data ] # ──── Post-transformation Event Schemas ──── PostTransformWebhookRequestInfo: type: object properties: x_request_id: type: string description: Unique identifier for the originating request. transformation: type: object properties: type: type: string enum: [ transformation, abs, gif-to-video, thumbnail ] description: Type of the requested post-transformation. value: type: string description: Value for the requested transformation type. protocol: type: string enum: [ hls, dash ] description: Only applicable if transformation type is 'abs'. Streaming protocol used. required: [ type ] required: [ x_request_id, transformation ] UploadPostTransformSuccessEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a post-transformation completes successfully. The transformed version of the file is now ready and can be accessed via the provided URL. Note that each post-transformation generates a separate webhook event. properties: type: type: string const: "upload.post-transform.success" created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. request: $ref: "#/components/schemas/PostTransformWebhookRequestInfo" data: type: object properties: fileId: type: string description: Unique identifier of the originally uploaded file. url: type: string format: uri description: URL of the generated post-transformation. name: type: string description: Name of the file. required: [ fileId, url, name ] required: [ type, created_at, request, data ] UploadPostTransformErrorEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a post-transformation fails. The original file remains available, but the requested transformation could not be generated. properties: type: type: string const: "upload.post-transform.error" created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. request: $ref: "#/components/schemas/PostTransformWebhookRequestInfo" data: type: object properties: fileId: type: string description: Unique identifier of the originally uploaded file. url: type: string format: uri description: URL of the attempted post-transformation. name: type: string description: Name of the file. path: type: string description: Path of the file. transformation: type: object properties: error: type: object properties: reason: type: string description: Reason for the post-transformation failure. example: "encoding_failed" required: [ reason ] required: [ error ] required: [ fileId, url, name, path, transformation ] required: [ type, created_at, request, data ] FileCreateEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a file is created. properties: type: type: string const: "file.created" description: Type of the webhook event. created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. data: $ref: "#/components/schemas/FileDetails" required: [ type, created_at, data ] FileUpdateEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a file is updated. properties: type: type: string const: "file.updated" description: Type of the webhook event. created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. data: $ref: "#/components/schemas/FileDetails" required: [ type, created_at, data ] FileVersionCreateEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a file version is created. properties: type: type: string const: "file-version.created" description: Type of the webhook event. created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. data: $ref: "#/components/schemas/FileDetails" required: [ type, created_at, data ] FileDeleteEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a file is deleted. properties: type: type: string const: "file.deleted" description: Type of the webhook event. created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. data: type: object properties: fileId: type: string description: The unique `fileId` of the deleted file. required: [ fileId ] required: [ type, created_at, data ] FileVersionDeleteEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a file version is deleted. properties: type: type: string const: "file-version.deleted" description: Type of the webhook event. created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. data: type: object properties: fileId: type: string description: The unique `fileId` of the deleted file. versionId: type: string description: The unique `versionId` of the deleted file version. required: [ fileId, versionId ] required: [ type, created_at, data ] FolderCreateEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a folder is created, whether explicitly, by copying or moving a folder, or implicitly when an upload creates missing parent folders. Copying or moving a folder tree sends one event per folder in the tree. properties: type: type: string const: "folder.created" description: Type of the webhook event. created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. data: $ref: "#/components/schemas/FolderDetails" required: [ type, created_at, data ] FolderUpdateEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a folder is updated, for example when its custom metadata changes or it is renamed. Renaming a folder sends one event per folder in the tree, each with its new `folderPath`. properties: type: type: string const: "folder.updated" description: Type of the webhook event. created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. data: $ref: "#/components/schemas/FolderDetails" required: [ type, created_at, data ] FolderDeleteEvent: allOf: - $ref: "#/components/schemas/BaseWebhookEvent" - type: object description: | Triggered when a folder is deleted. Deleting a folder tree sends one event per folder in the tree; the files inside it send `file.deleted` events and their versions send `file-version.deleted` events. Moving a folder sends this event for the old `folderId` and `folder.created` for the new one. properties: type: type: string const: "folder.deleted" description: Type of the webhook event. created_at: type: string format: date-time description: Timestamp of when the event occurred in ISO8601 format. data: $ref: "#/components/schemas/FolderDeleteData" required: [ type, created_at, data ] FolderDeleteData: type: object properties: folderId: type: string description: The unique `folderId` of the deleted folder. required: [ folderId ] SrcOptions: title: Source Options description: Options for generating ImageKit URLs with transformations. See the [Transformations guide](https://imagekit.io/docs/transformations). type: object required: - src - urlEndpoint properties: src: type: string description: | Accepts a relative or absolute path of the resource. If a relative path is provided, it is appended to the `urlEndpoint`. If an absolute path is provided, `urlEndpoint` is ignored. example: "/my-image.jpg" urlEndpoint: type: string format: uri description: | Get your urlEndpoint from the [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints). example: "https://ik.imagekit.io/demo" transformation: type: array items: $ref: "#/components/schemas/Transformation" description: | An array of objects specifying the transformations to be applied in the URL. If more than one transformation is specified, they are applied in the order they are specified as chained transformations. See [Chained transformations](https://imagekit.io/docs/transformations#chained-transformations). queryParameters: type: object additionalProperties: type: string description: | These are additional query parameters that you want to add to the final URL. They can be any query parameters and not necessarily related to ImageKit. This is especially useful if you want to add a versioning parameter to your URLs. transformationPosition: $ref: "#/components/schemas/TransformationPosition" signed: type: boolean default: false description: | Whether to sign the URL or not. Set this to `true` if you want to generate a signed URL. If `signed` is `true` and `expiresIn` is not specified, the signed URL will not expire (valid indefinitely). Note: If `expiresIn` is set to any value above 0, the URL will always be signed regardless of this setting. [Learn more](https://imagekit.io/docs/media-delivery-basic-security#how-to-generate-signed-urls). expiresIn: type: number description: | When you want the signed URL to expire, specified in seconds. If `expiresIn` is anything above 0, the URL will always be signed even if `signed` is set to false. If not specified and `signed` is `true`, the signed URL will not expire (valid indefinitely). Example: Setting `expiresIn: 3600` will make the URL expire 1 hour from generation time. After the expiry time, the signed URL will no longer be valid and ImageKit will return a 401 Unauthorized status code. [Learn more](https://imagekit.io/docs/media-delivery-basic-security#how-to-generate-signed-urls). additionalProperties: false GetImageAttributesOptions: title: Get Image Attributes Options description: | Options for generating responsive image attributes including `src`, `srcSet`, and `sizes` for HTML `` elements. This schema extends `SrcOptions` to add support for responsive image generation with breakpoints. type: object allOf: - $ref: "#/components/schemas/SrcOptions" - type: object properties: width: type: number description: | The intended display width of the image in pixels, used **only when the `sizes` attribute is not provided**. Triggers a DPR-based strategy (1x and 2x variants) and generates `x` descriptors in `srcSet`. Ignored if `sizes` is present. example: 400 sizes: type: string description: | The value for the HTML `sizes` attribute (e.g., `"100vw"` or `"(min-width:768px) 50vw, 100vw"`). - If it includes one or more `vw` units, breakpoints smaller than the corresponding percentage of the smallest device width are excluded. - If it contains no `vw` units, the full breakpoint list is used. Enables a width-based strategy and generates `w` descriptors in `srcSet`. example: "(min-width: 768px) 50vw, 100vw" deviceBreakpoints: type: array items: type: number description: | Custom list of **device-width breakpoints** in pixels. These define common screen widths for responsive image generation. Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`. Sorted automatically. example: [ 640, 750, 828, 1080, 1200, 1920, 2048, 3840 ] imageBreakpoints: type: array items: type: number description: | Custom list of **image-specific breakpoints** in pixels. Useful for generating small variants (e.g., placeholders or thumbnails). Merged with `deviceBreakpoints` before calculating `srcSet`. Defaults to `[16, 32, 48, 64, 96, 128, 256, 384]`. Sorted automatically. example: [ 16, 32, 48, 64, 96, 128, 256, 384 ] ResponsiveImageAttributes: title: Responsive Image Attributes description: | Resulting set of attributes suitable for an HTML `` element. Useful for enabling responsive image loading with `srcSet` and `sizes`. type: object required: - src properties: src: type: string format: uri description: URL for the *largest* candidate (assigned to plain `src`). example: "https://ik.imagekit.io/demo/image.jpg?tr=w-3840" srcSet: type: string description: | Candidate set with `w` or `x` descriptors. Multiple image URLs separated by commas, each with a descriptor. example: "https://ik.imagekit.io/demo/image.jpg?tr=w-640 640w, https://ik.imagekit.io/demo/image.jpg?tr=w-1080 1080w, https://ik.imagekit.io/demo/image.jpg?tr=w-1920 1920w" sizes: type: string description: | `sizes` returned (or synthesised as `100vw`). The value for the HTML `sizes` attribute. example: "100vw" width: type: number description: Width as a number (if `width` was provided in the input options). example: 400 TransformationPosition: type: string enum: [ "path", "query" ] description: | By default, the transformation string is added as a query parameter in the URL, e.g., `?tr=w-100,h-100`. If you want to add the transformation string in the path of the URL, set this to `path`. Learn more in the [Transformations guide](https://imagekit.io/docs/transformations). StreamingResolution: type: string enum: [ "240", "360", "480", "720", "1080", "1440", "2160" ] description: Available streaming resolutions for [adaptive bitrate streaming](https://imagekit.io/docs/adaptive-bitrate-streaming) Transformation: title: Transformation description: | The SDK provides easy-to-use names for transformations. These names are converted to the corresponding transformation string before being added to the URL. SDKs are updated regularly to support new transformations. If you want to use a transformation that is not supported by the SDK, You can use the `raw` parameter to pass the transformation string directly. See the [Transformations documentation](https://imagekit.io/docs/transformations). type: object properties: width: oneOf: - type: number - type: string description: | Specifies the width of the output. If a value between 0 and 1 is provided, it is treated as a percentage (e.g., `0.4` represents 40% of the original width). You can also supply arithmetic expressions (e.g., `iw_div_2`). Width transformation – [Images](https://imagekit.io/docs/image-resize-and-crop#width---w) · [Videos](https://imagekit.io/docs/video-resize-and-crop#width---w) example: 300 height: oneOf: - type: number - type: string description: | Specifies the height of the output. If a value between 0 and 1 is provided, it is treated as a percentage (e.g., `0.5` represents 50% of the original height). You can also supply arithmetic expressions (e.g., `ih_mul_0.5`). Height transformation – [Images](https://imagekit.io/docs/image-resize-and-crop#height---h) · [Videos](https://imagekit.io/docs/video-resize-and-crop#height---h) example: 200 aspectRatio: oneOf: - type: number - type: string description: | Specifies the aspect ratio for the output, e.g., "ar-4-3". Typically used with either width or height (but not both). For example: aspectRatio = `4:3`, `4_3`, or an expression like `iar_div_2`. See [Image resize and crop – Aspect ratio](https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar). example: "4:3" background: type: string description: | Specifies the background to be used in conjunction with certain cropping strategies when resizing an image. - A solid color: e.g., `red`, `F3F3F3`, `AAFF0010`. See [Solid color background](https://imagekit.io/docs/effects-and-enhancements#solid-color-background). - Dominant color: `dominant` extracts the dominant color from the image. See [Dominant color background](https://imagekit.io/docs/effects-and-enhancements#dominant-color-background). - Gradient: `gradient_dominant` or `gradient_dominant_2` creates a gradient using the dominant colors. Optionally specify palette size (2 or 4), e.g., `gradient_dominant_4`. See [Gradient background](https://imagekit.io/docs/effects-and-enhancements#gradient-background). - A blurred background: e.g., `blurred`, `blurred_25_N15`, etc. See [Blurred background](https://imagekit.io/docs/effects-and-enhancements#blurred-background). - Expand the image boundaries using generative fill: `genfill`. Not supported inside overlay. Optionally, control the background scene by passing a text prompt: `genfill[:-prompt-${text}]` or `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. See [Generative fill background](https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill). example: "red" border: type: string description: | Adds a border to the output media. Accepts a string in the format `_` (e.g., `5_FFF000` for a 5px yellow border), or an expression like `ih_div_20_FF00FF`. See [Border](https://imagekit.io/docs/effects-and-enhancements#border---b). example: "5_FF0000" crop: type: string enum: [ "force", "at_max", "at_max_enlarge", "at_least", "maintain_ratio", "maintain_ratio_no_enlarge" ] description: Crop modes for image resizing. See [Crop modes & focus](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus). cropMode: type: string enum: [ "pad_resize", "extract", "pad_extract", "pad_resize_no_enlarge", "pad_extract_no_shrink" ] description: Additional crop modes for image resizing. See [Crop modes & focus](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus). dpr: type: number minimum: 0.1 maximum: 5 description: | Accepts values between 0.1 and 5, or `auto` for automatic device pixel ratio (DPR) calculation. Also accepts arithmetic expressions. - Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). - See [DPR](https://imagekit.io/docs/image-resize-and-crop#dpr---dpr). example: 2 focus: type: string description: | Refines padding and cropping behavior for pad resize, maintain ratio, and extract crop modes. Supports manual positions and coordinate-based focus. With AI-based cropping, you can automatically keep key subjects in frame—such as faces or detected objects (e.g., `fo-face`, `fo-person`, `fo-car`)— while resizing. - See [Focus](https://imagekit.io/docs/image-resize-and-crop#focus---fo). - [Object aware cropping](https://imagekit.io/docs/image-resize-and-crop#object-aware-cropping---fo-object-name) example: "center" quality: type: number minimum: 1 maximum: 100 description: | Specifies the quality of the output image for lossy formats such as JPEG, WebP, and AVIF. A higher quality value results in a larger file size with better quality, while a lower value produces a smaller file size with reduced quality. See [Quality](https://imagekit.io/docs/image-optimization#quality---q). example: 80 x: oneOf: - type: number - type: string description: Focus using cropped image coordinates - X coordinate. See [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). xCenter: oneOf: - type: number - type: string description: Focus using cropped image coordinates - X center coordinate. See [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). y: oneOf: - type: number - type: string description: Focus using cropped image coordinates - Y coordinate. See [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). yCenter: oneOf: - type: number - type: string description: Focus using cropped image coordinates - Y center coordinate. See [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). format: type: string enum: [ "auto", "webp", "jpg", "jpeg", "png", "gif", "svg", "mp4", "webm", "avif", "orig" ] description: | Specifies the output format for images or videos, e.g., `jpg`, `png`, `webp`, `mp4`, or `auto`. You can also pass `orig` for images to return the original format. ImageKit automatically delivers images and videos in the optimal format based on device support unless overridden by the dashboard settings or the format parameter. See [Image format](https://imagekit.io/docs/image-optimization#format---f) and [Video format](https://imagekit.io/docs/video-optimization#format---f). videoCodec: type: string enum: [ "h264", "vp9", "av1", "none" ] description: Specifies the video codec, e.g., `h264`, `vp9`, `av1`, or `none`. See [Video codec](https://imagekit.io/docs/video-optimization#video-codec---vc). audioCodec: type: string enum: [ "aac", "opus", "none" ] description: Specifies the audio codec, e.g., `aac`, `opus`, or `none`. See [Audio codec](https://imagekit.io/docs/video-optimization#audio-codec---ac). radius: anyOf: - type: number - const: "max" - type: string description: | Specifies the corner radius for rounded corners. - Single value (positive integer): Applied to all corners (e.g., `20`). - `max`: Creates a circular or oval shape. - Per-corner array: Provide four underscore-separated values representing top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., `10_20_30_40`). See [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). example: 20 rotation: oneOf: - type: number - type: string description: | Specifies the rotation angle in degrees. Positive values rotate the image clockwise; you can also use, for example, `N40` for counterclockwise rotation or `auto` to use the orientation specified in the image's EXIF data. For videos, only the following values are supported: 0, 90, 180, 270, or 360. See [Rotate](https://imagekit.io/docs/effects-and-enhancements#rotate---rt). example: 90 blur: type: number minimum: 1 maximum: 100 description: | Specifies the Gaussian blur level. Accepts an integer value between 1 and 100, or an expression like `bl-10`. See [Blur](https://imagekit.io/docs/effects-and-enhancements#blur---bl). example: 10 named: type: string description: Named transformation reference. See [Named transformations](https://imagekit.io/docs/transformations#named-transformations). defaultImage: type: string description: | Specifies a fallback image if the resource is not found, e.g., a URL or file path. See [Default image](https://imagekit.io/docs/image-transformation#default-image---di). flip: type: string enum: [ "h", "v", "h_v", "v_h" ] description: | Flips or mirrors an image either horizontally, vertically, or both. Acceptable values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or `v_h`. See [Flip](https://imagekit.io/docs/effects-and-enhancements#flip---fl). original: type: boolean description: | If set to true, serves the original file without applying any transformations. See [Deliver original file as-is](https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true). startOffset: oneOf: - type: number - type: string description: | Specifies the start offset (in seconds) for trimming videos, e.g., `5` or `10.5`. Arithmetic expressions are also supported. See [Trim videos – Start offset](https://imagekit.io/docs/trim-videos#start-offset---so). endOffset: oneOf: - type: number - type: string description: | Specifies the end offset (in seconds) for trimming videos, e.g., `5` or `10.5`. Typically used with startOffset to define a time window. Arithmetic expressions are supported. See [Trim videos – End offset](https://imagekit.io/docs/trim-videos#end-offset---eo). duration: oneOf: - type: number - type: string description: | Specifies the duration (in seconds) for trimming videos, e.g., `5` or `10.5`. Typically used with startOffset to indicate the length from the start offset. Arithmetic expressions are supported. See [Trim videos – Duration](https://imagekit.io/docs/trim-videos#duration---du). streamingResolutions: type: array items: $ref: "#/components/schemas/StreamingResolution" description: | An array of resolutions for adaptive bitrate streaming, e.g., [`240`, `360`, `480`, `720`, `1080`]. See [Adaptive Bitrate Streaming](https://imagekit.io/docs/adaptive-bitrate-streaming). grayscale: const: true description: Enables a grayscale effect for images. See [Grayscale](https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale). aiUpscale: const: true description: | Upscales images beyond their original dimensions using AI. Not supported inside overlay. See [AI Upscale](https://imagekit.io/docs/ai-transformations#upscale-e-upscale). aiRetouch: const: true description: | Performs AI-based retouching to improve faces or product shots. Not supported inside overlay. See [AI Retouch](https://imagekit.io/docs/ai-transformations#retouch-e-retouch). aiVariation: const: true description: | Generates a variation of an image using AI. This produces a new image with slight variations from the original, such as changes in color, texture, and other visual elements, while preserving the structure and essence of the original image. Not supported inside overlay. See [AI Generate Variations](https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar). aiDropShadow: oneOf: - const: true - type: string description: | Adds an AI-based drop shadow around a foreground object on a transparent or removed background. Optionally, control the direction, elevation, and saturation of the light source (e.g., `az-45` to change light direction). Pass `true` for the default drop shadow, or provide a string for a custom drop shadow. Supported inside overlay. See [AI Drop Shadow](https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow). aiChangeBackground: type: string description: | Uses AI to change the background. Provide a text prompt or a base64-encoded prompt, e.g., `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. Not supported inside overlay. See [AI Change Background](https://imagekit.io/docs/ai-transformations#change-background-e-changebg). aiRemoveBackground: const: true description: | Applies ImageKit's in-house background removal. Supported inside overlay. See [AI Background Removal](https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove). aiRemoveBackgroundExternal: const: true description: | Uses third-party background removal. Note: It is recommended to use aiRemoveBackground, ImageKit's in-house solution, which is more cost-effective. Supported inside overlay. See [External Background Removal](https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg). aiEdit: type: string description: | Uses AI to edit images based on a text prompt. Provide a text prompt or a base64-encoded prompt, e.g., `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. Not supported inside overlay. See [AI Edit](https://imagekit.io/docs/ai-transformations#edit-image-e-edit). contrastStretch: const: true description: | Automatically enhances the contrast of an image (contrast stretch). See [Contrast Stretch](https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast). shadow: oneOf: - const: true - type: string description: | Adds a shadow beneath solid objects in an image with a transparent background. For AI-based drop shadows, refer to aiDropShadow. Pass `true` for a default shadow, or provide a string for a custom shadow. See [Shadow](https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow). sharpen: oneOf: - const: true - type: number description: | Sharpens the input image, highlighting edges and finer details. Pass `true` for default sharpening, or provide a numeric value for custom sharpening. See [Sharpen](https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen). unsharpMask: oneOf: - const: true - type: string description: | Applies Unsharp Masking (USM), an image sharpening technique. Pass `true` for a default unsharp mask, or provide a string for a custom unsharp mask. See [Unsharp Mask](https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm). gradient: oneOf: - const: true - type: string description: | Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. See [Gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient). progressive: type: boolean description: | Specifies whether the output JPEG image should be rendered progressively. Progressive loading begins with a low-quality, pixelated version of the full image, which gradually improves to provide a faster perceived load time. See [Progressive images](https://imagekit.io/docs/image-optimization#progressive-image---pr). lossless: type: boolean description: | Specifies whether the output image (in JPEG or PNG) should be compressed losslessly. See [Lossless compression](https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo). colorProfile: type: boolean description: | Indicates whether the output image should retain the original color profile. See [Color profile](https://imagekit.io/docs/image-optimization#color-profile---cp). metadata: type: boolean description: | By default, ImageKit removes all metadata during automatic image compression. Set this to true to preserve metadata. See [Image metadata](https://imagekit.io/docs/image-optimization#image-metadata---md). density: oneOf: - type: integer minimum: 1 maximum: 1200 - type: string description: | Sets the output image density in dots per inch (DPI). Accepts an integer from 1 to 1200 or an arithmetic expression using the `idn` variable, such as `idn_mul_2`. For raster images, this updates density metadata without changing dimensions. For vector images, it controls the DPI used during rasterization. Cannot be used inside layers. See [Density](https://imagekit.io/docs/image-optimization#density---dn). example: 300 opacity: type: number minimum: 0 maximum: 100 description: Specifies the opacity level of the output image. See [Opacity](https://imagekit.io/docs/effects-and-enhancements#opacity---o). trim: oneOf: - const: true - type: number description: | Useful for images with a solid or nearly solid background and a central object. This parameter trims the background, leaving only the central object in the output image. See [Trim edges](https://imagekit.io/docs/effects-and-enhancements#trim-edges---t). zoom: type: number description: | Accepts a numeric value that determines how much to zoom in or out of the cropped area. It should be used in conjunction with fo-face or fo-. See [Zoom](https://imagekit.io/docs/image-resize-and-crop#zoom---z). page: oneOf: - type: number - type: string description: | Extracts a specific page or frame from multi-page or layered files (PDF, PSD, AI). For example, specify by number (e.g., `2`), a range (e.g., `3-4` for the 2nd and 3rd layers), or by name (e.g., `name-layer-4` for a PSD layer). See [Thumbnail extraction](https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files). colorReplace: type: string description: | Replaces colors in the image. Supports three formats: - `toColor` - Replace dominant color with the specified color. - `toColor_tolerance` - Replace dominant color with specified tolerance (0-100). - `toColor_tolerance_fromColor` - Replace a specific color with another within tolerance range. Colors can be hex codes (e.g., `FF0022`) or names (e.g., `red`, `blue`). See [Color replacement](https://imagekit.io/docs/effects-and-enhancements#color-replace---cr). colorize: type: string description: | Applies a color tint to the image. Accepts color and intensity as optional parameters. - `co-color` - Color to apply (e.g., `red`, `blue`, `FF0022`). Default is gray color. - `in-intensity` - Intensity of the color (0-100). Default is 100. See [Colorize](https://imagekit.io/docs/effects-and-enhancements#colorize---e-colorize). distort: type: string description: | Distorts the shape of an image. Supports two modes: - Perspective distortion: `p-x1_y1_x2_y2_x3_y3_x4_y4` changes the position of the four corners starting clockwise from top-left. - Arc distortion: `a-degrees` curves the image upwards (positive values) or downwards (negative values). See [Distort effect](https://imagekit.io/docs/effects-and-enhancements#distort---e-distort). raw: type: string description: | Pass any transformation not directly supported by the SDK. This transformation string is appended to the URL as provided. overlay: $ref: "#/components/schemas/Overlay" additionalProperties: false Overlay: title: Overlay description: | Specifies an overlay to be applied on the parent image or video. ImageKit supports overlays including images, text, videos, subtitles, and solid colors. See [Overlay using layers](https://imagekit.io/docs/transformations#overlay-using-layers). discriminator: propertyName: type oneOf: - $ref: "#/components/schemas/TextOverlay" - $ref: "#/components/schemas/ImageOverlay" - $ref: "#/components/schemas/VideoOverlay" - $ref: "#/components/schemas/SubtitleOverlay" - $ref: "#/components/schemas/SolidColorOverlay" BaseOverlay: type: object properties: position: $ref: "#/components/schemas/OverlayPosition" description: | Specifies the overlay's position relative to the parent asset. See [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer). timing: $ref: "#/components/schemas/OverlayTiming" description: | Specifies timing information for the overlay (only applicable if the base asset is a video). See [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer). layerMode: type: string enum: [ "multiply", "cutter", "cutout", "displace" ] description: | Controls how the layer blends with the base image or underlying content. Maps to `lm` in the URL. By default, layers completely cover the base image beneath them. Layer modes change this behavior: - `multiply`: Multiplies the pixel values of the layer with the base image. The result is always darker than the original images. This is ideal for applying shadows or color tints. - `displace`: Uses the layer as a displacement map to distort pixels in the base image. The red channel controls horizontal displacement, and the green channel controls vertical displacement. Requires `x` or `y` parameter to control displacement magnitude. - `cutout`: Acts as an inverse mask where opaque areas of the layer turn the base image transparent, while transparent areas leave the base image unchanged. This mode functions like a hole-punch, effectively cutting the shape of the layer out of the underlying image. - `cutter`: Acts as a shape mask where only the parts of the base image that fall inside the opaque area of the layer are preserved. This mode functions like a cookie-cutter, trimming the base image to match the specific dimensions and shape of the layer. See [Layer modes](https://imagekit.io/docs/add-overlays-on-images#layer-modes). additionalProperties: false OverlayPosition: type: object properties: x: oneOf: - type: number - type: string description: | Specifies the x-coordinate of the top-left corner of the base asset where the overlay's top-left corner will be positioned. It also accepts arithmetic expressions such as `bw_mul_0.4` or `bw_sub_cw`. Maps to `lx` in the URL. Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). y: oneOf: - type: number - type: string description: | Specifies the y-coordinate of the top-left corner of the base asset where the overlay's top-left corner will be positioned. It also accepts arithmetic expressions such as `bh_mul_0.4` or `bh_sub_ch`. Maps to `ly` in the URL. Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). xCenter: oneOf: - type: number - type: string description: | Specifies the x-coordinate on the base asset where the overlay's center will be positioned. It also accepts arithmetic expressions such as `bw_mul_0.4` or `bw_sub_cw`. Maps to `lxc` in the URL. Cannot be used together with `x`, but can be used with `y`. Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). yCenter: oneOf: - type: number - type: string description: | Specifies the y-coordinate on the base asset where the overlay's center will be positioned. It also accepts arithmetic expressions such as `bh_mul_0.4` or `bh_sub_ch`. Maps to `lyc` in the URL. Cannot be used together with `y`, but can be used with `x`. Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). anchorPoint: type: string enum: [ "top", "left", "right", "bottom", "top_left", "top_right", "bottom_left", "bottom_right", "center" ] description: | Sets the anchor point on the base asset from which the overlay offset is calculated. The default value is `top_left`. Maps to `lap` in the URL. Can only be used with one or more of `x`, `y`, `xCenter`, or `yCenter`. focus: type: string enum: [ "center", "top", "left", "bottom", "right", "top_left", "top_right", "bottom_left", "bottom_right" ] description: | Specifies the position of the overlay relative to the parent image or video. If one or more of `x`, `y`, `xCenter`, or `yCenter` parameters are specified, this parameter is ignored. Maps to `lfo` in the URL. additionalProperties: false OverlayTiming: type: object properties: start: oneOf: - type: number - type: string description: | Specifies the start time (in seconds) for when the overlay should appear on the base video. Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. Applies only if the base asset is a video. Maps to `lso` in the URL. duration: oneOf: - type: number - type: string description: | Specifies the duration (in seconds) during which the overlay should appear on the base video. Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. Applies only if the base asset is a video. Maps to `ldu` in the URL. end: oneOf: - type: number - type: string description: | Specifies the end time (in seconds) for when the overlay should disappear from the base video. If both end and duration are provided, duration is ignored. Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. Applies only if the base asset is a video. Maps to `leo` in the URL. additionalProperties: false TextOverlay: allOf: - $ref: "#/components/schemas/BaseOverlay" - type: object required: - type - text properties: type: type: string const: "text" text: type: string description: Specifies the text to be displayed in the overlay. The SDK automatically handles special characters and encoding. encoding: type: string enum: [ "auto", "plain", "base64" ] default: "auto" description: | Text can be included in the layer as either `i-{input}` (plain text) or `ie-{base64_encoded_input}` (base64). By default, the SDK selects the appropriate format based on the input text. To always use base64 (`ie-{base64}`), set this parameter to `base64`. To always use plain text (`i-{input}`), set it to `plain`. Regardless of the encoding method, the input text is always percent-encoded to ensure it is URL-safe. transformation: type: array items: $ref: "#/components/schemas/TextOverlayTransformation" description: Control styling of the text overlay. See [Text overlays](https://imagekit.io/docs/add-overlays-on-images#text-overlay). additionalProperties: false ImageOverlay: allOf: - $ref: "#/components/schemas/BaseOverlay" - type: object required: - type - input properties: type: type: string const: "image" input: type: string description: Specifies the relative path to the image used as an overlay. encoding: type: string enum: [ "auto", "plain", "base64" ] default: "auto" description: | The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate format automatically. To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. To always use plain text (`i-{input}`), set it to `plain`. Regardless of the encoding method: - Leading and trailing slashes are removed. - Remaining slashes within the path are replaced with `@@` when using plain text. transformation: type: array items: $ref: "#/components/schemas/Transformation" description: | Array of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset. See overlays on [Images](https://imagekit.io/docs/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) and [Videos](https://imagekit.io/docs/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay). additionalProperties: false VideoOverlay: allOf: - $ref: "#/components/schemas/BaseOverlay" - type: object required: - type - input properties: type: type: string const: "video" input: type: string description: Specifies the relative path to the video used as an overlay. encoding: type: string enum: [ "auto", "plain", "base64" ] default: "auto" description: | The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate format automatically. To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. To always use plain text (`i-{input}`), set it to `plain`. Regardless of the encoding method: - Leading and trailing slashes are removed. - Remaining slashes within the path are replaced with `@@` when using plain text. transformation: type: array items: $ref: "#/components/schemas/Transformation" description: | Array of transformation to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported. See [Video transformations](https://imagekit.io/docs/video-transformation). additionalProperties: false SubtitleOverlay: allOf: - $ref: "#/components/schemas/BaseOverlay" - type: object required: - type - input properties: type: type: string const: "subtitle" input: type: string description: Specifies the relative path to the subtitle file used as an overlay. encoding: type: string enum: [ "auto", "plain", "base64" ] default: "auto" description: | The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate format automatically. To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. To always use plain text (`i-{input}`), set it to `plain`. Regardless of the encoding method: - Leading and trailing slashes are removed. - Remaining slashes within the path are replaced with `@@` when using plain text. transformation: type: array items: $ref: "#/components/schemas/SubtitleOverlayTransformation" description: Control styling of the subtitle. See [Styling subtitles](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer). additionalProperties: false SolidColorOverlay: allOf: - $ref: "#/components/schemas/BaseOverlay" - type: object required: - type - color properties: type: type: string const: "solidColor" color: type: string description: | Specifies the color of the block using an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name (e.g., `red`). If an 8-character value is provided, the last two characters represent the opacity level (from `00` for 0.00 to `99` for 0.99). transformation: type: array items: $ref: "#/components/schemas/SolidColorOverlayTransformation" description: | Control width and height of the solid color overlay. Supported transformations depend on the base/parent asset. See overlays on [Images](https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay) and [Videos](https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay). additionalProperties: false TextOverlayTransformation: type: object properties: width: oneOf: - type: number - type: string description: | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are supported. Useful when used in conjunction with the `background`. Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). fontSize: oneOf: - type: number - type: string description: Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression. fontFamily: type: string description: | Specifies the font family of the overlaid text. Choose from the supported fonts list or use a custom font. See [Supported fonts](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) and [Custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay). fontColor: type: string description: | Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. innerAlignment: type: string enum: [ "left", "right", "center" ] default: "center" description: | Specifies the inner alignment of the text when width is more than the text length. padding: oneOf: - type: number - type: string description: | Specifies the padding around the overlaid text. Can be provided as a single positive integer or multiple values separated by underscores (following CSS shorthand order). Arithmetic expressions are also accepted. alpha: type: number minimum: 1 maximum: 9 description: Specifies the transparency level of the text overlay. Accepts integers from `1` to `9`. typography: type: string description: | Specifies the typography style of the text. Supported values: - Single styles: `b` (bold), `i` (italic), `strikethrough`. - Combinations: Any combination separated by underscores, e.g., `b_i`, `b_i_strikethrough`. background: type: string description: | Specifies the background color of the text overlay. Accepts an RGB hex code, an RGBA code, or a color name. radius: anyOf: - type: number - const: "max" - type: string description: | Specifies the corner radius: - Single value (positive integer): Applied to all corners (e.g., `20`). - `max`: Creates a circular or oval shape. - Per-corner array: Provide four underscore-separated values representing top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., `10_20_30_40`). See [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). rotation: oneOf: - type: number - type: string description: | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with "N" for counter-clockwise rotation. flip: type: string enum: [ "h", "v", "h_v", "v_h" ] description: | Flip/mirror the text horizontally, vertically, or in both directions. Acceptable values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or `v_h`. lineHeight: oneOf: - type: number - type: string description: | Specifies the line height for multi-line text overlays. It will come into effect only if the text wraps over multiple lines. Accepts either an integer value or an arithmetic expression. additionalProperties: false SubtitleOverlayTransformation: type: object description: Subtitle styling options. [Learn more](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) from the docs. properties: background: type: string description: | Specifies the subtitle background color using a standard color name, an RGB color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50). [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) fontSize: type: number description: | Sets the font size of subtitle text. [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) fontFamily: type: string description: | Sets the font family of subtitle text. Refer to the [supported fonts documented](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) in the ImageKit transformations guide. color: type: string description: | Sets the font color of the subtitle text using a standard color name, an RGB color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50). [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) typography: type: string enum: [ "b", "i", "b_i" ] description: | Sets the typography style of the subtitle text. Supports values are `b` for bold, `i` for italics, and `b_i` for bold with italics. [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) fontOutline: type: string description: | Sets the font outline of the subtitle text. Requires the outline width (an integer) and the outline color (as an RGB color code, RGBA color code, or standard web color name) separated by an underscore. Example: `fol-2_blue` (outline width of 2px and outline color blue), `fol-2_A1CCDD` (outline width of 2px and outline color `#A1CCDD`) and `fol-2_A1CCDD50` (outline width of 2px and outline color `#A1CCDD` at 50% opacity). [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) fontShadow: type: string description: | Sets the font shadow for the subtitle text. Requires the shadow color (as an RGB color code, RGBA color code, or standard web color name) and shadow indent (an integer) separated by an underscore. Example: `fsh-blue_2` (shadow color blue, indent of 2px), `fsh-A1CCDD_3` (shadow color `#A1CCDD`, indent of 3px), `fsh-A1CCDD50_3` (shadow color `#A1CCDD` at 50% opacity, indent of 3px). [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) additionalProperties: false SolidColorOverlayTransformation: type: object properties: width: oneOf: - type: number - type: string description: | Controls the width of the solid color overlay. Accepts a numeric value or an arithmetic expression (e.g., `bw_mul_0.2` or `bh_div_2`). Learn about [arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). height: oneOf: - type: number - type: string description: | Controls the height of the solid color overlay. Accepts a numeric value or an arithmetic expression. Learn about [arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). radius: anyOf: - type: number - const: "max" - type: string description: | Specifies the corner radius of the solid color overlay. - Single value (positive integer): Applied to all corners (e.g., `20`). - `max`: Creates a circular or oval shape. - Per-corner array: Provide four underscore-separated values representing top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., `10_20_30_40`). See [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). alpha: type: number minimum: 1 maximum: 9 description: Specifies the transparency level of the overlaid solid color layer. Supports integers from `1` to `9`. background: type: string description: | Specifies the background color of the solid color overlay. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. gradient: oneOf: - const: true - type: string description: | Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. Only works if the base asset is an image. See [gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient). additionalProperties: false ContractUnits: type: object required: - bandwidthBytes - videoProcessingUnitsCount - extensionUnitsCount - purgeCacheRequests properties: bandwidthBytes: type: integer description: Bandwidth in bytes. videoProcessingUnitsCount: type: integer description: Number of video processing units. extensionUnitsCount: type: integer description: Number of extension units. purgeCacheRequests: type: integer description: Number of purge cache requests. UsageAnalyticsResponse: type: object properties: startDate: description: Start date of the computed analytics data. type: string format: date endDate: description: End date of the computed analytics data. type: string format: date generatedAt: type: string format: date-time description: | Date and time when the analytics data was computed. Use this to gauge how fresh the returned data is. The date and time is in ISO8601 format. requestCount: type: number description: Total number of requests made during the specified date range. bandwidthBytes: type: number description: Total bandwidth, in bytes, utilized during the specified date range. statusCodes: type: array description: Request count grouped by HTTP status code. items: type: object properties: name: type: string description: HTTP status code. example: "200" requestCount: type: number description: Number of requests that received this status code. required: [ name, requestCount ] errorReasons: type: array description: Request count grouped by origin error reason. This covers failed origin fetches, such as an asset not found at origin or an origin timeout. It is not the HTTP status code returned to the client, see `statusCodes` for that. items: type: object properties: name: type: string description: Description of the error reason. example: "ENOENT - Resource not found at any upstream origin" requestCount: type: number description: Number of requests that failed with this error reason. required: [ name, requestCount ] top404Assets: type: array description: Top URLs that returned a 404 response. items: type: object properties: name: type: string description: URL that returned a 404 response. example: https://ik.imagekit.io/demo/products/discontinued-sku-4421.jpg requestCount: type: number description: Number of requests to this URL that returned a 404 response. required: [ name, requestCount ] extensions: type: array description: Raw per-extension operation counts for the date range. These are raw operation counts, not billable extension units. For billable usage, use the `/v1/accounts/usage` endpoint. items: type: object properties: name: type: string description: Extension identifier. example: remove-bg operationCount: type: number description: Number of times this extension ran during the date range. required: [ name, operationCount ] cache: type: object description: CDN cache hit, miss and error counts for the date range. properties: hitCount: type: number description: Number of requests served from cache, including full hits and revalidated hits. missCount: type: number description: Number of requests that were not found in cache and had to be fetched from origin. errorCount: type: number description: Number of requests where the CDN encountered a cache error or exceeded capacity while serving the response. required: [ hitCount, missCount, errorCount ] videoProcessing: type: array description: Raw observed video transcode output duration, in seconds, grouped by resolution and codec. These are raw seconds, not billable Video Processing Units (VPU). For billable VPU totals, use the `/v1/accounts/usage` endpoint. items: type: object properties: resolution: type: string description: Output resolution tier (e.g. `SD`, `HD`, `4K`). codec: type: string description: Video codec used for the output (e.g. `h264`, `av1`). durationSeconds: type: number description: Total output duration, in seconds, for this resolution and codec combination. required: [ resolution, codec, durationSeconds ] country: type: object description: CDN traffic grouped by country. properties: byRequests: description: Top requesting countries sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Country name. code: type: string description: ISO country code. required: [ name, code ] byBandwidth: description: Top requesting countries sorted by total bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Country name. code: type: string description: ISO country code. required: [ name, code ] required: [ byRequests, byBandwidth ] format: type: object description: CDN traffic grouped by response `Content-Type`. properties: byRequests: description: Top content types sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: MIME type (e.g. `image/webp`). required: [ name ] byBandwidth: description: Top content types sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: MIME type (e.g. `image/webp`). required: [ name ] required: [ byRequests, byBandwidth ] device: type: object description: CDN traffic grouped by device and operating system (e.g. `Desktop - Apple Mac`, `Smartphone - Apple iPhone`). properties: byRequests: description: Top device/OS combinations sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Device category combined with operating system or vendor (e.g. `Desktop - Windows PC`). required: [ name ] byBandwidth: description: Top device/OS combinations sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Device category combined with operating system or vendor (e.g. `Desktop - Windows PC`). required: [ name ] required: [ byRequests, byBandwidth ] browser: type: object description: CDN traffic grouped by browser. properties: byRequests: description: Top browsers sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Browser name (e.g. `Chrome`). required: [ name ] byBandwidth: description: Top browsers sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Browser name (e.g. `Chrome`). required: [ name ] required: [ byRequests, byBandwidth ] urlEndpoints: type: object description: CDN traffic grouped by configured URL endpoint. Traffic that does not match any named URL endpoint pattern is grouped under `Default`. properties: byRequests: description: Top URL endpoints sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: URL endpoint name, or `Default` for traffic that does not match a named endpoint. required: [ name ] byBandwidth: description: Top URL endpoints sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: URL endpoint name, or `Default` for traffic that does not match a named endpoint. required: [ name ] required: [ byRequests, byBandwidth ] topImages: type: object description: Top image assets by traffic. properties: byRequests: description: Top image assets sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: URL of the image asset. required: [ name ] byBandwidth: description: Top image assets sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: URL of the image asset. required: [ name ] required: [ byRequests, byBandwidth ] topVideos: type: object description: Top video assets by traffic. properties: byRequests: description: Top video assets sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Full URL of the video asset (e.g. `https://ik.imagekit.io/demo/clip.mp4`). required: [ name ] byBandwidth: description: Top video assets sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: URL of the video asset. required: [ name ] required: [ byRequests, byBandwidth ] topOtherAssets: type: object description: Top non-image, non-video assets by traffic. properties: byRequests: description: Top non-image, non-video assets sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: URL of the non-image, non-video asset. required: [ name ] byBandwidth: description: Top non-image, non-video assets sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: URL of the non-image, non-video asset. required: [ name ] required: [ byRequests, byBandwidth ] topImageTransforms: type: object description: Top image transformation strings by traffic. properties: byRequests: description: Top image transformation strings sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Image transformation string (e.g. `tr:w-400,h-400`). required: [ name ] byBandwidth: description: Top image transformation strings sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Image transformation string (e.g. `tr:w-400,h-400`). required: [ name ] required: [ byRequests, byBandwidth ] topVideoTransforms: type: object description: Top video transformation strings by traffic. properties: byRequests: description: Top video transformation strings sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Video transformation string (e.g. `tr:h-720,f-mp4`). required: [ name ] byBandwidth: description: Top video transformation strings sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Video transformation string (e.g. `tr:h-720,f-mp4`). required: [ name ] required: [ byRequests, byBandwidth ] topReferrers: type: object description: Top HTTP referrers by traffic. properties: byRequests: description: Top HTTP referrers sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Referrer URL. required: [ name ] byBandwidth: description: Top HTTP referrers sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: Referrer URL. required: [ name ] required: [ byRequests, byBandwidth ] topUserAgents: type: object description: Top user agents by traffic. properties: byRequests: description: Top user agents sorted by request count. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: User agent string. required: [ name ] byBandwidth: description: Top user agents sorted by bandwidth utilized. type: array items: allOf: - $ref: "#/components/schemas/RequestBandwidthEntry" - type: object properties: name: type: string description: User agent string. required: [ name ] required: [ byRequests, byBandwidth ] required: - startDate - endDate - generatedAt - requestCount - bandwidthBytes - statusCodes - errorReasons - top404Assets - extensions - cache - videoProcessing - country - format - device - browser - urlEndpoints - topImages - topVideos - topOtherAssets - topImageTransforms - topVideoTransforms - topReferrers - topUserAgents additionalProperties: true RequestBandwidthEntry: type: object properties: requestCount: type: number description: Number of requests. bandwidthBytes: type: number description: Total bandwidth used in bytes. required: [ requestCount, bandwidthBytes ] examples: UploadResponseWithEmbeddedMetadata: fileId: 6673f88237b244ef54d60180 name: test-image.jpg size: 117079 versionInfo: id: 6673f88237b244ef54d60180 name: Version 1 filePath: "/test-image.jpg" url: https://ik.imagekit.io/demo/test-image.jpg fileType: image height: 500 width: 1000 orientation: 1 thumbnailUrl: https://ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/test-image.jpg AITags: null metadata: height: 500 width: 1000 size: 117079 format: jpg hasColorProfile: false quality: 0 density: 72 hasTransparency: false exif: image: ImageDescription: The description aka caption (ref2019.1) Orientation: 1 XResolution: 72 YResolution: 72 ResolutionUnit: 2 Artist: Creator1 (ref2019.1) YCbCrPositioning: 1 Copyright: Copyright (Notice) 2019.1 IPTC - www.iptc.org (ref2019.1) ExifOffset: 260 thumbnail: {} exif: ExifVersion: "0232" DateTimeOriginal: 2019:10:16 19:01:03 ComponentsConfiguration: "\x01\x02\x03\0" FlashpixVersion: "0100" ColorSpace: 65535 ExifImageWidth: 1000 ExifImageHeight: 500 gps: {} interoperability: {} makernote: {} pHash: 17949d3d3573ebca embeddedMetadata: Orientation: Horizontal (normal) ExifVersion: "0232" ImageDescription: The description aka caption (ref2019.1) XResolution: 72 YResolution: 72 ResolutionUnit: inches Artist: Creator1 (ref2019.1) Copyright: Copyright (Notice) 2019.1 IPTC - www.iptc.org (ref2019.1) DateTimeOriginal: "2019-10-16T19:01:03.000Z" OffsetTimeOriginal: "+00:00" ComponentsConfiguration: Y,Cb,Cr,- FlashpixVersion: "0100" ColorSpace: Uncalibrated ObjectAttributeReference: A Genre (ref2019.1) ObjectName: The Title (ref2019.1) SubjectReference: - IPTC:1ref2019.1 - IPTC:2ref2019.1 - IPTC:3ref2019.1 Keywords: - Keyword1ref2019.1 - Keyword2ref2019.1 - Keyword3ref2019.1 SpecialInstructions: An Instruction (ref2019.1) TimeCreated: 19:01:03+00:00 Byline: Creator1 (ref2019.1) BylineTitle: Creator's Job Title (ref2019.1) Sublocation: Sublocation (Core) (ref2019.1) ProvinceState: Province/State(Core)(ref2019.1) CountryPrimaryLocationCode: R19 CountryPrimaryLocationName: Country (Core) (ref2019.1) OriginalTransmissionReference: Job Id (ref2019.1) CopyrightNotice: Copyright (Notice) 2019.1 IPTC - www.iptc.org (ref2019.1) CaptionAbstract: The description aka caption (ref2019.1) WriterEditor: Description Writer (ref2019.1) ApplicationRecordVersion: 4 CountryCode: R19 CreatorCity: "Creator's CI: City (ref2019.1)" CreatorCountry: "Creator's CI: Country (ref2019.1)" CreatorAddress: "Creator's CI: Address, line 1 (ref2019.1)" CreatorPostalCode: "Creator's CI: Postcode (ref2019.1)" CreatorRegion: "Creator's CI: State/Province (ref2019.1)" CreatorWorkEmail: "Creator's CI: Email@1, Email@2 (ref2019.1)" CreatorWorkTelephone: "Creator's CI: Phone # 1, Phone # 2 (ref2019.1)" CreatorWorkURL: http://www.Creators.CI/WebAddress/ref2019.1 IntellectualGenre: A Genre (ref2019.1) Location: Sublocation (Core) (ref2019.1) Scene: - IPTC-Scene-Code1 (ref2019.1) - IPTC-Scene-Code2 (ref2019.1) SubjectCode: - IPTC:1ref2019.1 - IPTC:2ref2019.1 - IPTC:3ref2019.1 AboutCvTermCvId: http://example.com/cv/about/ref2019.1 AboutCvTermId: http://example.com/cv/about/ref2019.1/code987 AboutCvTermName: CV-Term Name 1 (ref2019.1) AboutCvTermRefinedAbout: http://example.com/cv/refinements2/ref2019.1/codeX145 AdditionalModelInformation: Additional Model Info (ref2019.1) ArtworkCircaDateCreated: "AO Circa Date: between 1550 and 1600 (ref2019.1)" ArtworkContentDescription: AO Content Description 1 (ref2019.1) ArtworkContributionDescription: AO Contribution Description 1 (ref2019.1) ArtworkCopyrightNotice: AO Copyright Notice 1 (ref2019.1) ArtworkCreator: - AO Creator Name 1a (ref2019.1) - AO Creator Name 1b (ref2019.1) ArtworkCreatorID: - AO Creator Id 1a (ref2019.1) - AO Creator Id 1b (ref2019.1) ArtworkCopyrightOwnerID: AO Current Copyright Owner ID 1 (ref2019.1) ArtworkCopyrightOwnerName: AO Current Copyright Owner Name 1 (ref2019.1) ArtworkLicensorID: AO Current Licensor ID 1 (ref2019.1) ArtworkLicensorName: AO Current Licensor Name 1 (ref2019.1) ArtworkDateCreated: "1919-10-16T19:01:00.000Z" ArtworkPhysicalDescription: AO Physical Description 1 (ref2019.1) ArtworkSource: AO Source 1 (ref2019.1) ArtworkSourceInventoryNo: AO Source Inventory No 1 (ref2019.1) ArtworkSourceInvURL: AO Source Inventory URL (ref2019.1) ArtworkStylePeriod: - AO Style Baroque (ref2019.1) - AO Style Italian Baroque (ref2019.1) ArtworkTitle: AO Title 1 (ref2019.1) DigitalImageGUID: http://example.com/imageGUIDs/TestGUID12345/ref2019.1 DigitalSourceType: http://cv.iptc.org/newscodes/digitalsourcetype/softwareImage EmbeddedEncodedRightsExpr: The Encoded Rights Expression (ref2019.1) EmbeddedEncodedRightsExprType: IANA Media Type of ERE (ref2019.1) EmbeddedEncodedRightsExprLangID: http://example.org/RELids/id4711/ref2019.1 Event: An Event (ref2019.1) GenreCvId: http://example.com/cv/genre/ref2019.1 GenreCvTermId: http://example.com/cv/genre/ref2019.1/code1369 GenreCvTermName: Genre CV-Term Name 1 (ref2019.1) GenreCvTermRefinedAbout: http://example.com/cv/genrerefinements2/ref2019.1/codeY864 ImageRegionName: - Listener 1 - Listener 2 - Speaker 1 ImageRegionOrganisationInImageName: - Organisation name no 1 in region persltr2 (ref2019.1) - Organisation name no 1 in region persltr2 (ref2019.1) - Organisation name no 1 in region persltr3 (ref2019.1) ImageRegionPersonInImage: - Person name no 1 in region persltr2 (ref2019.1) - Person name no 1 in region persltr3 (ref2019.1) - Person name no 1 in region persltr1 (ref2019.1) ImageRegionBoundaryH: - 0.385 ImageRegionBoundaryShape: - rectangle - circle - polygon ImageRegionBoundaryUnit: - relative - relative - relative ImageRegionBoundaryW: - 0.127 ImageRegionBoundaryX: - 0.31 - 0.59 ImageRegionBoundaryY: - 0.18 - 0.426 ImageRegionCtypeName: - Region Boundary Content Type Name (ref2019.1) - Region Boundary Content Type Name (ref2019.1) - Region Boundary Content Type Name (ref2019.1) ImageRegionCtypeIdentifier: - https://example.org/rctype/type2019.1a - https://example.org/rctype/type2019.1b - https://example.org/rctype/type2019.1a - https://example.org/rctype/type2019.1b - https://example.org/rctype/type2019.1a - https://example.org/rctype/type2019.1b ImageRegionID: - persltr2 - persltr3 - persltr1 ImageRegionRoleName: - Region Boundary Content Role Name (ref2019.1) - Region Boundary Content Role Name (ref2019.1) - Region Boundary Content Role Name (ref2019.1) ImageRegionRoleIdentifier: - https://example.org/rrole/role2019.1a - https://example.org/rrole/role2019.1b - https://example.org/rrole/role2019.1a - https://example.org/rrole/role2019.1b - https://example.org/rrole/role2019.1a - https://example.org/rrole/role2019.1b ImageRegionBoundaryRx: - 0.068 ImageRegionBoundaryVerticesX: - 0.05 - 0.148 - 0.375 ImageRegionBoundaryVerticesY: - 0.713 - 0.041 - 0.863 LinkedEncodedRightsExpr: http://example.org/linkedrightsexpression/id986/ref2019.1 LinkedEncodedRightsExprType: IANA Media Type of ERE (ref2019.1) LinkedEncodedRightsExprLangID: http://example.org/RELids/id4712/ref2019.1 LocationCreatedCity: City (Location created1) (ref2019.1) LocationCreatedCountryCode: R17 LocationCreatedCountryName: CountryName (Location created1) (ref2019.1) LocationCreatedLocationId: Location Id (Location created1) (ref2019.1) LocationCreatedLocationName: Location Name (Location created1) (ref2019.1) LocationCreatedProvinceState: Province/State (Location created1) (ref2019.1) LocationCreatedSublocation: Sublocation (Location created1) (ref2019.1) LocationCreatedWorldRegion: Worldregion (Location created1) (ref2019.1) LocationCreatedGPSAltitude: 480 m LocationCreatedGPSLatitude: 48,16.5N LocationCreatedGPSLongitude: 16,20.28E LocationShownCity: - City (Location shown1) (ref2019.1) - City (Location shown2) (ref2019.1) LocationShownCountryCode: - R17 - R17 LocationShownCountryName: - CountryName (Location shown1) (ref2019.1) - CountryName (Location shown2) (ref2019.1) LocationShownLocationId: - Location Id 1a(Location shown1) (ref2019.1) - Location Id 1b(Location shown1) (ref2019.1) - Location Id 2a(Location shown2) (ref2019.1) - Location Id 2b(Location shown2) (ref2019.1) LocationShownLocationName: - Location Name (Location shown1) (ref2019.1) - Location Name (Location shown2) (ref2019.1) LocationShownProvinceState: - Province/State (Location shown1) (ref2019.1) - Province/State (Location shown2) (ref2019.1) LocationShownSublocation: - Sublocation (Location shown1) (ref2019.1) - Sublocation (Location shown2) (ref2019.1) LocationShownWorldRegion: - Worldregion (Location shown1) (ref2019.1) - Worldregion (Location shown2) (ref2019.1) LocationShownGPSAltitude: - 140 m - 120 m LocationShownGPSLatitude: - 48,8.82N - 47,57.12N LocationShownGPSLongitude: - 17,5.88E - 16,49.8E MaxAvailHeight: 20 MaxAvailWidth: 19 ModelAge: - 25 - 27 - 30 OrganisationInImageCode: - Organisation Code 1 (ref2019.1) - Organisation Code 2 (ref2019.1) - Organisation Code 3 (ref2019.1) OrganisationInImageName: - Organisation Name 1 (ref2019.1) - Organisation Name 2 (ref2019.1) - Organisation Name 3 (ref2019.1) PersonInImage: - Person Shown 1 (ref2019.1) - Person Shown 2 (ref2019.1) PersonInImageCvTermCvId: - http://example.com/cv/test99/ref2019.1 PersonInImageCvTermId: - http://example.com/cv/test99/code987/ref2019.1 PersonInImageCvTermName: - Person Characteristic Name 1 (ref2019.1) PersonInImageCvTermRefinedAbout: - http://example.com/cv/refinements987/codeY765/ref2019.1 PersonInImageDescription: - Person Description 1 (ref2019.1) PersonInImageId: - http://wikidata.org/item/Q123456789/ref2019.1 - http://freebase.com/m/987654321/ref2019.1 PersonInImageName: - Person Name 1 (ref2019.1) ProductInImageDescription: - Product Description 1 (ref2019.1) ProductInImageGTIN: - 123456782019.1 ProductInImageName: - Product Name 1 (ref2019.1) RegistryEntryRole: - Registry Entry Role ID 1 (ref2019.1) - Registry Entry Role ID 2 (ref2019.1) RegistryItemID: - Registry Image ID 1 (ref2019.1) - Registry Image ID 2 (ref2019.1) RegistryOrganisationID: - Registry Organisation ID 1 (ref2019.1) - Registry Organisation ID 2 (ref2019.1) Creator: Creator1 (ref2019.1) Description: The description aka caption (ref2019.1) Rights: Copyright (Notice) 2019.1 IPTC - www.iptc.org (ref2019.1) Subject: - Keyword1ref2019.1 - Keyword2ref2019.1 - Keyword3ref2019.1 Title: The Title (ref2019.1) AuthorsPosition: Creator's Job Title (ref2019.1) CaptionWriter: Description Writer (ref2019.1) City: City (Core) (ref2019.1) Country: Country (Core) (ref2019.1) Credit: Credit Line (ref2019.1) DateCreated: "2019-10-16T00:00:00.000Z" Headline: The Headline (ref2019.1) Instructions: An Instruction (ref2019.1) Source: Source (ref2019.1) State: Province/State(Core)(ref2019.1) TransmissionReference: Job Id (ref2019.1) CopyrightOwnerID: - Copyright Owner Id 1 (ref2019.1) - Copyright Owner Id 2 (ref2019.1) CopyrightOwnerName: - Copyright Owner Name 1 (ref2019.1) - Copyright Owner Name 2 (ref2019.1) ImageCreatorID: Image Creator Id 1 (ref2019.1) ImageCreatorName: Image Creator Name 1 (ref2019.1) ImageCreatorImageID: Image Creator Image ID (ref2019.1) ImageSupplierID: Image Supplier Id (ref2019.1) ImageSupplierName: Image Supplier Name (ref2019.1) ImageSupplierImageID: Image Supplier Image ID (ref2019.1) LicensorCity: - Licensor City 1 (ref2019.1) - Licensor City 2 (ref2019.1) LicensorCountry: - Licensor Country 1 (ref2019.1) - Licensor Country 2 (ref2019.1) LicensorEmail: - Licensor Email 1 (ref2019.1) - Licensor Email 2 (ref2019.1) LicensorExtendedAddress: - Licensor Ext Addr 1 (ref2019.1) - Licensor Ext Addr 2 (ref2019.1) LicensorID: - Licensor ID 1 (ref2019.1) - Licensor ID 2 (ref2019.1) LicensorName: - Licensor Name 1 (ref2019.1) - Licensor Name 2 (ref2019.1) LicensorPostalCode: - Licensor Postcode 1 (ref2019.1) - Licensor Postcode 2 (ref2019.1) LicensorRegion: - Licensor Region 1 (ref2019.1) - Licensor Region 2 (ref2019.1) LicensorStreetAddress: - Licensor Street Addr 1 (ref2019.1) - Licensor Street Addr 2 (ref2019.1) LicensorTelephone1: - Licensor Phone1 1 (ref2019.1) - Licensor Phone1 2 (ref2019.1) LicensorTelephone2: - Licensor Phone2 1 (ref2019.1) - Licensor Phone2 2 (ref2019.1) LicensorURL: - Licensor URL 1 (ref2019.1) - Licensor URL 2 (ref2019.1) ModelReleaseID: - Model Release ID 1 (ref2019.1) - Model Release ID 2 (ref2019.1) PropertyReleaseID: - Property Release ID 1 (ref2019.1) - Property Release ID 2 (ref2019.1) Rating: 1 UsageTerms: Rights Usage Terms (ref2019.1) WebStatement: http://www.WebStatementOfRights.org/2019.1 DateTimeCreated: "2019-10-16T00:00:00.000Z" Caption: The description aka caption (ref2019.1) Writer: Description Writer (ref2019.1) UploadResponseImage: fileId: 6673f88237b244ef54d60180 name: test-image.jpg size: 117079 versionInfo: id: 6673f88237b244ef54d60180 name: Version 1 filePath: "/test-image.jpg" url: https://ik.imagekit.io/demo/test-image.jpg fileType: image height: 500 width: 1000 orientation: 1 thumbnailUrl: https://ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/test-image.jpg UploadResonseVideo: fileId: 6673f99b37b244ef54d98f11 name: test-video.mp4 size: 1378305 versionInfo: id: 6673f99b37b244ef54d98f11 name: Version 1 filePath: "/test-video.mp4" url: https://ik.imagekit.io/demo/test-video.mp4 height: 720 width: 720 bitRate: 1453966 duration: 7 audioCodec: aac videoCodec: h264 fileType: non-image metadata: height: 720 width: 720 bitRate: 1453966 duration: 7 audioCodec: aac videoCodec: h264 size: 1378305 ImageMetadata: height: 68 width: 100 size: 7749 format: jpg hasColorProfile: true quality: 0 density: 72 hasTransparency: false pHash: f06830ca9f1e3e90 exif: image: Make: Canon Model: Canon EOS 40D Orientation: 1 XResolution: 72 YResolution: 72 ResolutionUnit: 2 Software: GIMP 2.4.5 ModifyDate: 2008:07:31 10:38:11 YCbCrPositioning: 2 ExifOffset: 214 GPSInfo: 978 thumbnail: Compression: 6 XResolution: 72 YResolution: 72 ResolutionUnit: 2 ThumbnailOffset: 1090 ThumbnailLength: 1378 exif: ExposureTime: 0.00625 FNumber: 7.1 ExposureProgram: 1 ISO: 100 ExifVersion: "0221" DateTimeOriginal: 2008:05:30 15:56:01 CreateDate: 2008:05:30 15:56:01 ShutterSpeedValue: 7.375 ApertureValue: 5.625 ExposureCompensation: 0 MeteringMode: 5 Flash: 9 FocalLength: 135 SubSecTime: "00" SubSecTimeOriginal: "00" SubSecTimeDigitized: "00" FlashpixVersion: "0100" ColorSpace: 1 ExifImageWidth: 100 ExifImageHeight: 68 InteropOffset: 948 FocalPlaneXResolution: 4438.356164383562 FocalPlaneYResolution: 4445.969125214408 FocalPlaneResolutionUnit: 2 CustomRendered: 0 ExposureMode: 1 WhiteBalance: 0 SceneCaptureType: 0 gps: GPSVersionID: - 2 - 2 - 0 - 0 interoperability: InteropIndex: R98 InteropVersion: "0100" makernote: {} VideoMetadata: height: 720 width: 1280 bitRate: 546524 duration: 70 audioCodec: aac videoCodec: h264 size: 23490 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 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. webhooks: video.transformation.accepted: post: operationId: video-transformation-accepted summary: Video transformation accepted description: | Triggered when a new video transformation request is accepted for processing. This event is primarily useful for debugging purposes and tracking the start of video transformations. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VideoTransformationAcceptedEvent" responses: "200": description: Acknowledge video.transformation.ready: post: operationId: video-transformation-ready summary: Video transformation ready description: | Triggered when video encoding is finished and the transformed resource is ready to be served. Listen to this webhook and update any flags in your database or CMS so your application can start displaying the transformed video to users. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VideoTransformationReadyEvent" responses: "200": description: Acknowledge video.transformation.error: post: operationId: video-transformation-error summary: Video transformation error description: | Triggered when a video transformation fails during processing. Listen to this webhook to log the error reason and take appropriate action. Check your origin and URL endpoint settings if the reason is related to download failure. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VideoTransformationErrorEvent" responses: "200": description: Acknowledge upload.pre-transform.success: post: operationId: upload-pre-transform-success summary: Pre-transformation success description: | Triggered when a pre-transformation completes successfully. Pre-transformations are applied before the file is uploaded to the Media Library, allowing you to optimize files at ingestion time. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UploadPreTransformSuccessEvent" responses: "200": description: Acknowledge upload.pre-transform.error: post: operationId: upload-pre-transform-error summary: Pre-transformation error description: | Triggered when a pre-transformation fails. The original file upload may have been accepted, but the requested transformation could not be applied. Review the error reason to understand what went wrong. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UploadPreTransformErrorEvent" responses: "200": description: Acknowledge upload.post-transform.success: post: operationId: upload-post-transform-success summary: Post-transformation success description: | Triggered when a post-transformation completes successfully. Post-transformations are applied after the file has been uploaded to the Media Library, generating transformed versions that are ready for immediate delivery. Each post-transformation generates a separate webhook event. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UploadPostTransformSuccessEvent" responses: "200": description: Acknowledge upload.post-transform.error: post: operationId: upload-post-transform-error summary: Post-transformation error description: | Triggered when a post-transformation fails. The original file remains available in the Media Library, but the requested transformation could not be generated. Review the error reason to determine the cause of failure. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UploadPostTransformErrorEvent" responses: "200": description: Acknowledge file.created: post: operationId: file-created summary: File created description: | Triggered when a file is created. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FileCreateEvent" responses: "200": description: Acknowledge file.updated: post: operationId: file-updated summary: File updated description: | Triggered when a file is updated. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FileUpdateEvent" responses: "200": description: Acknowledge file.deleted: post: operationId: file-deleted summary: File deleted description: | Triggered when a file is deleted. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FileDeleteEvent" responses: "200": description: Acknowledge file-version.created: post: operationId: file-version-created summary: File version created description: | Triggered when a file version is created. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FileVersionCreateEvent" responses: "200": description: Acknowledge file-version.deleted: post: operationId: file-version-deleted summary: File version deleted description: | Triggered when a file version is deleted. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FileVersionDeleteEvent" responses: "200": description: Acknowledge folder.created: post: operationId: folder-created summary: Folder created description: | Triggered when a folder is created, whether explicitly, by copying or moving a folder, or implicitly when an upload creates missing parent folders. Copying or moving a folder tree sends one event per folder in the tree. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FolderCreateEvent" responses: "200": description: Acknowledge folder.updated: post: operationId: folder-updated summary: Folder updated description: | Triggered when a folder is updated, for example when its custom metadata changes or it is renamed. Renaming a folder sends one event per folder in the tree, each with its new `folderPath`. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FolderUpdateEvent" responses: "200": description: Acknowledge folder.deleted: post: operationId: folder-deleted summary: Folder deleted description: | Triggered when a folder is deleted. Deleting a folder tree sends one event per folder in the tree; the files inside it send `file.deleted` events and their versions send `file-version.deleted` events. Moving a folder sends this event for the old `folderId` and `folder.created` for the new one. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FolderDeleteEvent" responses: "200": description: Acknowledge security: - basicAuth: []