Set and remove metadata values

This section shows you how to use the Asset management API to set and remove metadata values on an asset from within your code.

Set metadata values

Before you assign metadata values, you must assign a metadata schema to the asset.

This function is a subset of the update asset endpoint.

Metadata fields

The Asset management API handles the metadata fields in specific ways. The Metadata fields document contains information about how the Asset management API handles the metadata JSON fields.


Use the following command to update the metadata schema on an asset:


<asset-id> is the asset ID of the asset being updated.


Before creating this command you need to identify the fields in the metadata schema. To find the fields in the Matrix instance, right-click on the metadata schema and select Details. Scroll down to the Fields section.

The example below sets the metadata value fields for a certain metadata schema. All metadata schemas have different values, so this is a working example only.

Add the values to the payload:

"metadata_values": {
	"keywords": {"value":"test keywords"},         (1)
	"description": {"value":"test description"},
	"right-col": {"value":"0"},
	"right-col-include": {"value":""},
	"show-heading": {"value":"1"}
1 Assign values to the fields of the metadata schema. Refer to the schema to see what data types are required.


The API response will contain:

    "id": "3435",
    "type": "page_standard",
    "attributes": {
        "name": "Home ",
        "short_name": "Home"
    "status": "under_construction",
    "version": "0.0.3",
    "created": {
        "date_time_unix": 1646800343,
        "user_id": "1227"
    "updated": {
        "date_time_unix": 1662599482,
        "user_id": "1227"
    "published": null,
    "status_changed": {
        "date_time_unix": 1646800343,
        "user_id": "1227"
    "metadata_schemas": [
            "id": "5190",
            "granted": true,
            "cascades": true
    "metadata_values": {
        "keywords": {
            "type": "metadata_field_text",      (1)
            "value": [
                "test keywords"
        "description": {
            "type": "metadata_field_text",      (2)
            "value": "test description"
        "right-col": {
            "type": "metadata_field_select",    (3)
            "value": "0"
        "right-col-include": {
            "type": "metadata_field_related_asset",  (4)
            "value": ""
        "show-heading": {
            "type": "metadata_field_select",     (5)
            "value": "1"
    "paint_layouts": {
        "asset_level": null,
        "asset_level_override": null,
        "url_based": {
            "": {
                "regular": null,
                "override": null
        "user_defined": {
            "": null
    "web_paths": [
    "urls": [
            "path": "",
            "schemes": [
    "external_id": ""
1 Value from the payload shown in the keywords field.
2 Value from the payload shown in the description field
3 Default values from payload.
4 Default values from payload.
5 Default values from payload.

Remove metadata values

To remove metadata values from an asset, PATCH the property with a value of null. In the following example, the value of "description" is being removed.

PATCH /__management_api/v1/assets/123456 HTTP/1.1
Host: matrix.labs.squiz.test
Authorization: Bearer ... change me ...
Content-Type: application/json
Content-Length: 62

"metadata_values": {
"description": null

Be aware that in the front end, the property might still have a value that is derived from the default value of the field defined in the schema. Read Metadata fields - Use default for more information about the Use Default option.

Only fields which are a part of an applied metadata schema can be set and unset.