Sample - Box Platform API
POST/metadata_taxonomies/{namespace}/{taxonomy_key}/levels

Create metadata taxonomy levels

Creates new hierarchical levels in a metadata taxonomy. Identify the taxonomy with namespace and taxonomy_key, then submit an array of level definitions containing display names, descriptions, and level indexes. The response returns all levels currently defined for the taxonomy.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 parameters · 3 body fields
namespacestringrequired
The namespace associated with the metadata taxonomy.
taxonomy_keystringrequired
The key of the metadata taxonomy to add levels to.

An array of metadata taxonomy level definitions to create.

displayNamestringoptional
The display name of the level as it is shown to the user.
descriptionstringoptional
A description of the level.
levelintegeroptional
An index of the level within the taxonomy. Levels are indexed starting from 1.

4 status codes
201Returns an array containing all levels in the metadata taxonomy, including the newly created levels.
entriesarray<MetadataTaxonomyLevel>optional
An array of all taxonomy levels.
400Returned when the request parameters or body are invalid.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
403Returned when the authenticated user does not have permission to modify the metadata taxonomy or access the specified namespace.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned when the request parameters or body are invalid. A 403 is returned when the authenticated user cannot modify the taxonomy or access the specified namespace. Each level's level value identifies its position in the taxonomy, with indexing starting at 1.