openapi: 3.0.3
info:
  title: ImageKit Account Management API Custom metadata fields API
  version: 1.0.0
  description: Checkout [API overview](/docs/api-overview) to learn about ImageKit's APIs, authentication, rate limits, and error codes etc.
  contact:
    email: developer@imagekit.io
    name: ImageKit Team
    url: https://imagekit.io
  termsOfService: https://imagekit.io/terms/
servers:
- url: https://api.imagekit.io
security:
- basicAuth: []
tags:
- name: Custom metadata fields
paths:
  /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.
                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.
                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:
      - Custom metadata fields
    get:
      tags:
      - 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/customMetadataFields/{id}:
    patch:
      tags:
      - Custom metadata fields
      operationId: update-existing-field
      summary: Update existing field
      description: 'This API updates the label 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.
                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 or schema should be provided.
                    - A custom metadata field with this label already exists.
                    - 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:
      - 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.
          content:
            application/json:
              schema:
                type: object
                x-stainless-empty-object: true
components:
  responses:
    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.
    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.
  schemas:
    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.

            '
        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
  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