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

Create a metadata taxonomy node

Creates a new node in a metadata taxonomy. Provide displayName and level in the request body, and optionally provide parentId to place the node beneath an existing parent.

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

2 parameters · 3 body fields
namespacestringrequired
The namespace containing the metadata taxonomy where you want to create the node.
taxonomy_keystringrequired
The key identifying the metadata taxonomy where you want to create the node.

Metadata taxonomy node details used to create a node in the taxonomy.

displayNamestringrequired
The display name of the taxonomy node.
levelintegerrequired
The level of the taxonomy node.
parentIdstringoptional
The identifier of the parent taxonomy node. Omit this field for root-level nodes.

4 status codes
201Returns the created metadata taxonomy node, including its identifier, display name, level, and ancestor information when applicable.
idstringrequired
A unique identifier of the metadata taxonomy node.
displayNamestringrequired
The display name of the metadata taxonomy node.
levelintegerrequired
An index of the level to which the node belongs.
parentIdstringoptional
The identifier of the parent node.
nodePatharray<string>optional
An array of identifiers for all ancestor nodes. Not returned for root-level nodes.
ancestorsarray<MetadataTaxonomyAncestor>optional
An array of objects for all ancestor nodes. Not returned for root-level nodes.
400Returned when the request parameters or body are invalid, including when a required node field is missing.
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 lacks access to the provided 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.
defaultReturned when an unexpected client error occurs.
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 namespace, taxonomy_key, or the request body is invalid, including when displayName or level is missing. A 403 is returned when the authenticated user does not have permission to modify the metadata taxonomy or lacks access to the provided namespace.