openapi.yml

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-<name>`, 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-<name>` 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-<name>` 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 `<asset_type>/<delivery_type>` 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 `<asset_type>/<delivery_type>` 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-<name>`. 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 `<img>` 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 `<img>` 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 `<border-width>_<hex-code>` 
            (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-<object_name>.
            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&#39;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
        <private_api_key> | Authorization: Basic <base64 hash of `private_api_key:`>

        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: []