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