ImageKit Custom metadata fields API
The Custom metadata fields API from ImageKit — 2 operation(s) for custom metadata fields.
OpenAPI Specification
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