Developer guide for importing custom metadata using user-defined fields to enhance dataset search and filtering.
Add custom metadata like temperature, timestamps, and tools to images via the API. This will help you improve dataset filtering and searchability.
This guide explains how to import custom metadata to your datasets via the API. Each metadata field is user-defined and supports one of several data types.
Custom metadata is associated at the image level and is immutable once uploaded.
To import custom metadata in Visual Layer, you must:
All API requests in the Cloud environment require authentication using a valid API token.
string
float
datetime
(UTC format)enum
(single or multi-select)link
(URL)Each upload task is used to add one metadata field only. If you want to add multiple fields, you’ll need to create a separate task for each - and make sure each field has a unique field_name.
READY
state.task_id
.To upload custom metadata, you’ll need to associate values with the correct media items in your dataset.
Each entry must include:
media_id
– a unique identifier generated by Visual Layer for each imagevalue
– the metadata value for that imagemedia_id
s:media_id
assigned to each media item.media_id
s to match your custom metadata with the corresponding images.Your custom metadata JSON file should follow this structure:
Click here for the full explanation on how to create the JSON file.
Each declaration creates a new upload task for a single field. You can repeat the process to add more fields—just ensure each field_name
is unique within the dataset.
string
, float
, datetime
, link
enum
is_multi = false
is_multi = true
The is_multi flag determines whether each image can have one or multiple values from the enum options.
is_multi: false
(Each image can have only one value.)is_multi: true
(Each image can have multiple values.)Make sure to save the task_id
- you’ll need it for the next steps in the flow.
Use the received task_id
to upload your metadata file. Each entry must include a valid media_id
and a value
matching the declared field type.
string
, float
, datetime
, link
enum
- when is_multi = false
enum
- when is_multi = true
Track progress and get visibility into errors (e.g., type mismatches).
At this stage, uploaded metadata is immutable - meaning it cannot be edited or replaced once submitted.
If any errors occur during upload, only the problematic rows will fail; all valid rows will proceed successfully.
You can always declare a new field_name
and reupload the data.
Support for updating existing metadata will be added in the future.
Returns all declared fields and types.
Response:
Once your custom metadata is uploaded successfully, the declared field_name
will automatically appear in the Filters section of the UI.
You can then filter dataset images using these fields — just like any other built-in filter.
>
, <
, =
)BETWEEN start_date AND end_date
)Filtering behavior may vary depending on the field type and the selected operator.