Sample - Box Platform API
POST/metadata_cascade_policies

Create metadata cascade policy

Creates a new metadata cascade policy that applies a given metadata template to a given folder and automatically cascades it down to any files within that folder.

In order for the policy to be applied a metadata instance must first be applied to the folder the policy is to be applied to.

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

3 body fields
folder_idstringrequired
The ID of the folder to apply the policy to. This folder will need to already have an instance of the targeted metadata template applied to it.
scopestringrequired
The scope of the targeted metadata template. This template will need to already have an instance applied to the targeted folder.
Allowed:globalenterprise
templateKeystringrequired
The key of the targeted metadata template. This template will need to already have an instance applied to the targeted folder. In many cases the template key is automatically derived of its display name, for example `Contract Template` would become `contractTemplate`. In some cases the creator of the template will have provided its own template key. Please [list the templates for an enterprise][list], or get all instances on a [file][file] or [folder][folder] to inspect a template's key. [list]: https://developer.box.com/reference/get-metadata-templates-enterprise [file]: https://developer.box.com/reference/get-files-id-metadata [folder]: https://developer.box.com/reference/get-folders-id-metadata

6 status codes
201Returns a new of metadata cascade policy.
idstringrequired
The ID of the metadata cascade policy object.
typestringrequired
The value will always be `metadata_cascade_policy`.
Allowed:metadata_cascade_policy
owner_enterpriseobjectoptional
The enterprise that owns this policy.
parentobjectoptional
Represent the folder the policy is applied to.
scopestringoptional
The scope of the metadata cascade policy can either be `global` or `enterprise_*`. The `global` scope is used for policies that are available to any Box enterprise. The `enterprise_*` scope represents policies that have been created within a specific enterprise, where `*` will be the ID of that enterprise.
templateKeystringoptional
The key of the template that is cascaded down to the folder's children. In many cases the template key is automatically derived of its display name, for example `Contract Template` would become `contractTemplate`. In some cases the creator of the template will have provided its own template key. Please [list the templates for an enterprise][list], or get all instances on a [file][file] or [folder][folder] to inspect a template's key. [list]: https://developer.box.com/reference/get-metadata-templates-enterprise [file]: https://developer.box.com/reference/get-files-id-metadata [folder]: https://developer.box.com/reference/get-folders-id-metadata
400Returns an error when any of the parameters are not in a valid format. * `bad_request` - Either the `scope`, `templateKey`, or `folder_id` are not in a valid format.
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.
403Returns an error when trying to apply a policy to a restricted folder, for example the root folder with ID `0`. * `forbidden` - Although the folder ID was valid and the user has access to the folder, the policy could not be applied to this folder.
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.
404Returns an error when the template or folder can not be found, or when the user does not have access to the folder or template. * `instance_tuple_not_found` - The template could not be found or the user does not have access to the template. * `not_found` - The folder could not be found or the user does not have access to the folder.
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.
409Returns an error when a policy for this folder and template is already in place. * `tuple_already_exists` - A cascade policy for this combination of `folder_id`, `scope` and `templateKey` already exists.
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
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: Returns an error when any of the parameters are not in a valid format.

  • bad_request - Either the scope, templateKey, or folder_id are not in a valid format. A 403 is returned: Returns an error when trying to apply a policy to a restricted folder, for example the root folder with ID 0.

  • forbidden - Although the folder ID was valid and the user has access to the folder, the policy could not be applied to this folder. A 404 is returned: Returns an error when the template or folder can not be found, or when the user does not have access to the folder or template.

  • instance_tuple_not_found - The template could not be found or the user does not have access to the template.

  • not_found - The folder could not be found or the user does not have access to the folder. A 409 is returned: Returns an error when a policy for this folder and template is already in place.

  • tuple_already_exists - A cascade policy for this combination of folder_id, scope and templateKey already exists. Any other status is an error: An unexpected client error.