How do I update or add a controlled vocabulary metadata value through the DAM API?

First, set up some variables for authentication headers in order to make requests to the API:

auth_token = 'YOUR_TOKEN_HERE'
headers = {
   'Authorization': f"Bearer {auth_token}"
}

In this example, we are using bearer authorization as described in the API documentation. Then, a dictionary is created containing header names mapped to header values to make it easy to pass the correct authorization header in our API requests without repeating ourselves. In the code examples, you will need to replace YOUR_TOKEN_HERE with your own API token for your DAM.

Now that authentication is in place, you can start making API calls. In our example scenario, you want to update the metadata on an asset in your DAM programmatically, so start with this basic example:

import requests

asset_id = 'YOUR_ASSET_ID'

response = requests.put(
 f"https://api.widencollective.com/v2/assets/{asset_id}/metadata",
 headers=headers, # pass in auth header created earlier
 json={
   'fields': { # metadata values we want to set
     'description': ['A delicious cake.'],
     'flavors': ['vanilla', 'strawberry']
   }
 }
)
response.raise_for_status()

Here we are importing the popular Requests library for Python in order to issue HTTP requests to the API. There are many other HTTP clients that can be used as well, but Requests has a simple interface that  helps to demonstrate the program logic concisely. Make an HTTP PUT request by calling the requests.put function, and specify a JSON request body using the json parameter. Finally, call the raise_for_status method on the response to ensure an exception is raised if a non-successful HTTP status code is returned by the API; otherwise Requests will ignore failed API calls. Check the Requests documentation for more information on how to use Requests.

In the example above, we are issuing a PUT request to the Update Metadata endpoint to set new values for both a description and a flavors field. These field names refer to the display key of the metadata fields you want to set. You can see display keys using the Fields Viewable endpoint. These will vary within your own DAM depending on how your metadata fields are configured.

If both of these fields were free text field types then this API call would be successful, and the asset metadata would be updated. Other field types have more strict validation on the values they allow, so for this example, the flavors field is set up to be a checkbox group field. This field type has controlled vocabulary and allows the user to select zero, one, or multiple values to apply to an asset, as long as all the values are listed in the field’s controlled vocabulary.

This field is initially set up containing only the values vanilla and chocolate in its controlled vocabulary. Since strawberry is not in that list and is in the request, you will get the following error response back from the API when you try to make this call:

{
 "error": true,
 "response_code": 404,
 "error_message": "The metadata value '[vanilla, strawberry]' is not valid for this Checkbox Group field. One or more of the values are not in the metadata field's vocabulary."
}

This error is returned because the API validated the values given against the flavors field’s controlled vocabulary and found that the value strawberry was not approved for that field. This is a benefit of controlled vocabulary fields, as it allows DAM admins to ensure that only approved values are set for the field to enforce consistent naming across the site, regardless of whether the metadata comes from a user or an API integration.

However, you might not always want this behavior in an integration. If you are updating metadata from an external system that holds the source of truth for a particular metadata field, then you may want to add new values to the controlled vocabulary list automatically.