Skip to main content
Metadata taxonomies can be created using the taxonomy’s displayName and namespace, with related items created using the namespace and taxonomy_key.

​
Create a metadata taxonomy

Create a new taxonomy that can be referenced by metadata templates. Call the API endpoint with the taxonomy’s displayName and namespace. Box will optionally generate a key if you didn’t specify one. 
curl --request POST \ 
--url "https://api.box.com/2.0/metadata_taxonomies" \ 
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
--header "Content-Type: application/json" \ 
--data '{ 
"displayName": "DISPLAY_NAME", 
"namespace": "{namespace}", 
"key": "{taxonomy_key}" 
}'

​
Create metadata taxonomy levels

Before you can add nodes, you must define the hierarchy of your taxonomy by creating one or more levels. Each level represents a hierarchical tier (for example, Country, State, City). Call the API endpoint with the taxonomy’s displayName, description, and level. 
curl --request POST \ 
--url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/levels" \ 
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
--header "Content-Type: application/json" \ 
--data '{ 
"levels": [ 
{ 
"displayName": "Continent", 
"description": "Continent Level" 
}, 
{ 
"displayName": "Country", 
"description": "Country Level" 
} 
] 
}'
Additional information is available for the and of a taxonomy.

​
Add an additional level

After defining the initial levels, you can add another level to the end of the existing hierarchy (for example, adding “City” after “Country”). Call the API endpoint with the taxonomy’s displayName and description. 

curl --request POST \ 
--url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/levels:append" \ 
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
--header "Content-Type: application/json" \ 
--data '{ 
"displayName": "Region", 
"description": "Region Description" 
}'
Additional information is available for the and of a taxonomy.

​
Add nodes to the taxonomy

With the hierarchy defined, you can begin adding nodes, which are the data in the taxonomy hierarchy. Call the API endpoint with the taxonomy’s displayName, level, and parentId. 

curl --request POST \ 
--url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes" \ 
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
--header "Content-Type: application/json" \ 
--data '{ 
"displayName": "Europe", 
"level": 1 
}'
Additional information is available for the and of a taxonomy.