Box Metadata Cascade Policies API

openapi: 3.2.0
info:
  title: Box Metadata Cascade Policies API
  x-refined-note:
  - x-box-commit-hash differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Metadata Cascade Policies across 2 of this provider''s published API definitions: box-openapi-original.yml, metadata-cascade-policies-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
tags:
- name: Metadata Cascade Policies
  description: 'A metadata cascade policy describes how metadata

    instances applied to a folder should be applied

    to any item within that folder.'
  x-box-tag: metadata_cascade_policies
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\nhave access to the folder.\n\n* `not_found` - The folder could not be found or the user does not have\n  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'
      security:
      - OAuth2Security: []
    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'
      security:
      - OAuth2Security: []
    servers:
    - url: https://api.box.com/2.0
      description: Box Platform API server
  /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\nhave access to the folder.\n\n* `instance_not_found` - The policy could not be found\n* `not_found` - The folder could not be found or the user does not have\n  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'
      security:
      - OAuth2Security: []
    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\nhave access to the folder.\n\n* `instance_not_found` - The policy could not be found\n* `not_found` - The folder could not be found or the user does not have\n  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'
      security:
      - OAuth2Security: []
    servers:
    - url: https://api.box.com/2.0
      description: Box Platform API server
  /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\nwhere a metadata template already has an instance applied\nto a child.\n\n* `none` will preserve the existing value on the file\n* `overwrite` will force-apply the templates values over\n  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\nhave access to the folder.\n\n* `instance_not_found` - The policy could not be found\n* `not_found` - The folder could not be found or the user does not have\n  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'
      security:
      - OAuth2Security: []
    servers:
    - url: https://api.box.com/2.0
      description: Box Platform API server
components:
  schemas:
    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
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
        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
        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
          - 'null'
          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
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
    FileVersion--Mini:
      title: File version (Mini)
      type: object
      x-box-resource-id: file_version--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested within another resource.'
      allOf:
      - $ref: '#/components/schemas/FileVersion--Base'
      - properties:
          sha1:
            type: string
            description: The SHA1 hash of this version of the file.
            example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
    File--Mini:
      title: File (Mini)
      type:
      - object
      - 'null'
      x-box-resource-id: file--mini
      x-box-variant: mini
      description: 'A mini representation of a file, used when

        nested under another resource.'
      allOf:
      - $ref: '#/components/schemas/File--Base'
      - properties:
          sequence_id:
            allOf:
            - type:
              - string
              - 'null'
              example: '3'
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-endpoint

                to filter out user events that would have occurred before this

                identifier was read.


                An example would be where a Box Drive-like application

                would fetch an item via the API, and then listen to incoming

                user events for changes to the item. The application would

                ignore any user events where the `sequence_id` in the event

                is smaller than or equal to the `sequence_id` in the originally

                fetched resource.'
            - {}
          name:
            type: string
            description: The name of the file
            example: Contract.pdf
          sha1:
            type: string
            format: digest
            example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
            description: 'The SHA1 hash of the file. This can be used to compare the contents

              of a file on Box with a local file.'
          file_version:
            allOf:
            - $ref: '#/components/schemas/FileVersion--Mini'
            - description: The information about the current version of the file.
    FileVersion--Base:
      title: File version (Base)
      type: object
      x-box-resource-id: file_version--base
      x-box-sanitized: true
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a file version, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier that represent a file version.
          example: '12345'
        type:
          type: string
          description: '`file_version`'
          example: file_version
          enum:
          - file_version
    ConflictError:
      title: Conflict error
      type: object
      x-box-resource-id: conflict_error
      x-box-tag: uploads
      description: 'The error that occurs when a file can not be created due

        to a conflict.'
      allOf:
      - $ref: '#/components/schemas/ClientError'
      - properties:
          context_info:
            type: object
            properties:
              conflicts:
                type: array
                description: A list of the file conflicts that caused this error.
                items:
                  $ref: '#/components/schemas/FileConflict'
    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'
    FileConflict:
      title: File (Conflict)
      type: object
      x-box-sanitized: true
      x-box-resource-id: file_conflict
      x-box-tag: null
      description: A representation of a file that is used to show
      allOf:
      - $ref: '#/components/schemas/File--Mini'
      - properties:
          sha1:
            type: string
            example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
            description: The SHA1 hash of the file.
          file_version:
            $ref: '#/components/schemas/FileVersion--Mini'
    File--Base:
      title: File (Base)
      type:
      - object
      - 'null'
      x-box-resource-id: file--base
      x-box-sanitized: true
      x-box-tag: files
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a file, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: 'The unique identifier that represent a file.


            The ID for any file can be determined

            by visiting a file in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/files/123`

            the `file_id` is `123`.'
          example: '12345'
        etag:
          type:
          - string
          - 'null'
          example: '1'
          description: 'The HTTP `etag` of this file. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the file if (no) changes have happened.'
        type:
          type: string
          description: '`file`'
          example: file
          enum:
          - file
    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
            - 'null'
          prev_marker:
            description: The marker for the start of the previous page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
            type:
            - string
            - 'null'
      - properties:
          entries:
            type: array
            description: A list of metadata cascade policies
            items:
              $ref: '#/components/schemas/MetadataCascadePolicy'
    ClientError_2:
      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
    MetadataCascadePolicies_2:
      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'
  securitySchemes:
    OAuth2Security:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.box.com/api/oauth2/authorize
          tokenUrl: https://api.box.com/oauth2/token
          scopes:
            root_readonly: Read all files and folders stored in Box
            root_readwrite: Read and write all files and folders stored in Box
            manage_app_users: Provision and manage app users
            manage_managed_users: Provision and manage managed users
            manage_groups: Manage an enterprise's groups
            manage_webhook: Create webhooks programmatically through the API
            manage_enterprise_properties: Manage enterprise properties
            manage_data_retention: Manage data retention polices
            manage_legal_hold: Manage Legal Holds
externalDocs:
  description: Box Developer Documentation
  url: https://developer.box.com
x-refined-from:
- box-openapi-original.yml
- metadata-cascade-policies-openapi-original.yml