---
title: "Create metadata cascade policy"
method: POST
path: "/metadata_cascade_policies"
tags: ["Metadata cascade policies"]
---

# Create metadata cascade policy

`POST /metadata_cascade_policies`

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.

## Request body

- object
  - `folder_id` string, required — 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.
  - `scope` 'global' | 'enterprise', required — The scope of the targeted metadata template. This template will need to already have an instance applied to the targeted folder.
  - `templateKey` string, required — 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

## Response `201`

Returns a new of metadata cascade policy.

- MetadataCascadePolicy — A metadata cascade policy automatically applies a metadata template instance to all the files and folders within the targeted folder.
  - `id` string, required — The ID of the metadata cascade policy object.
  - `type` 'metadata_cascade_policy', required — The value will always be `metadata_cascade_policy`.
  - `owner_enterprise` object — The enterprise that owns this policy.
    - `type` 'enterprise' — The value will always be `enterprise`.
    - `id` string — The ID of the enterprise that owns the policy.
  - `parent` object — Represent the folder the policy is applied to.
    - `type` 'folder' — The value will always be `folder`.
    - `id` string — The ID of the folder the policy is applied to.
  - `scope` string — 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.
  - `templateKey` string — 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

## Other responses

- `400` — 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.
- `403` — 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.
- `404` — 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.
- `409` — 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.
- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/versions/ba8f087e1a4d/schema)