Sample - Box Platform API
POST/metadata_taxonomies

Create metadata taxonomy

Creates a new metadata taxonomy that can be used in metadata templates.

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

3 body fields
keystringoptional
The taxonomy key. If it is not provided in the request body, it will be generated from the `displayName`. The `displayName` would be converted to lower case, and all spaces and non-alphanumeric characters replaced with underscores.
displayNamestringrequired
The display name of the taxonomy.
namespacestringrequired
The namespace of the metadata taxonomy to create.

4 status codes
201The schema representing the metadata taxonomy created.
idstringrequired
A unique identifier of the metadata taxonomy.
keystringoptional
A unique identifier of the metadata taxonomy. The identifier must be unique within the namespace to which it belongs.
displayNamestringrequired
The display name of the metadata taxonomy. This can be seen in the Box web app.
namespacestringrequired
A namespace that the metadata taxonomy is associated with.
levelsarray<MetadataTaxonomyLevel>optional
Levels of the metadata taxonomy.
400Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are 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 user does not have the permission to create the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have 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.
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: Returned if the request parameters or body is not valid.

  • bad_request when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. A 403 is returned: Returned when the user does not have the permission to create the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. Any other status is an error: An unexpected client error.