Custom Metadata

Custom metadata allows you to add extra information to your files, folders, and collections in ImageKit DAM.

For example, you can store information like Brand, SKU ID, Product Category, and other relevant information for your use case. Later, you can search assets based on the values of these custom metadata fields.

Before you can set custom metadata on assets (files, folders, and collections), you need to create the fields.

Go to the Media Library settings and click on the "Custom Metadata" tab. Click on the "Add new" button to create a new field.

• Field Label: Enter the label for the field. This will be displayed in the custom metadata form on the asset details page. This is only for display purposes and can be changed later.
• Field Name: Enter the field's name. This is used during the API calls to get and set the custom metadata, and it cannot be changed later. The name _internal_original_created_datetime is reserved for the original creation date field and cannot be used.
• Field Type: Select the type of field. It can be Text, Textarea, Number, Date, Boolean, SingleSelect, MultiSelect. Based on the field type, validations are applied at the time of setting the custom metadata. The Field Type cannot be changed later.

You can set additional options based on the field type, such as its default value and whether it's a mandatory field.

You also have to add the options for SingleSelect and MultiSelect fields. For Text fields, you can also set minimum and maximum length. For Number fields, you can set minimum and maximum values. For Date fields, you can set minimum and maximum dates.

For fields of type SingleSelect and MultiSelect, you can manually enter options or import them using a CSV file.

You can add options individually by specifying:

• The data type of the option (String, Number, or Boolean).
• The value of the option.

You can also download the currently defined options in CSV format.

You can upload a CSV file to add multiple select options at once. The CSV should have the following format:

Type,Value
string,option_one
number,42
boolean,true

The uploaded options will completely override any existing list rather than values being added incrementally to the current list.

Additionally, you can export your current options in CSV format. This allows you to keep a backup of your metadata configuration, which can be useful for version control, rollback planning, or restoring options later if unintended changes occur.

You can also download the CSV template to get started with the correct structure.

When you import assets from another system (for example, Google Drive, Dropbox, or another DAM), the createdAt of each file in ImageKit is the time it was uploaded to ImageKit, not the time it was originally created. If you want to keep the original date and sort your library by it, enable the original creation date setting.

Go to the Media Library settings, open the "Custom Metadata" tab, and turn on Enable original creation date.

This creates a reserved custom metadata field in your account:

The field behaves like any other Date custom metadata field, with a few differences:

• It is managed by ImageKit. The list fields API returns it with reserved: true.
• It cannot be deleted, and the setting cannot be turned off once enabled.
• Its name is reserved. You cannot create another field with this name.
• It always appears first in the custom metadata form on the asset details page.

Set the value the same way you set any other custom metadata field, using the field name _internal_original_created_datetime and an ISO 8601 date string. You can do this at the time of upload so migrated assets carry their original date from the start, or later using the update file details API.

curl -X POST "https://upload.imagekit.io/api/v1/files/upload" \
-u your_private_api_key: \
-F 'file=@/path/to/photo.jpg' \
-F 'fileName=photo.jpg' \
-F 'customMetadata={"_internal_original_created_datetime": "2019-03-14T09:26:53.000Z"}'

You can also set or edit the value manually from the "Custom metadata" section on the asset details page.

Once the setting is enabled, a new Original Creation Date option appears in the sort menu of the media library (and in the "Sort" submenu of the right-click context menu). In the list and search assets API, use sort=ASC_ORIGINAL_CREATION_DATE or sort=DESC_ORIGINAL_CREATION_DATE.

Files that do not have a value for this field are ordered by their upload time instead. This means migrated assets with a preserved original date and assets uploaded directly to ImageKit sort together in a single timeline, so you do not need to backfill the field for every file.

The field supports the same search operators as any other Date custom metadata field. For example:

• "customMetadata._internal_original_created_datetime" < "2021-01-01" returns files originally created before 2021.
• "customMetadata._internal_original_created_datetime" NOT EXISTS returns files that have no original creation date set, which is useful for finding assets that still need to be backfilled after a migration.

Assuming you have created the necessary custom metadata fields, you can set custom metadata for files by editing the asset details or at the time of upload.

To set custom metadata for a file, go to the asset details page by double-clicking or right-clicking on the asset and selecting "Details" from the context menu.

On the asset details page, you will see a "Custom metadata" section on the right, where you can set values for the custom metadata fields.

You can set custom metadata for folders during folder creation or by editing the folder details.

To set custom metadata for a folder, go to the folder details page by double-clicking on it or right-clicking on it and selecting "Folder details" from the context menu. This will open a dialog where you can see and update the custom metadata fields.

Like folders, collections can have custom metadata associated with them at the time of creation or editing of the collection details.

ImageKit offers AI tasks to use modern LLMs to automate media management at scale. You can use these AI tasks to set custom metadata fields automatically, using natural-language instructions and predefined vocabularies. This helps eliminate manual effort and errors while automating media management at scale.

For example, you can set the metadata field "gender" for your product images using the answer to a question like “Is there a male or a female model in this image?”.

You can learn more about AI tasks for automatically setting metadata here.

You can search for assets based on custom metadata fields using advanced search. Select any defined custom metadata field and set the search criteria to filter the assets.