To set the field to a new value not in the field’s controlled vocabulary list, first verify that the value you want to set is contained in the field’s vocabulary.If it is not present, add it to the list. First, use the List Values endpoint to get all values belonging to the field’s vocabulary:
response = requests.get(
allowed_values = response.json()['vocabulary']
If successful, this API call will return a JSON response like this:
Since the response data is encoded as a JSON object, you can use the
json helper method provided by Requests to easily deserialize the response and access the vocabulary list:
vocabulary = response.json()['vocabulary']
After being deserialized, the list from the response can be used to check to see if the value
strawberry is already contained within the vocabulary. If not, then make another API call to add it to the list. Then you can perform your asset metadata update. Since vocabulary values are case-insensitive, you must first check if the desired value is contained in the list in a case-insensitive way. Python provides an easy way of doing this:
if not 'strawberry'.casefold() in (value.casefold() for value in vocabulary):
response = requests.post(
If the code finds that the value
strawberry is not already in the controlled vocabulary, it issues an API call to the Add Value endpoint with the new value in the request. This API call will allow you to set the
flavors field to this new value on an asset. Keep in mind that the user connected to your API token will need additional permissions in one of its assigned roles to update a field’s controlled vocabulary.
If successful, your new value will now be allowed and you can issue the original metadata update request successfully. This isn’t required to make the update, but you can verify that the new value is added to the vocabulary list by calling the List Values endpoint again:
The Add Value endpoint will return an error code if you try to add a value that already exists in the target field’s vocabulary, so checking the presence of the field using the List Values can be helpful.
Finally, issue the metadata update request:
response = requests.put(
A response with a status code of 200 indicates your vocabulary update was correct and the asset now has the right metadata applied to it.
If you are setting multiple field values that have controlled vocabulary, you may need to repeat the vocabulary update process multiple times for each field you want updated. You can also check out our other endpoints related to controlled vocabulary available in our API.