The Box Metadata Cascade Policies API allows configuration of policies that automatically apply metadata templates from a parent folder to all files and subfolders within it, ensuring consistent metadata across content hierarchies.
openapi: 3.1.0
info:
title: Box Metadata Cascade Policies API
description: Needs a description.
paths:
/metadata_cascade_policies:
get:
operationId: get_metadata_cascade_policies
summary: Box List metadata cascade policies
tags:
- Metadata Cascade Policies
x-box-tag: metadata_cascade_policies
x-box-sanitized: true
description: |-
Retrieves a list of all the metadata cascade policies
that are applied to a given folder. This can not be used on the root
folder with ID `0`.
parameters:
- name: folder_id
in: query
required: true
schema:
type: string
example: '31232'
description: >-
Specifies which folder to return policies for. This can not be used
on the
root folder with ID `0`.
- name: owner_enterprise_id
in: query
schema:
type: string
example: '31232'
description: |-
The ID of the enterprise ID for which to find metadata
cascade policies. If not specified, it defaults to the
current enterprise.
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
in: query
required: false
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
schema:
type: string
- name: offset
description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
default: 0
responses:
'200':
description: Returns a list of metadata cascade policies
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataCascadePolicies'
'400':
description: >-
Returns an error when any of the parameters are not in a valid
format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: >-
Returns an error when the folder can not be accessed. This error
often
happens when accessing the root folder with ID `0`.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returns an error when the folder can not be found or the user does
not
have access to the folder.
* `not_found` - The folder could not be found or the user does not
have
access to the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_metadata_cascade_policies
summary: Box Create metadata cascade policy
tags:
- Metadata Cascade Policies
x-box-tag: metadata_cascade_policies
x-box-sanitized: true
description: |-
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.
requestBody:
content:
application/json:
schema:
type: object
required:
- folder_id
- scope
- templateKey
properties:
folder_id:
type: string
description: >-
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.
example: '1234567'
scope:
description: >-
The scope of the targeted metadata template. This template
will
need to already have an instance applied to the targeted
folder.
example: enterprise
type: string
enum:
- global
- enterprise
templateKey:
type: string
example: productInfo
description: >-
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]: e://get-metadata-templates-enterprise
[file]: e://get-files-id-metadata
[folder]: e://get-folders-id-metadata
responses:
'201':
description: Returns a new of metadata cascade policy
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataCascadePolicy'
'400':
description: >-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: >-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: >-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_cascade_policies/{metadata_cascade_policy_id}:
get:
operationId: get_metadata_cascade_policies_id
summary: Box Get metadata cascade policy
tags:
- Metadata Cascade Policies
x-box-tag: metadata_cascade_policies
x-box-sanitized: true
description: Retrieve a specific metadata cascade policy assigned to a folder.
parameters:
- name: metadata_cascade_policy_id
description: The ID of the metadata cascade policy.
example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7
in: path
required: true
schema:
type: string
responses:
'200':
description: Returns a metadata cascade policy
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataCascadePolicy'
'404':
description: >-
Returns an error when the policy can not be found or the user does
not
have access to the folder.
* `instance_not_found` - The policy could not be found
* `not_found` - The folder could not be found or the user does not
have
access to the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_metadata_cascade_policies_id
summary: Box Remove metadata cascade policy
tags:
- Metadata Cascade Policies
x-box-tag: metadata_cascade_policies
x-box-sanitized: true
description: Deletes a metadata cascade policy.
parameters:
- name: metadata_cascade_policy_id
description: The ID of the metadata cascade policy.
example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the policy
is successfully deleted.
'404':
description: >-
Returns an error when the policy can not be found or the user does
not
have access to the folder.
* `instance_not_found` - The policy could not be found
* `not_found` - The folder could not be found or the user does not
have
access to the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_cascade_policies/{metadata_cascade_policy_id}/apply:
post:
operationId: post_metadata_cascade_policies_id_apply
summary: Box Force-apply metadata cascade policy to folder
tags:
- Metadata Cascade Policies
x-box-tag: metadata_cascade_policies
x-box-sanitized: true
description: >-
Force the metadata on a folder with a metadata cascade policy to be
applied to
all of its children. This can be used after creating a new cascade
policy to
enforce the metadata to be cascaded down to all existing files within
that
folder.
parameters:
- name: metadata_cascade_policy_id
required: true
in: path
schema:
type: string
description: The ID of the cascade policy to force-apply.
example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7
requestBody:
content:
application/json:
schema:
type: object
required:
- conflict_resolution
properties:
conflict_resolution:
type: string
enum:
- none
- overwrite
description: >-
Describes the desired behavior when dealing with the
conflict
where a metadata template already has an instance applied
to a child.
* `none` will preserve the existing value on the file
* `overwrite` will force-apply the templates values over
any existing values.
example: none
responses:
'202':
description: >-
Returns an empty response when the API call was successful. The
metadata
cascade operation will be performed asynchronously.
The API call will return directly, before the cascade operation
is complete. There is currently no API to check for the status of
this
operation.
'404':
description: >-
Returns an error when the policy can not be found or the user does
not
have access to the folder.
* `instance_not_found` - The policy could not be found
* `not_found` - The folder could not be found or the user does not
have
access to the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
MetadataCascadePolicies:
title: Metadata cascade policies
type: object
x-box-resource-id: metadata_cascade_policies
x-box-tag: metadata_cascade_policies
description: A list of metadata cascade policies.
allOf:
- type: object
description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
nullable: true
prev_marker:
description: The marker for the start of the previous page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
type: string
nullable: true
- properties:
entries:
type: array
description: A list of metadata cascade policies
items:
$ref: '#/components/schemas/MetadataCascadePolicy'
ClientError:
title: Client error
type: object
x-box-resource-id: client_error
description: A generic error
properties:
type:
description: error
example: error
type: string
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
example: 400
type: integer
format: int32
nullable: false
code:
description: A Box-specific error code
example: item_name_invalid
type: string
enum:
- created
- accepted
- no_content
- redirect
- not_modified
- bad_request
- unauthorized
- forbidden
- not_found
- method_not_allowed
- conflict
- precondition_failed
- too_many_requests
- internal_server_error
- unavailable
- item_name_invalid
- insufficient_scope
message:
description: A short message describing the error.
example: Method Not Allowed
type: string
nullable: false
context_info:
description: |-
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.
type: object
nullable: true
properties:
message:
type: string
description: More details on the error.
example: Something went wrong.
help_url:
description: A URL that links to more information about why this error occurred.
example: >-
https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
type: string
nullable: false
request_id:
description: |-
A unique identifier for this response, which can be used
when contacting Box support.
type: string
example: abcdef123456
nullable: false
MetadataCascadePolicy:
title: Metadata cascade policy
type: object
x-box-resource-id: metadata_cascade_policy
x-box-tag: metadata_cascade_policies
description: >-
A metadata cascade policy automatically applies a metadata template
instance
to all the files and folders within the targeted folder.
required:
- id
- type
properties:
id:
type: string
example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7
description: The ID of the metadata cascade policy object
type:
type: string
description: '`metadata_cascade_policy`'
example: metadata_cascade_policy
enum:
- metadata_cascade_policy
owner_enterprise:
type: object
description: The enterprise that owns this policy.
properties:
type:
type: string
example: enterprise
description: '`enterprise`'
enum:
- enterprise
id:
type: string
example: '690678'
description: The ID of the enterprise that owns the policy.
parent:
type: object
description: Represent the folder the policy is applied to.
properties:
type:
type: string
example: folder
description: '`folder`'
enum:
- folder
id:
type: string
example: '1234567'
description: The ID of the folder the policy is applied to.
scope:
type: string
description: >-
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.
example: enterprise_123456
templateKey:
type: string
example: productInfo
description: |-
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]: e://get-metadata-templates-enterprise
[file]: e://get-files-id-metadata
[folder]: e://get-folders-id-metadata
tags:
- name: Metadata Cascade Policies