Create metadata taxonomy items

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}" 
}'

client.metadata_taxonomies.create_metadata_taxonomy(
    display_name, namespace, key=taxonomy_key
)

await client.metadataTaxonomies.createMetadataTaxonomy({
  displayName: displayName,
  key: taxonomyKey,
  namespace: namespace,
} satisfies CreateMetadataTaxonomyRequestBody);

try await client.metadataTaxonomies.createMetadataTaxonomy(requestBody: CreateMetadataTaxonomyRequestBody(displayName: displayName, key: taxonomyKey, namespace: namespace))

client.getMetadataTaxonomies().createMetadataTaxonomy(new CreateMetadataTaxonomyRequestBody.Builder(displayName, namespace).key(taxonomyKey).build())

await client.MetadataTaxonomies.CreateMetadataTaxonomyAsync(requestBody: new CreateMetadataTaxonomyRequestBody(displayName: displayName, namespaceParam: namespaceParam) { Key = taxonomyKey });

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" 
} 
] 
}' 

client.metadata_taxonomies.create_metadata_taxonomy_level(
    namespace,
    taxonomy_key,
    [
        MetadataTaxonomyLevel(display_name="Continent", description="Continent Level"),
        MetadataTaxonomyLevel(display_name="Country", description="Country Level"),
    ],
)

await client.metadataTaxonomies.createMetadataTaxonomyLevel(
  namespace,
  taxonomyKey,
  [
    {
      displayName: 'Continent',
      description: 'Continent Level',
    } satisfies MetadataTaxonomyLevel,
    {
      displayName: 'Country',
      description: 'Country Level',
    } satisfies MetadataTaxonomyLevel,
  ],
);

try await client.metadataTaxonomies.createMetadataTaxonomyLevel(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: [MetadataTaxonomyLevel(displayName: "Continent", description: "Continent Level"), MetadataTaxonomyLevel(displayName: "Country", description: "Country Level")])

client.getMetadataTaxonomies().createMetadataTaxonomyLevel(namespace, taxonomyKey, Arrays.asList(new MetadataTaxonomyLevel.Builder().displayName("Continent").description("Continent Level").build(), new MetadataTaxonomyLevel.Builder().displayName("Country").description("Country Level").build()))

await client.MetadataTaxonomies.CreateMetadataTaxonomyLevelAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: Array.AsReadOnly(new [] {new MetadataTaxonomyLevel() { DisplayName = "Continent", Description = "Continent Level" },new MetadataTaxonomyLevel() { 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" 
}'  

client.metadata_taxonomies.add_metadata_taxonomy_level(
    namespace, taxonomy_key, "Region", description="Region Description"
)

await client.metadataTaxonomies.addMetadataTaxonomyLevel(
  namespace,
  taxonomyKey,
  {
    displayName: 'Region',
    description: 'Region Description',
  } satisfies AddMetadataTaxonomyLevelRequestBody,
);

try await client.metadataTaxonomies.addMetadataTaxonomyLevel(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: AddMetadataTaxonomyLevelRequestBody(displayName: "Region", description: "Region Description"))

client.getMetadataTaxonomies().addMetadataTaxonomyLevel(namespace, taxonomyKey, new AddMetadataTaxonomyLevelRequestBody.Builder("Region").description("Region Description").build())

await client.MetadataTaxonomies.AddMetadataTaxonomyLevelAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: new AddMetadataTaxonomyLevelRequestBody(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 
}'   

client.metadata_taxonomies.create_metadata_taxonomy_node(
    namespace, taxonomy_key, "Europe", 1
)

await client.metadataTaxonomies.createMetadataTaxonomyNode(
  namespace,
  taxonomyKey,
  {
    displayName: 'Europe',
    level: 1,
  } satisfies CreateMetadataTaxonomyNodeRequestBody,
);

try await client.metadataTaxonomies.createMetadataTaxonomyNode(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: CreateMetadataTaxonomyNodeRequestBody(displayName: "Europe", level: 1))

client.getMetadataTaxonomies().createMetadataTaxonomyNode(namespace, taxonomyKey, new CreateMetadataTaxonomyNodeRequestBody("Europe", 1))

await client.MetadataTaxonomies.CreateMetadataTaxonomyNodeAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: new CreateMetadataTaxonomyNodeRequestBody(displayName: "Europe", level: 1));

Additional information is available for the and of a taxonomy.

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Create metadata taxonomy items

Create a metadata taxonomy

Create metadata taxonomy levels

Add an additional level

Add nodes to the taxonomy

​Create a metadata taxonomy

​Create metadata taxonomy levels

​Add an additional level

​Add nodes to the taxonomy

Create a metadata taxonomy

Create metadata taxonomy levels

Add an additional level

Add nodes to the taxonomy