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 POST /metadata_taxonomies 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 POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels 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 namespace and taxonomy_key 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 POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels:append 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 namespace and taxonomy_key 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 POST /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes 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 namespace and taxonomy_key of a taxonomy.