GET STARTED WITH APIs
Overview
ENDPOINTS
Upload File
Digital Asset Management (DAM)
Custom metadata fields
List all fields
get
Create new field
post
Update existing field
patch
Delete a field
delete
Managing assets
List and search assets
get
Managing folders
Caching
File Metadata
Account Management API
post
https://api.imagekit.io
/v1/customMetadataFields

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.

Request

Body

name
string
required

API name of the custom metadata field. This should be unique across all (including deleted) custom metadata fields.

label
string
required

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
object
required
type
string
required

Type of the custom metadata field.

Allowed values:
TextTextareaNumberDateBooleanSingleSelectMultiSelect
selectOptions
array

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

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.

isValueRequired
boolean

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

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.

maxValue

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.

minLength
number

Minimum length of string. Only set this property if type is set to Text or Textarea.

maxLength
number

Maximum length of string. Only set this property if type is set to Text or Textarea.

Auth
API key
:
Body
Note

Here, you can explore machine-generated code examples. For practical applications, refer to the examples section below, which includes detailed code snippets from the ImageKit SDKs.

curl --request POST \
  --url https://api.imagekit.io/v1/customMetadataFields \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic 123' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "price",
  "label": "price",
  "schema": {
    "type": "Number",
    "minValue": 1000,
    "maxValue": 3000
  }
}'

Responses

Custom metadata field created successfully.

Body

responses
/
201
id
string
required

Unique identifier for the custom metadata field. Use this to update the field.

name
string
required

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
string
required

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
object
required

An object that describes the rules for the custom metadata field value.

type
string
required

Type of the custom metadata field.

Allowed values:
TextTextareaNumberDateBooleanSingleSelectMultiSelect
selectOptions
array

An array of allowed values when field type is SingleSelect or MultiSelect.

Example:
["small","medium","large",30,40,true]
defaultValue

The default value for this custom metadata field. Date type of default value depends on the field type.

isValueRequired
boolean

Specifies if the this custom metadata field is required or not.

minValue

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.

maxValue

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.

minLength
number

Minimum length of string. Only set if type is set to Text or Textarea.

maxLength
number

Maximum length of string. Only set if type is set to Text or Textarea.

1
{
2
  "id": "598821f949c0a938d57563dd",
3
  "name": "price",
4
  "label": "price",
5
  "schema": {
6
    "type": "Number",
7
    "minValue": 1000,
8
    "maxValue": 3000
9
  }
10
}

Examples

Here is the example request to understand the API usage.

Copy
# The unique id of the created custom metadata schema is returned with this api along with key name and schema object.
curl -X POST "https://api.imagekit.io/v1/customMetadataFields" \
-H 'Content-Type: application/json' \
-u your_private_key: -d'
{
    "name": "price",
    "label": "price",
    "schema": {
        "type": "Number",
        "minValue": 1000,
        "maxValue": 3000
    }
}
'

var ImageKit = require("imagekit");

var imagekit = new ImageKit({
    publicKey : "your_public_api_key",
    privateKey : "your_private_api_key",
    urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});

imagekit.createCustomMetadataField(
    {
        name: "price",
        label: "price",
        schema: {
            type: "Number",
            minValue: 1000,
            maxValue: 3000
        }
    }, 
    function(error, result) {
        if(error) console.log(error);
        else console.log(result);
    }
);

from imagekitio import ImageKit

imagekit = ImageKit(
    public_key='your_public_api_key',
    private_key='your_private_api_key',
    url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)

create_custom_metadata_fields = imagekit.create_custom_metadata_fields(options=CreateCustomMetadataFieldsRequestOptions(name="test",
                                                  label="test",
                                                  schema=CustomMetadataFieldsSchema(
                                                    type=CustomMetaDataTypeEnum.Number,
                                                    min_value=100,
                                                    max_value=200))
)

print("Create custom metadata field-", create_custom_metadata_fields, end="\n\n")

# Raw Response
print(create_custom_metadata_fields.response_metadata.raw)

# print the id of created custom metadata fields
print(create_custom_metadata_fields.id)

# print the schema's type of created custom metadata fields
print(create_custom_metadata_fiecreate_custom_metadata_fieldslds_number.schema.type)

use ImageKit\ImageKit;

$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";

$imageKit = new ImageKit(
    $public_key,
    $your_private_key,
    $url_end_point
);

$body = [
    "name" => "price",
    "label" => "Price",
    "schema" => [
        "type" => 'Number',
        "minValue" => 1000,
        "maxValue" => 3000,
    ],
];

$createCustomMetadataField = $imageKit->createCustomMetadataField($body);

echo("Create Custom Metadata Field : " . json_encode($createCustomMetadataField));

CustomMetaDataFieldSchemaObject customMetaDataFieldSchemaObject = new CustomMetaDataFieldSchemaObject();
customMetaDataFieldSchemaObject.setType("Number");
customMetaDataFieldSchemaObject.setMinValue(1000);
customMetaDataFieldSchemaObject.setMaxValue(3000);

CustomMetaDataFieldCreateRequest customMetaDataFieldCreateRequest = new CustomMetaDataFieldCreateRequest();
customMetaDataFieldCreateRequest.setName("price");
customMetaDataFieldCreateRequest.setLabel("price");
customMetaDataFieldCreateRequest.setSchema(customMetaDataFieldSchemaObject);

ResultCustomMetaDataField resultCustomMetaDataField = ImageKit.getInstance().createCustomMetaDataFields(customMetaDataFieldCreateRequest);


imagekitio = ImageKitIo::Client.new("your_private_key", "your_public_key", "your_url_endpoint")
imagekitio.create_custom_metadata_field(
  name: 'price',
  label: 'price',
  schema: {
    type: 'Number',
    minValue: 1000,
    maxValue: 3000
  }
)

resp, err := ik.Metadata.CreateCustomField(ctx, metadata.CreateFieldParam{
    Name:  "price",
    Label: "price",
    Schema: metadata.Schema{
        Type: "Number",
        MinValue: 1000,
        MaxValue: 3000,
    },
})


var imagekit = new ImageKit({
    publicKey : "your_public_api_key",
    privateKey : "your_private_api_key",
    urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
CustomMetaDataFieldCreateRequest requestModelDate = new CustomMetaDataFieldCreateRequest
{
    name = "price",
    label = "price"
};
CustomMetaDataFieldSchemaObject schemaDate = new CustomMetaDataFieldSchemaObject
{
    type = "Number",
    minValue = 1000,
    maxValue = 3000
};
requestModelDate.schema = schemaDate;
ResultCustomMetaDataField resultCustomMetaDataFieldDate = imagekit.CreateCustomMetaDataFields(requestModelDate);